# Platform {#en_platform_about}

A section with the general information about the payment platform, its structure, and operation.

This section contains general information about working with the Ecommpay payment platform. Use it to understand the fundamentals of how the platform works and how to establish the interaction with the platform via one or several interfaces.For example, if you need to accept payments with the use of the payment form by Ecommpay, issue refunds via an API, and have your employees monitor information via an online dashboard panel, you can use this section to learn about interfaces and components that fit the needs of your company, general steps of integration with the platform, workflows of specific payment types and their statuses, data signing, and different ways to check payment information. Based on the information you have learned, you can set up the most fitting solutions for your business.

This section includes the following information:

-   [Overview](en_platform_overview.md)—an introductory article with the information about the payment platform, its interfaces, components and key capabilities.
-   [Integration](en_platform_registration.md)—articles about the general procedure of integrating with the platform and the specialised solutions for specific categories of merchants.
-   [Payment processing](en_platform_payment_model.md)—articles about payment types that can be processed via the platform, workflows and possible statuses of these payments and operations performed within them.
-   [Signature generation and verification](en_platform_signature.md)—information about data signing and verification required in order to work with any of the program interfaces of the platform.
-   [Handling payment processing information](en_platform_payment_information.md)—information about receiving and processing data on payments executed via the platform so that the merchant can analyse, monitor, and respond to payment processing activity.

In addition to the information covered in this section, in order to learn about the platform's capabilities and interacting with it, you can use the articles about working with specific interfaces and components of the platform in the **Tools** section, information [on risk management](en_dbl_risks.md)and [chargebacks](en_faq_chargebacks.md), answers to [FAQs](en_faq.md), and other articles of this documentation portal. Along with that, if you have any questions, you can contact your Ecommpay account manager and the technical support.

-   **[Overview](en_platform_overview.md)**  
An article with the introductory information about the payment platform, its interfaces, components, and key capabilities.
-   **[Integration](en_platform_registration.md)**  
Articles about the general procedure of integrating with the platform and the specialised solutions for specific categories of merchants.
-   **[Payment processing](en_platform_payment_model.md)**  
Articles about payment types that can be processed via the platform, workflows and possible statuses of these payments and operations performed within them.
-   **[Signature generation and verification](en_platform_signature.md)**  
An article about signing data in API requests, responses, and callbacks and verifying signatures in order to ensure secure data exchange with the payment platform.
-   **[Handling payment processing information](en_platform_payment_information.md)**  
Articles about receiving and processing data about payments executed via the platform in order to analyse, monitor, and respond to payment processing activity.



---

# Overview {#en_platform_overview}

An article with the introductory information about the payment platform, its interfaces, components, and key capabilities.

## Introduction {#section_cb3_crm_vzb .section}

The Ecommpay payment platform allows you to processdifferent types of paymentsalmost everywhere in the world with support for a wide range ofcurrencies,payment methods, and payment scenarios. It relies on exceptionally thought out and organised processes and high-performance computing resources, which, from the technical standpoint, makes the platform an advanced information system—state of art, high-integrity, and efficient. Thanks to this, all required actions in the platform are executed in milliseconds while merchants and their customers can expand ranges of services they offer and enjoy high quality performance of the platform.

![](images/ecommpay/en_platform_functional.svg "Processing payments via main interfaces of the platform")

At the same time, the scalability of the Ecommpay payment platform, with its plethora of capabilities and use options, leads to a wide range of ways of how merchants can work with it. This makes the interaction with the platform convenient and efficient, but it can also be challenging, for example, when the merchant needs to find the most optimal solution that fits the merchant's business needs.To make sure that your questions about working with the platform are answered, you can use this documentation portal\(including the documentation survey on the home page\). You can also contact your account manager and the technical support.

## Key concepts: projects and payments {#section_dlt_rc1_xzb .section}

While the integration workflows and scenarios can vary, working with the platform starts with registering in it a specific merchant and a project of interaction between the merchant's web service and the platform. Along with that, the project is assigned a permanent identifier, and a wide range of customisable properties is set up for it. These properties include support for payment methods and currencies, as well as various parameters that determine payment processing workflows and procedures. Once this has been done \(and only then\), it is possible to process payments in the project of the merchant, with payments defined as compound actions performed to carry out transfers of funds between merchants and their customers.

The number of projects set up for one merchant can vary. Most often, one project is enough, but in certain cases, the number of projects can increase. As a rule, the optimal number of projects is determined by the Ecommpay specialists on the basis of the merchant's business specifics and goals. More importantly, this number can be changed in the course of collaboration with Ecommpay.

As for payments, they can include a different number of operations that have to do with the transfer of funds.For example, within one payment, first a purchase takes place, and then—a full or partial refund. As another example, a series of regularly recurring debit operations for a fixed amount is processed within one subscription payment. And so on. Available payment types, operations, and their statuses are strictly defined in the platform and are described in this section. Meanwhile, as you read, it is important to keep in mind that payments are processed within projects and can include a varying number of operations.

Overall, this logic—that to work with the platform, the merchant's project needs to be registered and that within these registered projects payments are processed and include a certain number of operations—can be considered the basis for understanding the interaction with the platform.It applies to all actions in the Ecommpay platform starting from test integrations and processing test payments and ending with distributing permissions for accessing information about individual payments and operations by individual projects.

## Tools: interfaces and components {#section_itw_sg1_xzb .section}

To work with the Ecommpay payment platform, you and your web service can use specialised interfaceseach of which allows you to achieve specific business goals. These interfaces include:

-   [Payment Page](en_PP_about.md)—the payment form developed by Ecommpay that is invoked via an API and allows you to process purchasesand perform other actionswith the use of various payment methods.
-   [Gate](en_Gate_Integration_About.md)—the payment API that provides you with the largest range of capabilities for working with paymentsof all supported typesand payment methods and implies that your web service utilises in-house UI solutions.
-   [Dashboard](en_dbl_about.md)—the web interface for your employees that allows them to configure projects,including the interface of Payment Page, and to monitor the state of all payments\(processed and in-progress\), to manage their execution, and to initiate various payments and operations.
-   [Data API](en_dbl_api_protocol.md)—an API that allows you to retrieve information about operations, chargebacks, and balances for the projects in use. It also helps you establish the workflow of monitoring and analysing payment processing outside of Dashboard\(for example, in the external BI system\).

At the same time, for more convenient ways of working with the platform, you can also use additional components—self-contained software products that can be implemented in the web service to achieve specific goals.These components include:

-   [SDKs for mobile applications](en_sdk_overview.md)—software development kits \(SDKs\) to integrate Android and iOS applications with the Ecommpay payment platform.Merchants can use a special version of Payment Page or their own user interface.
-   [Integration modules for CMS](en_CMS.md)—plug-ins\(certain systems refer to them as *cartridges*\) that help connect the merchant's web service created in a popular CMS system or a specialised ecommerce platform to the Ecommpay platform.
-   [SDKs for data signing](en_sdk_overview.md#section_vcj_5zv_tvb)—language-specific specialised software development kits \(SDKs\) that facilitate signing data sent in requests and verifying data integrity in responses and callbacksin the API interaction with the platform.

Together these interfaces and components serve as tools that allow merchants to work with the platform. In different cases, this work can be organised with the use of a different number of tools.Thus, sometimes a task can be completed by using one interface \(Dashboard\), and in other cases, using SDKs formobile applications anddata signing,Payment Page, Gate, Dashboard, and the Data API can be more effective. As a rule, the key factors affecting the choice of this or that tool include payment types and user scenarios, web service development methods, and the preferred ways to organise work with the platform. These factors, for example, are taken into account in the responses that are given as a result of taking our survey available on the home page. Similarly, when the Ecommpay specialists help you find the most optimal solutions for your business, these factors are taken into consideration as well.

## Capabilities and procedures {#section_m2q_l22_xzb .section}

Capabilities of the Ecommpay platform are diverse and, more importantly, are supported to a varying degree with different tools.Thus, Payment Page allows you to initiate authorisation holds as part of performing two-step purchases, but to withdraw or release the held funds you need to use Gate or Dashboard \(or set up automatic *capture* operations after a specific time lag\). This is true about each tool and, therefore, it is important to keep in mind that:

-   Each tool of the platform is intended for achieving its own specific set of goals.
-   Achieving any applicable goal can be accomplished with the use one or several tools.
-   To ensure efficient use of platform, it is often beneficial to combine its capabilities and tools according to the specifics of goals you are working to accomplish.

It can also be added that from the technical standpoint supporting any capability implies performing certain procedures, and for different tools these procedures, this way or another, will have to do with the configuration of the web service, the customers, or employees of the merchant. For example, the 3‑D Secure authentication of the customer used in purchase processing does not require active participation of the web service when processing involves payment interfaces of Ecommpay \(only customer actions are required\). However, when processing occurs via Gate, the web service is required to perform a whole number of actions \(accepting and processing data and redirecting the customer\). These aspects of using different tools and capabilities are worth keeping in mind.

The capabilities of the platform can be divided into several groups functionality-wise:

-   Processing paymentsof different types\(or performing essential payment procedures\)—a group of capabilities that ensure basic functions of the platform.

    These capabilities allow processing purchasesof different types\(in one or two steps, one time or with different kinds of repetition\), payouts, and 'nominal' payments for verifying payment instrumentswith the use of various payment methods.

-   Performing auxiliary payment procedures—a group of capabilities that ensure compliance with the requirements imposed on payment processing in specific cases.

    These capabilities allow executing procedures that are not always required but mandatory in certain cases and situations due to the requirements imposed by payment systems, regional specifics, or other conditions.As a rule, these procedures include additional customer verification, 3‑D Secure and AVS checks being the prime example.

-   Expanding the scope of payment scenarios\(or using additional capabilities\)—a group of capabilities that ensure flexible configuring of the integration for specific situations and business needs to improve payment services.

    These capabilities allow performing procedures that can be considered complementary enhancements: they are not required to process payments, but they facilitate the variability of payment scenarios, boost payment interfaces conversion and payment acceptance rates,strengthen fraud preventionand increase customer loyalty.

-   Managing payment solutions—a group of capabilities that allow merchants to manage payment solutions but do not affect payment processing per se.

    These capabilities are intended for simplifying the use of procedures for monitoring and analysing payment information,handling chargebacks, managing balances and other processes important for maintaining merchants' business operations.


Together, these groups of capabilities ensure full functionality and scalability of the platform for merchants.

**Parent topic:**[Platform](en_platform_about.md)



---

# Integration {#en_platform_registration}

Articles about the general procedure of integrating with the platform and the specialised solutions for specific categories of merchants.

Integration with the Ecommpay payment platform requires solving a number of organisational, legal, and technical issues. To ensure efficiency of the integration process, Ecommpay constantly develops different solutions, both for general use and specialised.

-   [General procedure](en_platform_registration_workflow.md)—an individualised approach to integration; the specialists of Ecommpay are in constant communication with the representatives of the merchant to ensure all questions are solved quickly and efficiently. It is used for mid-market and large enterprises that meet the requirements of Ecommpay to their clients.
-   [Ecommpay for Small Businesses](en_platform_onboarding_for_small_businesses.md)—a partially automated approach; includes self-service onboarding of the merchant and the subsequent technical integration without the involvement of an account manager assigned by Ecommpay. It is used for small businesses in the UK that meet the eligibility criteria of Ecommpay.

-   **[General procedure](en_platform_registration_workflow.md)**  
An article about the general procedure of integrating with the platform used for mid-market and large enterprises that meet the requirements of Ecommpay to their clients.
-   **[Onboarding via Ecommpay for Small Businesses in the UK](en_platform_onboarding_for_small_businesses.md)**  
An article about a specialised procedure of integrating with the platform used for small businesses in the UK that meet the eligibility criteria of Ecommpay.

**Parent topic:**[Platform](en_platform_about.md)



---

# General procedure {#en_platform_registration_workflow}

An article about the general procedure of integrating with the platform used for mid-market and large enterprises that meet the requirements of Ecommpay to their clients.

Depending on the tools that will be used for working with the platform, the actual steps and the order in which they should be taken are going to varysignificantly. In general case, you need:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If your company is not yet a client of Ecommpay and has not obtained the project identifier and a secret key for interacting with the platform, submit [an application](https://ecommpay.com/apply-now/).Once the application receives its initial approval, you will have the contact information of the Ecommpay specialists in charge of your onboarding.
    2.  For processing payments made with Visa and Mastercard, provide your Ecommpay account manager with the documents of compliance with [the PCI DSS requirements](en_faq_integration.md#fig_fgk_rgs_4nb). The following documents are required:
        -   From all merchants—[the ASV scan](en_glossary.md) report.

            ASV scanning must be performed by the authorised scanning service providers \(PCI SSC Approved Scanning Vendor, ASV\) quarterly and after every significant change in the network infrastructure.The Ecommpay merchants can select these providers on their own and, if relevant, involve a provider that is in partnership with Ecommpay. To have the scanning services via the partner arranged, contact your account manager.

        -   From the merchants processing over 6 million operations annually \(Level 1\)—the Attestation of Compliance, AOC.
        -   From the merchants processing up to 6 million operations annually \(Levels 2, 3, and 4\)—[the Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment), SAQ.

            With questions on completing the questionnaire, contact your Ecommpay account manager.

    3.  Coordinate the procedures of integrating with the payment platform, testing\(including testing card payments and some alternative payment methods\), and launching the functionality with the Ecommpay technical support specialists.
2.  Complete preliminary technical tasksby using either your in-house resources or the specialised components offered by Ecommpay if needed.Make sure to implement signature generation and callback response processing on the server side of the web service.
3.  Test the required actions and launch the integration solution in coordination with the Ecommpay technical support.

    Upon testing and monitoring, when the required actions are performed correctly, the Ecommpay technical support specialists will switch to interacting with the web service in the full-time support mode.


**Parent topic:**[Integration](en_platform_registration.md)



---

# Onboarding via Ecommpay for Small Businesses in the UK {#en_platform_onboarding_for_small_businesses}

An article about a specialised procedure of integrating with the platform used for small businesses in the UK that meet the eligibility criteria of Ecommpay.

**Parent topic:**[Integration](en_platform_registration.md)

## Introduction {#en_platform_onboarding_for_small_businesses_overview}

Integration with any payment platform requires solving a lot of organisational, legal, and technical issues. To simplify this process, Ecommpay offers a number of specialised solutions includingEcommpay for Small Businesses—a solution that allows small businesses registered in the United Kingdom and previously without an account with Ecommpay to start working with the payment platform.

Ecommpay for Small Businesses is an automated onboarding solution that allows you to sign up and submit all necessary information, carries out all necessary verification and compliance checks, following which you can sign an agreement via Dashboard, without the need for continuous direct interaction with the Ecommpay specialists.Ecommpay for Small Businesses is intended for clients whose business is compact enough that it does not require full scale onboarding with the involvement of account managers and other specialists. As a self-service onboarding solution, it provides small businesses with an access to a range of functional capabilities and key payment methods, which allows for efficient operation and development of their payment services.

To start onboarding via Ecommpay for Small Businesses, the company must meet the following eligibility criteria:

|Country of registration|the United Kingdom|
|Nature of business|included in the Ecommpay approved list of eligible low risk industry sectors|
|Number of employees|fewer than 10|
|Annual turnover|up to £1.5 million|
|Trading history|at least 12 months after the company was registered with Companies House|

-   Advertising
-   Camera and Photographic Supply Stores
-   Children Clothes
-   Department Stores
-   Digital Entertainment
-   Electronic Stores
-   Family Clothes
-   Furniture and other made-to-order goods
-   Groceries
-   Gym memberships
-   Hobby, Toy, and Game Shops
-   Home Furnishings
-   Home Supply
-   Household Utilities
-   Job listings
-   Men Clothes
-   Online Education and Training
-   Pet Shops, Pet Foods and Supplies Stores
-   Product Subscriptions
-   Professional Digital Services
-   Reviews and Recommendations
-   Shipping, Delivery and Logistics
-   Space Hire \(Hall, Meeting Room, Office, etc\)
-   Sporting Goods
-   Sports and Riding Apparel Stores
-   Takeaways and Restaurants
-   Telecommunications
-   Warehouse Stores
-   Wholesalers
-   Women Clothes

**Note:** The up-to-date version of the eligible sectors list can be found on the Ecommpay website, [in the application form](https://ecommpay.com/payments-for-small-businesses/), and can differ from the list above which should be used for reference purposes only.

If any questions occurin the process of onboarding via Ecommpay for Small Businesses, refer to this documentation and the AI assistant of the Dashboard interface. In cases when you need more assistance, contact the Ecommpay specialists at [help@ecommpay.com](mailto:help@ecommpay.com), an email specifically set up for answering questions related to Ecommpay for Small Businesses.

## Onboarding steps {#en_platform_onboarding_for_small_businesses_workflow}

When onboarding via Ecommpay for Small Businesses, you should keep in mind that this solution automates organisational and legal issues related to integration, and you are in charge of the technical integration of your web service with the Ecommpay payment platform.

The procedure of automated onboarding includes the following steps:

1.  Apply for the automated onboarding on the Ecommpay website.

    To do so, check if your company is eligible, submit your application at [the Ecommpay website](https://ecommpay.com/payments-for-small-businesses/), and receive an invitation to start the automated onboarding via Dashboard \(more [below](platform_onboarding_for_small_businesses_application.md)\).

2.  Submit the company information along with supporting documentationto Dashboard.

    To do so, add the company details, stakeholders, and a bank account in the appropriate tabs \([details](platform_onboarding_for_small_businesses_company.md)\) and upload necessary documents \([details](platform_onboarding_for_small_businesses_documents.md)\).

3.  Sign an agreement between your company and Ecommpayin Dashboard.

    To do so, read the terms of the Ecommpay agreement and sign it to confirm the intent to be legally bound. This step is described [further on](platform_onboarding_for_small_businesses_agreement.md).

4.  Complete technical tasks to integrate with the payment platform.

    Once the agreement is signed, you can proceed to technical integration. The automated onboarding via the Dashboard interface provides access to the essential set of features and functionalities that merchants can implement \([details](platform_onboarding_for_small_businesses_integration.md)\).


## Completing an application {#en_platform_onboarding_for_small_businesses_application}

Completing and submitting an application form is the first step of onboarding via Ecommpay for Small Businesses. At this step, it is important to keep in mind that the decision on the application is made automatically. If the application is declined, Ecommpay reserves the right not to reconsider this decision. To increase the chances of approval, the company must meet [the specified requirements](platform_onboarding_for_small_businesses_overview.md), and the information on the application must be correct and accurate.However, it is also worth noting that if the application is approved, the information you provided can be edited and corrected later when you are working with the Dashboard interface.

To apply for the automated onboarding with the Ecommpay platform:

1.  Open an application form by clicking [the link](https://ecommpay.com/payments-for-small-businesses/) and then the **Get started** button.
2.  Specify the company details.

    To do so, fill in the following fields:

    -   **First name**—the first and middle names of the company's contact person\(exactly as they appear on an identity document\).
    -   **Last name**—the last name of the company's contact person\(exactly as it appears on an identity document\).
    -   **Business email**—the email address to contact the company and sign up for the Dashboard account.
    -   **Mobile number**—the telephone number to contact the company\(in the international format\).
    -   **Company registration number**—the company registration number, CRN\(an 8-character identifier found in the Certificate of Incorporation from Companies House\).
    -   **Company name**—the name of the company\(as specified in the Certificate of Incorporation\).
    -   **Company website**—the URL of the company's website\(in the URL format; third-party resources, such as social media profiles or partnership pages, are not accepted\).
    -   **Business segment**—the category of the company's economic activity according to the list of eligible industry sectors from Ecommpay\(select the most relevant category\).
    **Note:** If you are unable to fill in at least one of the fields \(or you cannot find a fitting business segment in the list of the Ecommpay eligible sectors\), you can [apply for standard onboarding instead](https://ecommpay.com/apply-now/).

3.  Make sure that the specified information is correct and click **Register your interest** to submit the application.
4.  Make sure the application is submitted successfully.

    You should be redirected to the page with a `Thank you` message.

5.  Make sure that you receive the result of the application review from Ecommpay.

    As a rule, the review of the application is performed automatically and takes about one minute. However, if there are questions and there is a need for involvement of specialists, this process can take up to three business days. Once Ecommpay reviews your application, you will receive an email. If you are approved, the email will contain an invitation to start the automated onboarding via Dashboard, otherwise, the email will state that the application has been declined. If you have any questions about your application, contact the Ecommpay specialists at [help@ecommpay.com](mailto:help@ecommpay.com).


![](images/ecommpay/onboarding/onboarding_application.svg "The application form")

## Submitting company information {#en_platform_onboarding_for_small_businesses_registering}

### General description {#section_js2_fjb_1jc .section}

At the second step of onboarding via Ecommpay for Small Businesses, you need to submit information that will be reviewed for eligibility and compliance. There are three categories of information to be added: general information about the company, the company's stakeholders, and the company's bank account that will be used for settlements with Ecommpay. You have to submit information for each category, in the order categories are listed on the registration navigation panel: you can move on to the next category only after you have received the confirmation that the information you have submitted previously has been reviewed and approved. Once all of the required information has been submitted and reviewed, you need to upload supporting documentation\(for example, the certificate of registration and HM Revenue and Customs \(HMRC\) tax notices\). To prevent inconsistencies, make sure to specify the company information as stated in the official documents.

### Adding company details {#en_platform_onboarding_for_small_businesses_company}

The first category of information that you need to submit for onboarding is the general information about the company. Some of these details will be prefilled with the information you have provided on the application formand you will be able to edit them if needed. Also note that the information you provide in this tab cannot be saved as a draft. All required information must be entered within one Dashboard session.

The company details must match the information provided in the documents that contain [the list of shareholders](platform_onboarding_for_small_businesses_documents.md#section_tp1_zxy_t3c) and [the company's address](platform_onboarding_for_small_businesses_documents.md#section_kmw_lyy_t3c).When filling in the fields, keep these documents at hand to ensure that the company details are provided as stated in the official documents.

To add information about the company:

1.  Open the tab for adding company details.

    To do so, go to the **Get started** section of the Dashboard interface and click **Add company info** on the registration navigation panel.

2.  Specify the company details: review the information that you have provided on the application form, edit it if necessary, and add any data that is missing.

    To do so, fill in the following fields:

    -   **Company legal name**—the name of the company\(as specified in the Certificate of Incorporation; this field is prefilled according to the original application and editable\).
    -   **Website URL**—the URL of the company's website\(in the URL format; third-party resources, such as social media profiles or partnership pages, are not accepted; this field is prefilled according to the original application and editable\).
    -   **Business industry segment**—the category of the company's economic activity according to the list of eligible industry sectors from Ecommpay\(select the most relevant category; this field is prefilled according to the original application and editable\).
    -   **Business phone number**—the telephone number to contact the company\(in the international format; this field is prefilled according to the original application and editable\).
    -   **Registration Number**—the company registration number, CRN\(an 8-character identifier found in the Certificate of Incorporation from Companies House; this field is prefilled according to the original application and editable\).
    -   **TAX ID \(if applicable\)**—the Corporation Unique Taxpayer Reference\(a 10 or 13-digit identifier found on the HMRC correspondence or in your HMRC Business Tax Account\).
    -   **Number of employees in the company**—the number of people employed by your company on the date when you are submitting the application via Dashboard\(cannot be more than 10 employees\).
    -   **Building number**—the number of the building in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Street**—the name of the street in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Unit / Floor / Office \(optional\)**—the number of the unit, floor, or office in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Country**—the name of the country in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; must be selected from the list\).
    -   **City**—the name of the city in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; must be selected from the list that becomes available after the country is selected\).
    -   **Postal code**—the postcode in the company's registered address\(can be found on the HMRC tax notice, lease agreement, or another supporting document\).
3.  Make sure that the specified information is correct and submit it for review by Ecommpay.

    To do so, compare the information you have entered with the official documents of your company, click **Continue** in the bottom right corner of the tab and then **Submit** in the modal window that opens, following which make sure you are shown a notification that the information is under review.

4.  Make sure that you receive the result of the review from Ecommpay.

    As a rule, the review takes about half an hour. If the information provided at this step is accepted, you will be able to proceed to adding information about the company stakeholders, whereas if it is declined, you will be shown a message that you will not be able to continue onboarding via the Dashboard interface. Also, in some cases, Ecommpay may contact you to discuss switching to the standard onboarding and integration process, with specialist consultations.


![](images/ecommpay/onboarding/onboarding_company_main.svg "Opening the tab")

![](images/ecommpay/onboarding/onboarding_company_fields.svg "Adding company details")

![](images/ecommpay/onboarding/onboarding_company_success.svg "Notification that the information is under review")

![](images/ecommpay/onboarding/onboarding_company_decline.svg "Notification that the application is declined")

![](images/ecommpay/onboarding/onboarding_stakeholders_main.svg "Viewing onboarding progress")

### Adding stakeholders {#en_platform_onboarding_for_small_businesses_stakeholders}

The second category of information that you need to submit for onboarding is the information about the company's stakeholders that include:

-   `Ultimate beneficial owner`—each person who owns more than 25% of the company's shares.
-   `Director`—an officially listed company director with the signing authority.
-   `Signatory`—a person who has legal authority to sign agreements for the company.
-   `Contact person`—a person who completes the onboarding application form and acts as a main contact for the company.

Depending on the company, the same person can be assigned one or more stakeholder roles. For the contact person, specifying their name and position in the company is enough, while for other stakeholder roles you need to provide more detailsincluding personal information, sources of income, and residential address \(you do not have to enter this information repeatedly if the same person is assigned several stakeholder roles\). Also note that the stakeholder information can be saved as a draft using the **Save a draft** button\(with the option to return to editing the draft later via the Dashboard homepage\).

The information about the company stakeholders must match the information provided in the documents that contain [the list of shareholders](platform_onboarding_for_small_businesses_documents.md#section_tp1_zxy_t3c), [personal identification of stakeholders](platform_onboarding_for_small_businesses_documents.md#section_h41_cyy_t3c), and [their residential addresses](platform_onboarding_for_small_businesses_documents.md#section_mfc_fyy_t3c).When filling in the fields, keep these documents at hand to ensure that the information is provided as stated in the official documents.

To add information about the company stakeholders:

1.  Open the tab for adding the stakeholders.

    To do so, go to the homepage of the Dashboard interface and click **Add stakeholders** on the registration navigation panel.

2.  Specify the details of all company stakeholders.

    Note that for the first stakeholder specified, some fields will be prefilled with the information you have provided on the application form, and you can edit these fields. For subsequent stakeholders, prefilling is not used, and you will have to fill in all fields manually. To add information about the next stakeholder, click **Add person** in the bottom right corner of the tab.

    As a rule, the first stakeholder you specify is the contact person for whom it is sufficient to enter the first name, last name, and job title. For other individuals, you must provide the following information:

    -   **Role**—all roles assigned to the stakeholder\(`Contact person`, `Director`, `Signatory`, and `Ultimate beneficial owner`\).
    -   **First name**—the stakeholder's first and middle names\(exactly as they appear on an identity document\).
    -   **Last name**—the stakeholder's last name\(exactly as it appears on an identity document\).
    -   **Date of birth**—the stakeholder's date of birth\(exactly as it appears on an identity document\).
    -   **Mobile phone**—the telephone number to contact the stakeholder\(in the international format\).
    -   **Email**—the email address to contact the stakeholder.
    -   **Share percentage**—the proportion of the company's total outstanding shares owned by the stakeholder\(percentage, exactly as it appears on a corporate document\).
    -   **Source of wealth**—the origin of total accumulated assets describing how the stakeholder has accumulated their overall net worth over time\(must be selected from the list\).
    -   **Value of source of wealth**—the value of total accumulated assets of the stakeholder\(must be selected from the list of ranges in US dollars\).
    -   **Building number**—the number of the building in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Street**—the name of the street in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Unit / Floor / Office \(optional\)**—the number of the unit, floor, or flat in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; this field is optional\).
    -   **Country**—the name of the country in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; must be selected from the list\).
    -   **City**—the name of the city in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document; must be selected from the list that becomes available after the country is selected\).
    -   **Postal code**—the postcode in the stakeholder's residential address\(can be found on the HMRC tax notice, lease agreement, or another supporting document\).
3.  Make sure that the specified information is correct and submit it for review by Ecommpay.

    To do so, compare the information you have entered with the official documents of your company and stakeholders, click **Continue** in the bottom right corner of the tab and then **Submit** in the modal window that opens, following which make sure you are shown a notification that the information is under review.

4.  Make sure that you receive the result of the review from Ecommpay.

    As a rule, the review takes about half an hour. If the information provided at this step is accepted, you can proceed to providing information about the company's bank account, whereas if it is declined, you will be shown a message that you will not be able to continue onboarding via the Dashboard interface. Also, in some cases, Ecommpay may contact you to discuss switching to the standard onboarding and integration process, with specialist consultations.


![](images/ecommpay/onboarding/onboarding_stakeholders_main.svg "Opening the tab")

![](images/ecommpay/onboarding/onboarding_stakeholders_contactperson.svg "Adding a contact person")

![](images/ecommpay/onboarding/onboarding_stakeholders_ubo.svg "Adding a UBO")

![](images/ecommpay/onboarding/onboarding_stakeholders_success.svg "Notification that the information is under review")

![](images/ecommpay/onboarding/onboarding_company_decline.svg "Notification that the application is declined")

![](images/ecommpay/onboarding/onboarding_bankaccount_main.svg "Viewing onboarding progress")

### Adding a bank account {#en_platform_onboarding_for_small_businesses_bank_accounts}

The third category of information that you need to submit for onboarding is the information about the company's bank account to set up settlements with Ecommpay. As a rule, providing an account number and a SWIFT code is sufficient, since the name of the bank and the country are determined automatically. Keep in mind that at this step you can provide only one account, single currency or multicurrency, and the information about this account will be used to perform compliance checks.You can add more bank accounts at a later date, after the process of onboarding is complete. Also note that the information you provide in this tab cannot be saved as a draft. All required information must be entered within one Dashboard session.

The bank account details must match the information provided in the [financial supporting documents](platform_onboarding_for_small_businesses_documents.md#section_pjy_fll_2jc). When filling in the fields, keep these documents at hand to ensure that the account details are provided as specified by the bank.

To add information about the company's bank account:

1.  Open the tab for adding a bank account.

    To do so, go to the homepage of the Dashboard interface and click **Connect bank account** on the registration navigation panel.

2.  Specify the bank account details.

    To do so, fill in the following fields:

    -   **Is this a multicurrency account?**—an indicator showing that the multicurrency operations are supported by the bank for this account\(select `Yes` or `No`\).
    -   **Account Number / IBAN**—an international bank account number.
    -   **Account Currency**—the currency code\(for the single currency bank account\).
    -   **BIC/SWIFT**—an international identification code of the bankwhere the account is held \(BIC or SWIFT; when you are filling in this field, you can use the dropdown list that becomes available if at least three characters have been entered\).
    -   **Name of the financial institution**—the name of the bankwhere the account is held \(prefilled according to the specified bank code, not editable at this step\).
    -   **Registration country of the financial institution**—the country where the bank is registered\(prefilled according to the specified bank code, not editable at this step\).
3.  Make sure that the specified information is correct and submit it to Ecommpay.

    To do so, compare the information you have entered with the official documents of your company, click **Continue** in the bottom right corner of the tab and then **Submit** in the modal window that opens, following which make sure that you are redirected to the tab for uploading supporting documentation.


![](images/ecommpay/onboarding/onboarding_bankaccount_main.svg "Opening the tab")

![](images/ecommpay/onboarding/onboarding_bankaccount_fields.svg "Adding a single currency account")

![](images/ecommpay/onboarding/onboarding_documents_shareholders.svg "Redirecting to the next tab")

## Uploading supporting documents {#en_platform_onboarding_for_small_businesses_documents}

### General procedure {#section_gmy_mpv_s3c .section}

After all necessary information has been submitted, you need to upload supporting documentation in order to prove that the information you provided is valid. You can find the comprehensive list of documents in this section.

**Note:** Failure to upload some of the documents can only be acceptable if you provide a valid reason. Note that it can lead to increase in the overall number of documents that you need to submit, additional checks, and longer application approval times.

At this step of onboarding via Ecommpay for Small Businesses, you need to do the following:

1.  Prepare all required documents for upload.

    To do so, check if you have supporting documents for each category of information described in this section and prepare a file for each document. The file must meet the following requirements:

    -   Type of the document: an electronic original or a digital copy of a printed original\(as a scanned image with clear, easy-to-read text\).
    -   Language of the document: English\(as the only language or one of the languages used in the document simultaneously\).
    -   Date of the original document: within the allowed time range specific to each category of documents\(usually, not older than 12 months\).
    -   File format: PDF, PNG or JPG.Other formats, including archive formats, are not supported.
    -   File size: no more than 25Mb.
2.  Open the tab for uploading documents in Dashboard.

    To do so, go to the homepage of the Dashboard interface and click **Document upload** on the registration navigation panel.

3.  Upload the documents and specify current information.

    To do so, attach documents one by one or fill in necessary data for each category: the shareholder register, personal identification information and residential addresses of stakeholders, description of the company's nature of business, address of the company's registration and financial statements. Note that in case of each category you should proofread the automatically recognised data and, if needed, edit it or add more, following which confirm that the details provided are correct and navigate to the next category of documents by clicking **Next**.

    In cases when you are unable to upload a document, you can skip its upload by clicking **I don't have a document** and specifyingin the field that opens the reason for it: absence, damage, and so on.

    **Warning:** Keep in mind that when you upload documents, you cannot return to previous pageseven if you skipped a form by accident or continued to the next page without uploading anything.

4.  Make sure that the documents have been sent for review by Ecommpay.

    You should be redirected to the page with a `Thank you` message.

5.  Make sure that you receive the result of the documents review from Ecommpay.

    As a rule, this review takes about five minutes. If the uploaded documentation is accepted, you can proceed to signing the agreement. If it is declined, you will be shown a message that you will not be able to continue onboarding via the Dashboard interface. Also, in some cases, Ecommpay may contact you to discuss switching to the standard onboarding and integration process, with specialist consultations.


### Uploading the shareholder register {#section_tp1_zxy_t3c .section}

To upload supporting documentation about the company's shareholders, you can use any of the followingas long as the document contains the up-to-date shareholder list with percentages of shares held by each shareholder:

-   Company Register Extract with shareholders
-   Memorandum of Association with shareholders
-   Certificate of Incumbency
-   Certificate of Sole Entrepreneurship

### Uploading stakeholder documents {#section_h41_cyy_t3c .section}

To upload supporting documentation about the company's stakeholders, you can use any official documentsissued by any country that include personal identification details \(first name, last name, date of birth\), a photo and the document's expiry date. Depending on the person, it can be the following:

-   British passport or an international passport issued by any other country
-   UK Driving License or International Driving License
-   Citizen Card, Biometric Residence Permit, or National ID Card issued by an EU country

### Uploading proof of address {#section_mfc_fyy_t3c .section}

To upload proof of address for each of the stakeholders in the role `Ultimate beneficial owner`, `Director`, and `Signatory`, you can use any official documentthat contains the full name and the residential address of the person, as well as the document's expiry date. Depending on the person, it can be the following:

-   HMRC tax notification \(not older than 3 months and excluding P45 or P60 documents that are not acceptable\)
-   Local authority tax bill \(not older than 3 months\)
-   Utility Bill \(not older than 3 months\)
-   Bank Statement, for 6 or 12 months \(not older than 3 months\)
-   Lease Agreement \(no restrictions to the document recency\)

### Describing nature of business {#section_txt_hyy_t3c .section}

To submit the description of the company's nature of business and business risk level for review and approval, you should provide answers to a number of questions. The exact number of these questions varies and usually includes the following questions:

-   What does the company do, what products and services does it offer to the clients, and what are the company's main delivery channels?
-   What specific products and services does the company offer and who is the company's target audience?
-   How does the company find new customers and what are the main methods of customer acquisition?
-   What websites does the company use to sell goods and services?

Enter each answer in plain text, as the text in the answer fields cannot be formatted and illustrations cannot be inserted.In addition, if you specify different websites, the URL for each should be provided in a new line.

### Uploading the company's registration address {#section_kmw_lyy_t3c .section}

To upload proof of address where the company is registered, you can use any official documentthat contains the name and the address of the company, as well as the document's expiry date, including:

-   HMRC tax notification \(not older than 3 months and excluding P45 or P60 documents that are not acceptable\)
-   Local authority tax bill \(not older than 3 months\)
-   Utility Bill \(not older than 3 months\)
-   Bank Statement, for 6 or 12 months \(not older than 3 months\)
-   Lease Agreement \(no restrictions to the document recency\)

### Uploading financial supporting documents {#section_pjy_fll_2jc .section}

To upload supporting documentation about the company's turnover, you can use recent financial statements or audit reports.

## Signing the agreement {#en_platform_onboarding_for_small_businesses_agreement}

At the ultimate step of onboarding via Ecommpay for Small Businesses, you need to sign the agreement with Ecommpay in Dashboard. This agreement is legally binding and goes into effect once both parties confirm their intent to enter into a contract.

To sign the agreement:

1.  Open the tab for signing the agreement.

    To do so, go to the homepage of the Dashboard interface and click **Agreement signing** on the registration navigation panel.

2.  Review the documents to be signed.

    To do so, read the terms of the Ecommpay agreement displayed in the tab that opens and the privacy policy available on a separate page of the Ecommpay website.

3.  Select a stakeholder authorised to sign a legally binding document and confirm the signing.

    To do so, select a stakeholder with the `Signatory` role from the **Selected authorized signatory** drop-down list, check the box to agree with the terms, click **Continue**, and confirm the action in the modal window that opens.

4.  Make sure that the approval of the onboarding application is confirmed.

    As a rule, it takes about five minutes. If the application is approved, you will be shown a message in Dashboard that the application process is complete and the technical integration can start at this point. If there are errors or disruptions at this step, you can refresh the page, clear the browser cache, and reopen the Dashboard interface. If difficulties or questions occur, contact the Ecommpay specialists at [help@ecommpay.com](mailto:help@ecommpay.com).


![](images/ecommpay/onboarding/onboarding_agreement_main.svg "Opening the tab")

![](images/ecommpay/onboarding/onboarding_agreement_signing.svg "Signing the agreement")

![](images/ecommpay/onboarding/onboarding_agreement_success.svg "Completing the onboarding application")

After signing the agreement, you can proceed to the technical integration with the platform and going live.

## Technical integration {#en_platform_onboarding_for_small_businesses_integration}

After you have signed the agreement with Ecommpay, you can proceed to technical integration with the payment platform.Companies that are onboarded via Ecommpay for Small Businesses have access to essential functionality of the platformwith different options of payment processing. Within these options, you can choose and configure the following:

-   Interfaces for payment processingthat include:
    -   Standard edition of hosted Payment Pagethat can be embedded into any web service \([details](en_pp_quickstart.md)\).
    -   Plug-ins for Magento CMS \([details](en_CMS__magento.md)\) and Wordpress CMS \([details](en_CMS__wordpress.md)\).
    -   Payment linksthat can be generated and sent to customers via Dashboard \([details](en_dbl_payments.md)\).
    -   The Ecommpay web application for working with Xero \([details](en_xero_invoices.md)\).
-   Payment methodsthat are most widely recognised and used around the globe:
    -   [Standard card payments](en_pm_card_payments.md)
    -   [Apple Pay](pm_applepay.md)
    -   [Google Pay](pm_googlepay.md)
-   Essential capabilitiesfor which all necessary auxiliary procedures are supported automatically, for example, 3‑D Secure or the customer address verification:
    -   one-time one-step and two-step purchases\(with different user scenarios depending on the specifics of the payment interface used\)
    -   purchase refunds issued via Dashboard \([details](en_dbl_payments.md)\)
-   Additional capabilities for working with Payment Page, available by default, for example, customisation of the payment form design \([details](en_PP__design_customisation.md)\) and configuring interface language \([details](en_PP_WigetLanguages.md)\).
-   [Dashboard](en_dbl_about.md), the interface to monitor payment processing, and the financial accounting tools of the [Xero](en_xero.md) platform.

To solve any issues that arise in the process of technical integration, refer to this documentation, the AI assistant, and the technical support specialists \(contact them at [help@ecommpay.com](mailto:help@ecommpay.com)\). However, note that merchants onboarded via Ecommpay for Small Businesses are not assigned account managers by Ecommpay, so if it is suggested that you should refer to your account manager, use other available communication channels instead.



---

# Payment processing {#en_platform_payment_model}

Articles about payment types that can be processed via the platform, workflows and possible statuses of these payments and operations performed within them.

The Ecommpay payment platform allows you touse various payment methods to process different paymentsmade with payment cards and other payment instruments. All payments, regardless of payment method, are separated into several basic types.

-   One-time purchase with [one step](en_platform_sms_model.md) and [two steps](en_platform_dms_model.md)—`purchase`;
-   COF purchase with [on-demand](en_platform_recurring_model.md) or [automatic](en_platform_sheduled_recurring_model.md) debiting of funds—`recurring`;
-   [Payment link purchase](en_platform_invoice_model.md) with one step and two steps—`invoice`;
-   [Payout](en_platform_payout_model.md)—`payout`;
-   [Payment instrument verification](en_platform_account_verification_model.md)—`account verification`.

This subsection covers information aboutthe general payment model and models of separate payment types.

-   **[Payment model](en_platform_payment_model_overview.md)**  
An article about the general model of initiating and processing payments via the platform.
-   **[One-time one-step purchase](en_platform_sms_model.md)**  
An article about processing one-time purchases with immediate debiting of funds \(one step\), includes the description of the processing workflow, possible statuses and operations.
-   **[One-time two-step purchase](en_platform_dms_model.md)**  
An article about processing one-time purchases with placing an authorisation hold and subsequent debiting of funds \(two steps\), includes the description of the processing workflow, possible statuses and operations.
-   **[On-demand COF purchase](en_platform_recurring_model.md)**  
An article about processing recurring purchases with debiting of funds initiated by the merchant \(unscheduled\), includes the description of the processing workflow, possible statuses and operations.
-   **[COF purchase with automatic debiting](en_platform_sheduled_recurring_model.md)**  
An article about processing recurring purchases with automatic debiting of funds \(according to a set schedule\), includes the description of the processing workflow, possible statuses and operations.
-   **[Payment link purchase](en_platform_invoice_model.md)**  
An article about processing purchases with the use of payment links, includes the description of the processing workflow, possible statuses and operations.
-   **[Payout](en_platform_payout_model.md)**  
An article about processing payouts, includes the description of the processing workflow, possible statuses and operations.
-   **[Payment instrument verification](en_platform_account_verification_model.md)**  
An article about verifying a payment instrument \(by debiting a zero amount\), includes the description of the processing workflow, possible statuses and operations.

**Parent topic:**[Platform](en_platform_about.md)



---

# Payment model {#en_platform_payment_model_overview}

An article about the general model of initiating and processing payments via the platform.

The Ecommpay payment platform is used for processing *payments*. A payment in the payment platform is a set of tasks to transfer funds between the merchant and their customer.It can be a transfer of funds from the customer to the merchant \(*purchase*\), or from the merchant to the customer \(*payout*\). Refunds are processed within the purchase and, therefore, are not considered a separate payment type. However, payments also include *payment instrument verification* that can involve transferring a zero amountor placing a hold on the customer account for a specified amount and subsequent cancellation of this holding.

There are several ways to initialise a payment. You can send an *HTTP request* by using the Gate API or the Payment Page APIor perform certain actions in the Dashboard interface. Besides, payments can be initiated with the use of other tools for working with the payment platform.

If a request to perform a payment is successfully accepted for processing, in the payment platform the `payment` object and the first \(or the only one\) `operation` object associated with this payment are created.

![](images/payment%20model/en_gate_payment_model_1.svg)



When the payment takes more that one operation, normally the merchant needs to send the request for initiating each subsequent operation. However, in some cases, the payment platform automatically initiates the subsequent operation, for example, automatic debit operations performed as part of a COF purchase.

General information about processing payments via the Ecommpay payment platform is provided in the [Payment processing](en_platform_payment_model.md) section, while technical information is provided in the sections with information about the platform's interfaces.

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# One-timeone-step purchase {#en_platform_sms_model}

An article about processing one-time purchases with immediate debiting of funds \(one step\), includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_zvh_1rr_whb .section}

*One-time one-step purchase* is a payment type which uses only one request to make a one-time transfer of funds from customer to merchant. This is the most basic purchase type in which the customercard or account is immediately debited for the amount of the purchase, for example to pay for an item of goods.

## Payment model {#section_ajd_brr_whb .section}

To initiate one-step purchase, a request of the `sale` category should be sent to the platform or the payment form should be opened in the Purchase mode with the `sale` payment type specified. Once the payment platform receives the request, it creates the `sale` operation which eventually results in debiting the customercard or account.

A one-step purchase may require the merchant to send the following additional requests:

-   *Customer authentication by using the 3‑D Secure technology*.In case of working via Gate, for such authentication, the web service is required to accept the corresponding callback and perform the needed actions, while in case of working via Payment Page, all actions needed for authentication are carried out without the web service involved.
-   *Customer authentication performed by the payment system on merchant's request*. In case of working via Gate, for such authentication, the web service is required to accept the corresponding callback and perform the needed actions, while in case of working via Payment Page, all actions needed for authentication are carried out without the web service involved.
-   *Submission of additional payment information* for any party involved in the payment processing.In case of working via Gate, for submitting additional information, the web service is required to accept the corresponding callback and send a request with the needed data, while in case of working via Payment Page, all actions needed for that are carried out without the web service involved.

If the payment method supports the capability of confirming that the funds were transferred to the payment recipient, then, after the `sale` operation has been completed, the `payment confirmation` operation is initiated in the payment platform. It results in receiving such a confirmation from the provider.

If the payment method supports refunds, after completing a one-time one-step purchase you can return your customers their money if needed. This can be done as a result of a [request](en_Gate_Refund.md) sent via Gate or as a result of the corresponding [action](en_dbl_payments.md) in the tab of the needed purchase in the Dashboard interface. For a refundwithin a card payment, depending on the refund time and amount and the payment instrument used for the payment, one of the following operations is initiated:

-   `reversal` if the refund is initiated within the [operation day](en_glossary.md) regardless of the purchase amount for a Mastercard card and provided that the total purchase amount is refunded for a card of any other card network;
-   `refund` if the refund is initiated for a card of any card network after [operation day](en_glossary.md) and regardless of the amount and within the operation day provided that a partial purchase amount is refunded for a card of all card networks except Mastercard.

In case of a refund for a purchase processed with the use of an alternative payment method, normally the `refund` operation is initiated. The `reversal` operation can be initiated when the purchase is assigned the `success` status following the confirmation from the payment system or the provider, but the funds cannot be transferred to the payment recipient.

![](images/payment%20model/en_payment_model_2.svg "State diagram for one-time one-step purchase")

The rest of this section describes any possible statuses of a one-time one-step purchase and operations related with the purchase. More information about processing one-time one-step purchasesusing payment cards is provided in the[Payment Page](en_PP_about.md) and [Gate](en_Gate_Integration_About.md) sections, while the information about processing purchases with the use of other payment instruments is provided in the [Payment methods](en_pm_about.md) section.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of a one-time one-step purchase.

|`error`|Error occurred when request processing. Payment is not performed.|*Final status. The request can be resent with the same payment identifier and the same payment can be retried.*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting merchant auth`|Payment processing is suspended until the customer authentication initiated in a payment system on the merchant's request is completed.|*Intermediate status*|
|`awaiting redirect result`|Payment processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.

 When processing of the payment only one of the following statuses can be used: either `awaiting redirect result` or `awaiting customer action`.

|*Intermediate status*|
|`awaiting customer action`|Payment processing is suspended until a customer interacts with a payment system that submits the results of this interaction. Depending on the result that the payment system submitted the status is set to `success` or `decline`.

 When processing of the payment only one of the following statuses can be used: either `awaiting redirect result` or `awaiting customer action`.

|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`awaiting customer`|Payment processing is suspended until one of additional attempts to perform this payment is completed \(in this case, the status is set to `success` or all additional attempts are used up \(in this case, the status is set to `decline`\).

 For more information about the Try again payments, see [Payment retries](en_PP_Try_Again.md).

|*Intermediate status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has been completed.|*Final status. Additionally the payment refund is supported.*|
|`partially reversed`|Payment amount is partially refunded within the operation day on which the payment was completed.|*Final status*|
|`reversed`|Total payment amount is refunded within the operation day on which the payment was completed.|*Final status. Additionally, the refund can be cancelled.*|
|`partially refunded`|Partial amount of the payment is returned to the customer.|*Final status. Additionally, the refund can be cancelled.*|
|`refunded`|Payment amount is fully refunded after the operation day on which the payment was completed. This status is used if the total amount of payment is returned in one refund or if the total amount of the partial refunds is equal to the total amount of payment.|*Final status. Additionally, the refund can be cancelled.*|

## Statuses of the sale operation {#section_h3k_crr_whb .section}

The following table describes the statuses of the `sale` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting merchant auth`|Payment processing is suspended until the customer authentication initiated in a payment system on the merchant's request is completed.|*Intermediate status*|
|`awaiting redirect result`|Operation processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting customer action`|Operation processing is suspended until a customer interacts with a payment system that submits the results of this interaction. Depending on the result that the payment system submitted the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

## Statuses of the payment confirmation operation {#section_egh_3zh_sqb .section}

The following table describes the statuses of the `payment confirmation` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

## Statuses of the reversal and refund operations {#section_zfx_crr_whb .section}

The following table describes the statuses of the `reversal` or the `refund` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# One-time two-step purchase {#en_platform_dms_model}

An article about processing one-time purchases with placing an authorisation hold and subsequent debiting of funds \(two steps\), includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_zvh_1rr_whb .section}

*One-time two-step purchase* is a payment type which uses two steps to make a one-time transfer of funds from customer to merchant. On the first step, merchant initiates an authorization hold—in other words, the purchase amount is deducted from the credit limit of customer's card account. On the second step, the purchase amount is *captured*, or, in other words, it is debited to the customer account based on the merchant request or after specific time lag.

This payment type allows merchant to “hold” the purchase amount and, thus, to ensure that specific amount will be charged, or *captured*, to customer account or, alternatively, to “release” the funds if the situation changes, for instance when the customer cancels hotel booking.

## Payment model {#section_ajd_brr_whb .section}

You initiate *the first step* of a purchaseby sending an `auth` request to the payment platform or by opening the payment form in the `purchase` mode with the `auth` operation type specified. Once the payment platform receives the request, it creates an `auth` operation which eventually results in holding funds on customer account.

*The first step* may require merchant to issue additional requests:

-   If the payment requires *customer to be authenticated by using the 3‑D Secure technology*, the payment platform sends to the web service a callback that contains the data required to generate a request to the issuer and suspends the purchase processing until the authentication result information is received.For submitting the information, in case of working via Gate, it is required to send a request with the authentication result—`3ds_result`—, while in case of working via Payment Page, all actions are carried out without the merchant's web service involved.
-   If the payment requires *customer to be authenticated by the payment system on merchant's request*, the payment platform receives a notification from the payment system and sends to the web service a callback with notification that authentication is required, and then suspends the payment processing in the platform. To continue processing the payment, in case of working via Gate, two `merchant_auth` requests should be sent: `start`—after the customer confirms the payment and `finish`—after the customer enters the validation code, while in case of working via Payment Page, all actions are carried out without the merchant's web service involved.
-   If any payment stakeholder requests *additional information* \(For example, the payment system may request cardholder address which was missing from the initial request.\), the payment platform sends to the web service a callback that lists the requested parameters and suspends the purchase processing until the required information is received.In case of working via Gate, a request should be sent with the needed information included—`clarification`, while in case of working via Payment Page, all actions are carried out without the merchant's web service involved.

*The second step* may be initiated by a request from merchant's web service, through an action in the Dashboard or the payment platform may automatically perform the step after specific time elapses.

The merchant initiates *the second step* by sending one of the following requests to the payment platform:

-   `capture`—this request processing results in a `capture` operation and the customer account is debited for the held amount.
-   `cancel`—this request processing results in a `cancel` operation and release of the funds held on the customer account.

In your `capture` request, you can specify a to-be-debited amount which is different from the initially authorised amount.

For more information on how to initiate the second step, refer to your account manager.

If the payment method supports refunds, after completing the second step of a one-time two-step purchase, you can refund the purchase. This can be done by sending a `refund` request to the payment platform or as a result of the corresponding action on the payment information tab in the Dashboard interface. For a refundwithin a card payment, depending on the refund time and amount and the payment instrument used for the payment, one of the following operations is initiated:

-   `reversal` if the refund is initiated within the [operation day](en_glossary.md) regardless of the purchase amount for a Mastercard card and provided that the total purchase amount is refunded for a card of any other card network;
-   `refund` if the refund is initiated for a card of any card network after [operation day](en_glossary.md) and regardless of the amount and within the operation day provided that a partial purchase amount is refunded for a card of all card networks except Mastercard.

![](images/payment%20model/en_gate_payment_model_3.svg)



The rest of this section describes any possible statuses of a one-time two-step purchase and the related operations. More information about processing one-time two-step purchasesusing payment cards is provided in the [Payment Page](en_PP_about.md)and [Gate](en_Gate_Integration_About.md) sections, while the information about processing purchases with the use of other payment instruments is provided in the [Payment methods](en_pm_about.md) section.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of a one-time two-step purchase.

|`error`|Error occurred when request processing. Payment is not performed.|*Final status. The request can be resent with the same payment identifier and the same payment can be retried.*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting merchant auth`|Payment processing is suspended until the customer authentication initiated in a payment system on the merchant's request is completed.|*Intermediate status*|
|`awaiting redirect result`|Payment processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`awaiting customer`|Payment processing is suspended until one of additional attempts to perform this payment is completed \(in this case, the status is set to `success`or all additional attempts are used up \(in this case, the status is set to `decline`\).

 For more information about the Try again payments, see [Payment retries](en_PP_Try_Again.md).

|*Intermediate status*|
|`awaiting capture`|Payment processing is suspended until the web service submits a `capture` request or a `cancel` request.|*Intermediate status*|
|`canceled`|A hold placed on funds was cancelled.|*Final status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has been completed.|*Final status. Additionally, the payment refund is supported.*|
|`partially reversed`|Payment amount is partially refunded within the operation day on which the payment was completed.|*Final status*|
|`reversed`|Total payment amount is refunded within the operation day on which the payment was completed.|*Final status. Additionally, the refund can be cancelled.*|
|`partially refunded`|Partial amount of the payment is returned to the customer.|*Final status. Additionally a partial refund can be cancelled.*|
|`refunded`|Payment amount is fully refunded after the operation day on which the payment was completed. This status is used if the total amount of payment is returned in one refund or if the total amount of the partial refunds is equal to the total amount of payment.|*Final status. Additionally, a refund can be cancelled.*|

## The auth operation statuses {#section_h3k_crr_whb .section}

The following table describes the statuses of the `auth` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting merchant auth`|Payment processing is suspended until the customer authentication initiated in a payment system on the merchant's request is completed.|*Intermediate status*|
|`awaiting redirect result`|Operation processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

## Statuses of the incremental operation {#section_tnc_3nh_snb .section}

The following table describes the statuses of the `incremental` operation.

|`decline`|Operation is declined.|*Final status*|
|`success`|Operation is completed.|*Final status*|

## Statuses of the capture and cancel operations {#section_wxn_gsr_whb .section}

The following table describes the statuses of any `capture` or `cancel` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

## Statuses of the reversal and refund operations {#section_zfx_crr_whb .section}

The `reversal` and `refund` operation statuses coincide with the statuses of the `capture` and `cancel` operations.

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# On-demand COF purchase {#en_platform_recurring_model}

An article about processing recurring purchases with debiting of funds initiated by the merchant \(unscheduled\), includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_zvh_1rr_whb .section}

*On-demand Credential-on-file \(COF\) purchase* is a payment type which uses a single initial request to make one transfer of funds from customer to merchant by using previously stored payment credentials but without validation of the payment instrument \(such as card validation code, or CVC\).

The on-demand COF purchases are used for purchases that use the same payment instrument for repeatable purchases with variable amount and no specific schedule, for instance to pay for taxi services. On-demand COF purchases are convenient because they do not require the customer to enter payment credentials and to validate the payment instrument for each purchase.

The payment platform supports the following COF payment categories:

-   *One-click purchases*. Series of debits within such purchases are initiated by the customer and are not based on a schedule or a payment amount. For example, the customer can pay the rent of one or several movies in a virtual cinema using previously saved card credentials.
-   *Autopurchases*. Series of debits within such purchases are initiated by the merchant and are unscheduled or performed for different amounts. For example, when the customer's account balance falls below specific threshold, funds are withdrawn from the customer's bank account for a top up.

Gate can be used to register and process any COF purchases, while Payment Page allows registering any COF purchases and process one-click purchaseswith the use of some payment methods.

## Payment model {#section_ajd_brr_whb .section}

A COF purchase becomes available only after its *registration*, which means making an initial payment—a one-time purchase or a payment instrument verification—with the customer's payment data saved in the platform and COF purchase type specified.The set of parameters required for further processing of the COF purchase can differ depending on the payment method in use.

When using Gate, you initiate COF purchase by sending a `recurring` requestor a `sale` request to the payment platform. Once the payment platform receives the request, it creates a `recurring`or a `sale` operationrespectively. The created operation eventually results in debiting customer card or account without payment instrument validation.

When using Payment Page, to initiate a COF purchase, you specify the `purchase` operation mode and additional parameters required for performing COF purchasesusing a particular payment method in the parameters for opening the payment form. Once the payment form opens, the customer should select the payment instrument for which the COF purchases are registered and confirm payment processing. Authentication is not required. As soon as the customer confirms payment processing, request is sent to the payment platform. Once the payment platform receives the request, it creates the `sale` operation which results in debiting of customer's funds without the verification of the payment instrument.

In rare instances, a COF purchase may require you to send another request to submit *additional information* requested by one of the stakeholders, for example to provide cardholder address which is missing from the initial request. In such cases, when working via Gate, a callback with the names of parameters for clarifying information is sent from the platform to the web service and payment processing is suspended until a request with the required information is sent from the web service—`clarification`, while when working via Payment Page, all actions are carried out without the merchant's web service involved.

If the payment method supports refunds, after completing an on-demand COF purchase you can *return* your customers their money, if needed. You initiate a refund by sending a `refund` request to the payment platform or select the corresponding action on the payment information tab in the Dashboard interface. For a refundwithin a card payment, depending on the refund time and amount and the payment instrument used for the payment, one of the following operations is initiated:

-   `reversal` if the refund is initiated within the [operation day](en_glossary.md) regardless of the purchase amount for a Mastercard card and provided that the total purchase amount is refunded for a card of any other card network;
-   `refund` if the refund is initiated for a card of any card network after [operation day](en_glossary.md) and regardless of the amount and within the operation day provided that a partial purchase amount is refunded for a card of all card networks except Mastercard.

![](images/payment%20model/en_gate_payment_model_4.svg "State diagram for on-demand COF purchase")

The rest of this section describes any possible statuses of an on-demand COF purchase and the related operations. More information about processing COF purchases is provided in the [Payment Page](en_PP_about.md) and [Gate](en_Gate_Integration_About.md) sections, while the information about processing purchases with the use of other payment instruments is provided in the [Payment methods](en_pm_about.md) section.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of any on-demand COF purchase.

|`error`|Payment processing is not initiated, error occurred when processing the request received by the payment platform.|*Final status. The request can be resent with the same payment identifier and the same payment can be retried.*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status.|*Intermediate status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has completed successfully.|*Final status. Additionally the payment refund is supported.*|
|`reversed`|Total payment amount is refunded within the operation day on which the payment was completed.|*Final status. Additionally, the refund can be cancelled.*|
|`partially refunded`|The partial amount of payment has returned to a customer.|*Final status. Additionally a partial refund can be cancelled.*|
|`refunded`|The the total amount of payment was returned to a customer after the business day the initial purchase had been completed.

 This status is used if the total amount of payment is returned in one refund or if the total amount of the partial refunds is equal to the total amount of payment.

|*Final status. Additionally a refund can be cancelled.*|

## The recurring operation statuses {#section_h3k_crr_whb .section}

The following table describes the statuses of the `sale` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has completed successfully.|*Final status*|

## Statuses of the reversal and refund operations {#section_zfx_crr_whb .section}

The `reversal` and `refund` operation statuses coincide with the statuses of the `recurring` operation.

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# COF purchase with automatic debiting {#en_platform_sheduled_recurring_model}

An article about processing recurring purchases with automatic debiting of funds \(according to a set schedule\), includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_zvh_1rr_whb .section}

*Credential-on-file \(COF\) purchase with automatic debiting* is a payment type which uses an initial request to initiate a series of fund transfers from customer to merchant by using previously stored payment credentials without validation of the payment instrument \(such as card validation code, or CVC\). This payment type includes *regular purchases*.

COF purchases with automatic debiting are used for purchases in which the same payment instrument for repeatable miscellaneous purchases with fixed amount and schedule, for instance to pay monthly fee for a subscription. COF purchases with automatic debiting are convenient for the customer and the merchant because they can be sure that payments will be performed automatically, with no additional actions on their part.

## Payment model {#section_ajd_brr_whb .section}

A COF purchase becomes available only after its *registration*, which means making an initial payment—a one-time purchase or a payment instrument verification—with the customer's payment data saved in the platform and COF purchase type specified.The set of parameters required for further processing of the COF purchase can differ depending on the payment method in use.

If all required parameters were specified during COF purchase registration, the merchant or the customer does not need to initiate the scheduled COF purchase, as in this case withdrawal of funds is initiated automatically by the payment platform. A separate `recurring` operation is used for each withdrawal.

If required, you can change the payment schedule and/or amount or even cancel the payment altogether. To change the payment schedule and/or amount, you need to submit an `update` request to the payment platform via Gate. To cancel the payment, you submit a `cancel` request. To initiate the `update` and `cancel` requests, you use the `recurring_update` and `recurring_cancel` operations, respectively.

In rare instances, a COF purchase with automatic debiting may require you to send another request to submit *additional information* requested by one of the stakeholders, for example to provide cardholder address which is missing from the initial request. In such cases, when working via Gate, a callback with the names of parameters for clarifying information is sent from the platform to the web service and payment processing is suspended until a request with the required information is sent from the web service—`clarification`.

If the payment method supports refunds, after completing a COF purchase with automatic debiting you can *return* your customers their money, if needed. The total amount of refund cannot be larger than the total debited amount. You initiate a refund by sending a `refund` request to the payment platform or select the corresponding action in the payment information tab of the Dashboard interface. Refund is performed by using the `refund` operation.

![](images/payment%20model/en_gate_payment_model_5.svg)



The rest of this section describes any possible statuses of a COF purchase with automatic debiting and the related operations. More information about processing COF purchases is provided in the [Gate](en_Gate_Integration_About.md) section.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of any COF purchase with automatic debiting.

|`error`|Payment processing is not initiated, error occurred when processing the request received by the payment platform.|*Final status. The request can be resent with the same payment identifier and the same payment can be retried.*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status|*Intermediate status*|
|`scheduled recurring processing`|Payment is in progress. Automatic debiting is pending according to the prearranged schedule.|*Intermediate status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has completed successfully.|*Final status. Additionally the payment refund is supported.*|
|`partially refunded`|The partial amount of payment has returned to a customer and all series of debits within the payment are completed.|*Final status. Additionally a partial refund can be cancelled.*|
|`refunded`|The the total amount of payment was returned to a customer and all series of debits within the payment are completed.

|*Final status. Additionally a refund can be cancelled.*|

## The recurring operation statuses {#section_h3k_crr_whb .section}

The following table describes the statuses of the `sale` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has completed successfully.|*Final status*|

## The recurring\_update and recurring\_cancel operations statuses {#section_h3k_ytr_whb .section}

The following table describes the statuses of the `recurring_update` and `recurring_cancel` operations.

|`processing`|Operation is being processed.|*Intermediate status*|
|`decline`|Operation is declined.|*Final status*|
|`success`|Operation is completed.|*Final status*|

## The refund operation statuses {#section_glx_sqm_g3b .section}

The `refund` operation statuses coincide with the `recurring` operation statuses.

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# Payment link purchase {#en_platform_invoice_model}

An article about processing purchases with the use of payment links, includes the description of the processing workflow, possible statuses and operations.

## General information {#section_ltv_433_tkb .section}

*Payment link purchase* is a payment type which uses an initial request to generate a web link that customers can click to make purchases that involve a one-timeor recurring transfer of funds from the customer to the merchant.As a rule, payment link purchases are used for one-time payments with or without the authorisation hold. At the same time, if needed, payment link purchases can be used for registering [COF purchases](en_Gate__payments_on_saved_data.md), while with certain payment methods payment links can be used for obtaining the customer's consent to registration of a COF purchase, without actual withdrawal of funds.

This payment type is useful when you need to accept online payments that are not attached to a certain time, physical POS, or online site. You can either have the Ecommpay payment platform send payment link to the customer via email, or you can share it via any other delivery media, for example, messengers or social media.

## Payment model {#section_dy1_z33_tkb .section}

To create a payment link, you can send an `invoice/create` request to the Gate API or select the corresponding action in the Dashboard interface. When the payment platform receives the request, it creates an `invoice` operation that results in:

-   generating the payment link,
-   delivering it to your web service,
-   sending it to the customer if it was specified in the request.

Depending on which interface was used to initiate the payment link creation, you can receive the created payment link in a callback sent to the web service or via Dashboard. The link is sent to the customer automatically via the payment platform if it was specifically indicated and the customer's email was provided. For this purpose, you can use parameters `send_email` and `email` in the request to the Gate API or the **Send e-mail to the Customer** toggle switch and the **Customer e-mail** field in Dashboard. Note that if the link is not intended to be sent via the payment platform and will be sent via the web service instead, the `invoice` operation is technically finalised after the payment link has been delivered to your web service.

Once the link has been created and delivered to the web service, but before the customer confirms the purchase, you can deactivate the payment link if necessary. To do so, you need to send an `invoice/cancel` request to the payment platform or use the **Deactivate** toggle switch in the list of payment links in Dashboard.

By clicking the payment link, your customers open Payment Page where they can enter their payment information and complete the purchase. Then,the payment is processed according to one of the following scenarios depending on the `operation_type` parameter value:

-   *Processing a purchase \([details](en_platform_sms_model.md)\), with or without registration of a COF purchase*   In this processing scenario, the payment platform creates a `sale` operation that eventually debits the customer's account.
-   *Placing an authorisation hold \([details](en_platform_dms_model.md)\), with or without registration of a COF purchase*   In this processing scenario, the payment platform creates an `auth` operation that results in authorisation hold of funds on customer account. Capturing the funds or cancelling the hold can be initiated in one of the following ways:
    -   By request from the merchant's web service.
    -   By the merchant employees that use Dashboard for this purpose.
    -   By the payment platform after a timeout.
-   *Registering a COF purchase*   In this processing scenario, the COF purchase is registered without the customer's funds deducted or held. The payment platform creates a `contract_registration` operation that results in a registered COF purchase.

For each of these scenarios that involve payment links, the payment platform may perform some [auxiliary procedures](en_gate_procedures.md), though no additional input from the web service is required because all operations are performed by Payment Page.

*Refunds* can be issued for all successful payments completed by using payment linksif refunds are supported for the specific payment methodand the payment processing scenario. To initiate a refund, you need to submit a `refund` request or select the corresponding action in the payment information tab in the Dashboard interface. For a refundwithin a card payment, depending on the refund time and amount and the payment instrument used for the payment, one of the following operations is initiated:

-   `reversal` if the refund is initiated within the [operation day](en_glossary.md) regardless of the purchase amount for a Mastercard card and provided that the total purchase amount is refunded for a card of any other card network;
-   `refund` if the refund is initiated for a card of any card network after [operation day](en_glossary.md) and regardless of the amount and within the operation day provided that a partial purchase amount is refunded for a card of all card networks except Mastercard.

![](images/payment%20model/en_gate_payment_model_invoice.svg "State diagram for a two-step payment link purchase")

The rest of this section describes any possible statuses of a payment link purchase and the related operations. More information about processing payment link purchases is provided in the [Gate](en_Gate_Integration_About.md)and [Dashboard](en_dbl_about.md) sections.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of a payment link purchase.

|`error`|Payment not initiated because of request verification error|*Final status. The request can be resent with the same payment identifier and reattempt to perform the payment.*|
|`awaiting payment`|Payment processing initiated, waiting for payment link submission|*Intermediate status*|
|`expired`|Payment declined because of payment link expiry|*Final status*|
|`invoice canceled`|Payment declined by merchant|*Final status*|
|`invoice sent`|Payment processing initiated, payment link sent|*Intermediate status*|
|`processing`|Payment is being processed|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting redirect result`|Payment processing is suspended until the payment system submits a messagewith the result or that the customer performed required actions. Depending on the result the payment system submitted, the status is set to `awaiting finalization`,`success`, or `decline`.|*Intermediate status*|
|`awaiting finalization`|Payment processing is suspended until the payment system submits a message with the result. No additional actions of the customer are required, and depending on the result the payment system submitted, the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`awaiting customer`|Payment processing is suspended until one of additional customer attempts to perform the payment is successfully completed—the status is set to `success`—or the maximum amount of the additional attempts is exceeded—the status is set to `decline`. \(For more information, see [Payment retries](en_PP_Try_Again.md).\)|*Intermediate status*|
|`awaiting capture`|Payment processing is suspended until the web service submits a `capture` or a `cancel` request.|*Intermediate status*|
|`canceled`|Authorisation hold previously placed by a `auth` request has been cancelled.|*Final status*|
|`decline`|Payment declined|*Final status*|
|`success`|Payment completed|*Final status. Also, refund is supported.*|
|`partially reversed`|Partial refund performed before closing the business day the initial payment was completed|*Final status*|
|`reversed`|Full refund performed before closing the business day the initial payment was completed|*Final status. Also, refund can be reversed.*|
|`partially refunded`|Payment partially refunded|*Final status. Also, refund can be reversed.*|
|`refunded`|Full refund performed after closing the business day when the initial payment was completed. The refund is performed in a lump sum or in several sums that in total equal to the initial purchase amount.|*Final status. Also, refund can be reversed.*|

## The statuses of the invoice operation {#section_vhh_1j3_tkb .section}

The following table describes the statuses of the `invoice` operation.

|`awaiting payment`|Operation initiated, the payment link delivered to the web service.

 If the payment link was requested to be sent to the customer via the Ecommpay payment platform, then waiting to send the email with the link.

 If the payment link was not requested to be sent via the Ecommpay payment platform and will be sent via the web service, then the operation has been completed.

|*Intermediate statusif the link is sent via the platform.*

 *Final status if the link is sent via the merchant's web service*

|
|`expired`|Operation completed, the payment link expired|*Final status*|
|`invoice canceled`|Operation cancelled by the merchant|*Final status*|
|`invoice sent`|Operation completed, the payment link sent|*Final status*|

## The statuses of the saleand auth operations {#section_oxc_cw3_tkb .section}

The following table describes the statuses for the `sale`and `auth` operations.

|`processing`|Operation is being performed|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting redirect result`|Operation processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result returned by the payment system, the status is set to `success` or `decline`.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Operation declined|*Final status*|
|`success`|Operation completed|*Final status*|

## The statuses of the capture and cancel operations {#section_gnf_fw3_tkb .section}

The following table describes the statuses for the `capture` and `cancel` operations.

|`processing`|Operation is being processed|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Operation declined|*Final status*|
|`success`|Operation completed|*Final status*|

## The statuses of the contract registration operation {#section_o3q_bxg_j2c .section}

|`processing`|Operation is being processed|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives additional information. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`awaiting redirect result`|Operation processing is suspended until the payment system submits a message. Depending on the result the payment system submitted, the status is set to `success` or `decline`.|*Intermediate status*|
|`decline`|Operation declined|*Final status*|
|`success`|Operation completed|*Final status*|

## The statuses of the reversal and refund operations {#section_mvr_hw3_tkb .section}

The `reversal` and `refund` operations use the same statuses as the `capture` and `cancel` operations.

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# Payout {#en_platform_payout_model}

An article about processing payouts, includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_htd_ylv_cjb .section}

*Payout* is a payment type which uses one request to make a one-time transfer of funds from merchant to customer.

Basically, the payment platform performs payouts on demand \(one-time payments\); though, you can implement bulk payouts by using Dashboard. In the latter case, you can have the required payouts generated automatically. For more information about bulk payouts, see [Monitoring and performing payments](en_dbl_payments.md).

## Payment model {#section_ajd_brr_whb .section}

You initiate a payout by sending a `payout` request to the payment platform, opening the payment form in the Payout mode, or selecting the corresponding action in the **Payouts** section of the Dashboard interface. Once the payment platform receives the payout request, it creates a `payout` operation which eventually results in crediting the funds to the customer card or account.

In some cases, a payout may require you to send another request to submit *additional information* requested by one of the stakeholders, for example to provide cardholder address which is missing from the initial request. In this case, the payment platform sends to the web service a callback with the names of the missing parameters, suspends the payout processing, and waits until the web service submits a `clarification` request with the values for the missing parameters.The procedure is currently not supported for alternative payment methods.

If a payment system or a provider assigns the payout the `success` status but for some reason the customer's account cannot be credited, a reversal of the payout is initiated in the payment platform after receiving a callback with information about crediting failure. The reversal is performed manually by the Ecommpay technical support specialists or, for some payment methods, automatically. The reversal is performed by initiating the `payout reversal` operation.

![](images/payment%20model/en_gate_payment_model_14.svg "State diagram for payout via Payment Page")

![](images/payment%20model/en_gate_payment_model_12.svg "State diagram for payout via Gate")

The rest of this section describes any possible statuses of a payout and operations related with the payout. More information about processing payoutsusing payment card is provided in the [Payment Page](en_PP_about.md),[Gate](en_Gate_Integration_About.md), and [Dashboard](en_dbl_about.md) sections, while the information about processing payouts with the use of alternative payment instruments is provided in the [Payment methods](en_pm_about.md) section.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes payout statuses.

|`error`|Error occurred when request processing. Payment is not performed.|*Final status. The request can be resent with the same payment identifier and reattempt to perform the payment.*|
|`awaiting payout completion`|Payment processing has been initiated, awaiting the payout confirmation by the customer.|*Intermediate status*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has been completed successfully.|*Final status. Additionally the payment refund is supported.*|
|`reversed`|Payment has been reversed.|*Final status.*|

## The payout operation statuses {#section_h3k_crr_whb .section}

The following table describes the statuses of any `payout` operation.

|`awaiting payout completion`|Operation processing has been initiated, awaiting the payout confirmation by the customer.|*Intermediate status*|
|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting clarification`|Operation processing is suspended until the payment platform receives the additional information from the customer. If the payment platform does not receive the required information within 30 minutes, the status is set to `decline`.|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed successfully.|*Final status*|

## The payout reversal operation statuses {#section_n3y_j4g_ppb .section}

The following table describes the statuses of any `payout reversal` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`decline`|Operation is declined.|*Final status*|
|`success`|Operation is completed.|*Final status*|

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# Payment instrument verification {#en_platform_account_verification_model}

An article about verifying a payment instrument \(by debiting a zero amount\), includes the description of the processing workflow, possible statuses and operations.

## Overview {#section_zvh_1rr_whb .section}

*Payment instrument verification* is a payment type in which the customer card or account is validated by either transferring a dummy \(zero\) amount from customer to merchantor by authorizing a specific amount \(non-zero\) on the customer's card or account and then voiding the transfer or the authorization. The authorization amount can be changed on merchant's request. Normally, the authorized amount is released shortly after the operation, but in some instances the authorized amount can be held up to 45 days.

This payment type can be used, for example, for registering COF purchases.

**Note:** For information about the availability of payment instrument verification, contact the Ecommpay account manager.

## Payment model {#section_ajd_brr_whb .section}

You initiate the verificationby sending the `account verification` request to the payment platform or by opening the payment form in the `card_verify` mode. Once the payment platform receives the request, it creates an `account verification` operation.

Payment instrument verification may require the merchant to send additional requests:

-   If the payment requires *customer to be authenticated by using the 3‑D Secure service*, the payment platform sends to the web service a callback with the data required to generate a request to the issuer and suspends payment processing until the information about the authentication result is received.For this, in case of working via Gate, it is required to send a request with the authentication result—`3ds_result`, while in case of working via Payment Page, all actions are carried out without the merchant's web service involved.
-   If any payment stakeholder requests *additional information* \(for example, the payment system may request cardholder address which was missing from the initial request.\), the payment platform sends to the web service a callback that lists the requested parameters and suspends the purchase processing until the required information is received.In case of working via Gate, a request should be sent with the needed information included—`clarification`, while in case of working via Payment Page, all actions are carried out without the merchant's web service involved.

![](images/payment%20model/en_gate_payment_model_7.svg)



The rest of this section describes any possible statuses of a payment instrument verification and related operations. More information about processing payment instrument verification is provided in the [Payment Page](en_PP_about.md)and [Gate](en_Gate_Integration_About.md) sections.

## Payment statuses {#section_n4r_brr_whb .section}

The following table describes the statuses of payment instrument verification.

|`error`|Error occurred when request processing. Payment is not performed.|*Final status. The request can be resent with the same payment identifier and the same payment can be retried.*|
|`processing`|Payment is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status.|*Intermediate status*|
|`decline`|Payment could not be completed.|*Final status*|
|`success`|Payment has been completed.|*Final status. Additionally the payment refund is supported.*|

## The account verification operation statuses {#section_h3k_crr_whb .section}

The following table describes the statuses of any `account verification` operation.

|`processing`|Operation is being processed.|*Intermediate status*|
|`awaiting 3ds result`|Payment processing is suspended until the information about the 3‑D Secure authentication result is received. If this information is not received within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on a provider. For more information about specific timeouts, contact technical support at [support@ecommpay.com](mailto:support@ecommpay.com).|*Intermediate status*|
|`awaiting clarification`|Payment processing is suspended until the required additional information is received. If the information is not received within 30 minutes, the payment is assigned the `decline` status.|*Intermediate status*|
|`decline`|Operation could not be completed.|*Final status*|
|`success`|Operation has been completed.|*Final status*|

**Parent topic:**[Payment processing](en_platform_payment_model.md)



---

# Signature generation and verification {#en_platform_signature}

An article about signing data in API requests, responses, and callbacks and verifying signatures in order to ensure secure data exchange with the payment platform.

**Parent topic:**[Platform](en_platform_about.md)

## Overview {#en_platform_signature_overview}

The data communication between the merchant's web service and the Ecommpay payment platform is protected by using the TLS \(Transport Layer Security\) protocol version 1.2 or later. This ensures the confidentiality of the data being transmitted, although the protocol cannot guarantee the message integrity and ensure that the message author possesses the secret key. Therefore, every message must be digitally signed using the secret key issued by Ecommpay for the merchant and known only to the merchant and the Ecommpay payment platform.

Regardless of the interface that is used for working with the payment platform, digital signatures must be included in all requests, callbacks, and certain responses exchanged between the merchant's web service and the payment platform. Thus, before sending any request to the platform, generate and include a signature in the request to be sent; and when receiving responses and callbacks from the platform, verify the received data by comparing the signatures to the ones generated on the merchant side.To implement the digital signature generation and verification, you can use either your own solutions or the SDKs available from Ecommpay \([details](en_sdk_overview.md)\).

This section describes the algorithms for the digital signature generation and the data integrity verification, including examples with the use of these algorithms and interactive forms for testing the workflows using signatures.

## Signature generation {#en_platform_signature_generation}

### Signing algorithm {#section_zkt_kcl_bbb .section}

The algorithm *input* includes the following:

1.  *Data* to sign.

    As a rule, it is a request body: all request parameters without the signature or the configObj JavaScript object with parameters that do not include the `signature` parameter.

2.  A signing *key*.

    **Note:** For working with the Data API, it is necessary to use keys generated via the Dashboard interface together with tokens \(for more information, see the [Data access model](en_dbl_api_interaction.md) section.\)

    For the purposes of debugging and testing your signing algorithm implementation, you are free to use any signing key. For signing requests in production environment, you are required to use your production secret key.


Depending on the algorithm implementation, its *output* may be either a *signature* or *signed data*. Generally, the algorithm output consists of an object or a request body in the JSON format with the `signature` parameter.

The algorithm description, the examples, and test forms below include the most common algorithm implementation relevant for use when working with the Payment Page API, the Gate API, and the Data API.

The *algorithm* includes *the following steps*:

1.  *Validating input*. Make sure the following requirements are met:

    1.  The structure of data to be signed must correspond to the JSON format. In case of using Payment Page, JavaScript objects are also allowed.
    2.  Data to sign does not contain any `signature` parameter even if it is empty.
    3.  The signing key is readily available.
2.  *Transforming data to meet the nesting depth requirements*.

    Depending on which interface of the payment platform you need to send the request to, this step requires different actions:

    -   When working via Payment Page, encode those parameters that contain nested objects using Base64 or URL encoding, as per the requirements that can be found in [the list of parameters for opening the payment form](en_PP_Parameters.md).
    -   When working via the Gate API, you do not have to transform data because there are no nesting depth restrictions.
    -   When working via the Data API, replace values of all parameters nested at level four or deeper with empty strings.
3.  *Converting all strings to UTF-8 with parameters sorted in natural order*. Complete the following steps:

    1.  Encode any Boolean values as follows: replace `false` with `0`, replace `true` with `1`. Mind that this rule applies only to Boolean values. If any string parameter contains `"false"` or `"true"` string value, the value is not replaced with `0` or `1` but is treated as any other string value\(for example the `recurring: "{type: \"U\",register: true}"` parameter does not require replacing `true` with `1`\).
    2.  Convert each parameter into a string that contains the full path to the parameter \(with all its parents\), parameter name, and parameter value:

        ```language-c
        <*parent\_1*>:...:<*parent\_n*>:<*parameter\_name*>:<*parameter\_value*>
        ```

        where *parents* are the object\(s\) and/or arrays in which the parameter is contained. Parents are ordered by the embedding level starting with the topmost one. The parent names, parameter name, and parameter value are delimited by colon \(:\); delete any commas between key-value pairs and any quotation marks that delimit string values.

    3.  Leave any empty parameter values empty. In other words, do not replace any empty values with blank space or `null`. For instance, `"payment_description":""` is replaced with `payment_description:`.
    4.  Add index numbers to array elements starting with zero, for example, `["alpha", "beta", "gamma"]` is replaced with three strings: `0:alpha`, `1:beta`, and `2:gamma`.
    5.  Empty arrays are ignored and are not included in the string set used to generate the signature.
    6.  Convert all strings to UTF-8.
    7.  Sort the strings in natural sort order and join them into a single string by using semicolon \(;\) as a delimiter.
4.  *Calculating the HMAC code by using the key and the SHA-512 hash function*. Calculate the HMAC code for the string by using the SHA-512 hash function and secret key. The HMAC code must be calculated as raw binary data.
5.  *Encoding the HMAC code by using the Base64 scheme*. Encode the HMAC code using Base64 to obtain the signature for the initial data.
6.  *Adding signature*. Add the `signature` parameter to the request body using the signature from the previous step as its value.

### Example of a purchase request via Payment Page {#section_kpg_ncl_bbb .section}

Suppose that you need to generate a signature for a Payment Page request in the following scenario:

-   The secret key obtained from the Ecommpay technical support: `secret`.
-   The configObj object that does not yet contain the signature parameter is the following:

    ``` {#codeblock_chw_ylb_f1c}
    {
    "project_id": 12345, 
    "payment_id": "X03936", 
    "payment_amount": 2035, 
    "payment_currency": "USD",
    "payment_description": "Guyliner purchase",
    "customer_first_name": "Jack",
    "customer_id": "user007",
    "customer_last_name": "Sparrow",
    "customer_phone": "02081234567",
    "close_on_missclick": true,
    **"signature": "<*signature that needs to be generated*\>" **
    }
    ```


The task is to generate the signature; in other words, you need to compute the value for the `signature` parameter. The signature is generated as follows:

1.  Make sure there is no `signature` parameter in your request even it is empty:

    ``` {#codeblock_wdr_zy3_1fc}
    {
    "project_id": 12345, 
    "payment_id": "X03936", 
    "payment_amount": 2035, 
    "payment_currency": "USD",
    "payment_description": "Guyliner purchase",
    "customer_first_name": "Jack",
    "customer_id": "user007",
    "customer_last_name": "Sparrow",
    "customer_phone": "02081234567",
    "close_on_missclick": true,
    **"signature": "<*signature that needs to be generated*\>" **
    }
    ```

2.  Convert all strings to UTF-8 as per algorithm description:

    ``` {#codeblock_ydr_zy3_1fc}
    project_id:12345 
    payment_id:X03936
    payment_amount:2035
    payment_currency:USD
    payment_description:Guyliner purchase
    customer_first_name:Jack
    customer_id:user007
    customer_last_name:Sparrow
    customer_phone:02081234567
    close_on_missclick:1
    ```

3.  Sort the strings in natural sort order:

    ``` {#codeblock_a2r_zy3_1fc}
    close_on_missclick:1
    customer_first_name:Jack
    customer_id:user007
    customer_last_name:Sparrow
    customer_phone:02081234567
    payment_amount:2035
    payment_currency:USD
    payment_description:Guyliner purchase
    payment_id:X03936
    project_id:12345
    
    ```

4.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ``` {#codeblock_c2r_zy3_1fc}
    close_on_missclick:1;customer_first_name:Jack;customer_id:user007;customer_last_name:Sparrow;customer_phone:02081234567;payment_amount:2035;payment_currency:USD;payment_description:Guyliner purchase;payment_id:X03936;project_id:12345
    ```

5.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ``` {#codeblock_e2r_zy3_1fc}
    SyA3cx/dmFrwjRcpbnwEK9zaklWKR9buIfTctQob/EHUTutFLpI0zWpSDFEWEwbZt/04i83395RCdEhtUMw83A==
    ```

6.  Add the resulting signature to the configObj object:

    ``` {#codeblock_g2r_zy3_1fc}
    {
    "project_id": 12345, 
    "payment_id": "X03936", 
    "payment_amount": 2035, 
    "payment_currency": "USD",
    "payment_description": "Guyliner purchase",
    "customer_first_name": "Jack",
    "customer_id": "user007",
    "customer_last_name": "Sparrow",
    "customer_phone": "02081234567",
    "close_on_missclick": true,
    **"signature": "SyA3cx/dmFrwjRcpbnwEK9zaklWKR9buIfTctQob/EHUTutFLpI0zWpSDFEWEwbZt/04i83395RCdEhtUMw83A==" **
    }
    ```


### Signature verification form for Payment Page {#section_i2r_zy3_1fc .section}

Below you can find an interactive form that allows you to test signature generation when sending requests for opening Payment Page.

**Note:** To ensure correct processing of parameters specified in real requests for opening Payment Page, familiarise yourself with the requirements for encoding nested objects listed in [Payment Page API specification](en_PP_Parameters.md) and the articles describing the capabilities of the payment form. When you specify nested objects that do not conform to these requirements, the signature in the interactive testing form will still be generated according to the algorithm, but this signature cannot be used for real requests because it is generated with the use of incorrect input data.



### Example of a purchase request via Gate {#section_kpg_ncldsdsdsdasa_bbb .section}

Suppose that you need to generate the signature for the Gate API request in the following scenario:

-   Signing key : `secret`.
-   Preliminary request body version where the value for the `signature` is not yet added:

    ``` {#codeblock_edx_cz3_1fc .language-python}
    {
        "general": {
            "project_id": 3254,
            "payment_id": "id_38202316",
           **"signature": "<*signature that needs to be generated*\>" **
        },
        "customer": {
            "id": "585741",
            "email": "johndoe@mycompany.com",
            "first_name": "John",
            "last_name": "Doe",
            "address": "Downing str., 23",
            "identify": {
                "doc_number": "54122312544"
            },
            "ip_address": "111.222.333.444"
        },
        "payment": {
            "amount": 10800,
            "currency": "USD",
            "description": "Computer keyboards"
        },
        "receipt_data": {
            "positions": [
                {
                    "quantity": "10",
                    "amount": "108",
                    "description": "Computer keyboard"
                }
            ]
        },
        "return_url": {
            "success": "https://paymentpage.mycompany.com/complete-redirect?id=success",
            "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline"
        }
    }
    ```


The task is to generate the signature; in other words, you need to compute the value for the `signature` parameter and add it to the request. Complete the following steps:

1.  Make sure there is no `signature` parameter in your request even if it is empty:

    ``` {#codeblock_gdx_cz3_1fc .language-python}
    {
        "general": {
            "project_id": 3254,
            "payment_id": "id_38202316",
    **"signature": "<*signature that needs to be generated*\>"**
        },
        "customer": {
            "id": "585741",
            "email": "johndoe@mycompany.com",
            "first_name": "John",
            "last_name": "Doe",
            "address": "Downing str., 23",
            "identify": {
                "doc_number": "54122312544"
            },
            "ip_address": "111.222.333.444"
        },
        "payment": {
            "amount": 10800,
            "currency": "USD",
            "description": "Computer  keyboards"
        },
        "receipt_data": {
            "positions": [
                {
                    "quantity": "10",
                    "amount": "108",
                    "description": "Computer keyboard"
                }
            ]
        },
        "return_url": {
            "success": "https://paymentpage.mycompany.com/complete-redirect?id=success",
            "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline"
        }
    }
    ```

2.  Convert all strings to UTF-8 as per algorithm description:

    ``` {#codeblock_idx_cz3_1fc .language-json}
    general:project_id:3254
    general:payment_id:id_38202316
    customer:id:585741
    customer:email:johndoe@mycompany.com
    customer:first_name:John
    customer:last_name:Doe
    customer:address:Downing str., 23
    customer:identify:doc_number:54122312544
    customer:ip_address:111.222.333.444
    payment:amount:10800
    payment:currency:USD
    payment:description:Computer keyboards
    receipt_data:positions:0:quantity:10
    receipt_data:positions:0:amount:108
    receipt_data:positions:0:description:Computer keyboard
    return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success
    return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline
    ```

3.  Sort the strings in natural sort order:

    ``` {#codeblock_kdx_cz3_1fc .language-lua}
    customer:address:Downing str., 23
    customer:email:johndoe@mycompany.com
    customer:first_name:John
    customer:id:585741
    customer:identify:doc_number:54122312544
    customer:ip_address:111.222.333.444
    customer:last_name:Doe
    general:payment_id:id_38202316
    general:project_id:3254
    payment:amount:10800
    payment:currency:USD
    payment:description:Computer keyboards
    receipt_data:positions:0:amount:108
    receipt_data:positions:0:description:Computer keyboard
    receipt_data:positions:0:quantity:10
    return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline
    return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success
    
    ```

4.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ``` {#codeblock_mdx_cz3_1fc}
    customer:address:Downing str., 23;customer:email:johndoe@mycompany.com;customer:first_name:John;customer:id:585741;customer:identify:doc_number:54122312544;customer:ip_address:111.222.333.444;customer:last_name:Doe;general:payment_id:id_38202316;general:project_id:3254;payment:amount:10800;payment:currency:USD;payment:description:Computer keyboards;receipt_data:positions:0:amount:108;receipt_data:positions:0:description:Computer keyboard;receipt_data:positions:0:quantity:10;return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline;return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success
    ```

5.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ``` {#codeblock_odx_cz3_1fc}
    VLLZzVNGevQNhr1b4TEhbC4qqHD17Kyn/M6FPNN93ttyk/amJgD/R6dayTKVvW6/QCRdq4hOf8R2w/xbUa8f2w==
    ```

6.  Add the resulting signature to the request body:

    ``` {#codeblock_qdx_cz3_1fc}
    {
        "general": {
            "project_id": 3254,
            "payment_id": "id_38202316",
    **       "signature": "VLLZzVNGevQNhr1b4TEhbC4qqHD17Kyn/M6FPNN93ttyk/amJgD/R6dayTKVvW6/QCRdq4hOf8R2w/xbUa8f2w=="**
        },
        "customer": {
            "id": "585741",
            "email": "johndoe@mycompany.com",
            "first_name": "John",
            "last_name": "Doe",
            "address": "Downing str., 23",
            "identify": {
                "doc_number": "54122312544"
            },
            "ip_address": "111.222.333.444"
        },
        "payment": {
            "amount": 10800,
            "currency": "USD",
            "description": "Computer keyboards"
        },
        "receipt_data": {
            "positions": [
                {
                    "quantity": "10",
                    "amount": "108",
                    "description": "Computer keyboard"
                }
            ]
        },
        "return_url": {
            "success": "https://paymentpage.mycompany.com/complete-redirect?id=success",
            "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline"
        }
    }
    ```


### Signature verification form for the Gate API {#section_sdx_cz3_1fc .section}

Below you can find an interactive form that allows you to test signature generation when sending the Gate API requests.



### Example of a data request via the Data API {#section_kpg_ncdsdsdl_bbb .section}

Suppose that you need to generate a signature for a Dashboard request in the following scenario:

-   Signing key : `secret`.
-   Preliminary request body version where the value for the `signature` is not yet added:

    ```
    {
      "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
      "interval": {
        "from": "2020-01-01 14:53:55",
        "to": "2020-01-30 13:53:59"
      },
      "project_id": [
        183
      ],
      "limit": 3,
      "offset": 0,
      "tz": "Asia/Singapore",
     **"signature": "<*signature that needs to be generated*\>"**
    }
    ```


The task is to generate the signature; in other words, you need to compute the value for the `signature` parameter and add it to the request. Complete the following steps:

1.  Make sure there is no `signature` parameter in your request even it is empty:

    ```
    {
      "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
      "interval": {
        "from": "2020-01-01 14:53:55",
        "to": "2020-01-30 13:53:59"
      },
      "project_id": [
        183
      ],
      "limit": 3,
      "offset": 0,
      "tz": "Asia/Singapore",
     **"signature": "<*signature that needs to be generated*\>"**
    }
    ```

2.  Convert all strings to UTF-8 as per algorithm description:

    ```
    token:WKiarERJ5pcceNerpM9R5TNnyPTQMl
    interval:from:2020-01-01 14:53:55
    interval:to:2020-01-30 13:53:59
    project_id:0:183
    limit:3
    offset:0
    tz:Asia/Singapore
    ```

3.  Sort the strings in natural sort order:

    ```
    interval:from:2020-01-01 14:53:55
    interval:to:2020-01-30 13:53:59
    limit:3
    offset:0
    project_id:0:183
    token:WKiarERJ5pcceNerpM9R5TNnyPTQMl
    tz:Asia/Singapore
    
    ```

4.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ```
    interval:from:2020-01-01 14:53:55;interval:to:2020-01-30 13:53:59;limit:3;offset:0;project_id:0:183;token:WKiarERJ5pcceNerpM9R5TNnyPTQMl;tz:Asia/Singapore
    ```

5.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ```
    Ini3aKje6aZskajTuRS761YOzVqierlVRafZdxIz48wmVnL7yxgy9vDsp7T2/LGPGHJ/DHoKOgP7VqObJALrUA==
    ```

6.  Add the resulting signature to the request body:

    ```
    {
      "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
      "interval": {
        "from": "2020-01-01 14:53:55",
        "to": "2020-01-30 13:53:59"
      },
      "project_id": [
        183
      ],
      "limit": 3,
      "offset": 0,
      "tz": "Asia/Singapore",
     **"signature": "Ini3aKje6aZskajTuRS761YOzVqierlVRafZdxIz48wmVnL7yxgy9vDsp7T2/LGPGHJ/DHoKOgP7VqObJALrUA=="**
    }
    ```


### Signature verification form for Data API {#section_uct_5df_52c .section}

Below you can find an interactive form that allows you to test signature generation when sending the Data API requests.

**Note:** When working with the requests sent to the platform via the Data API and the responses to such requests, mind the restriction for signing multi-level nested data included in the payload. The signature is generated for data with three levels of nesting, and the data nested at deeper levels is ignored.



## Signature verification {#en_platform_signature_verification}

### Verification algorithm {#section_ub4_png_z3b .section}

The algorithm *input* includes the following:

1.  *Signed data* to verify.

    As a rule, it is a callback or response body in the JSON format with the `signature` parameter.

2.  Verification *key*. It must be the same key that was previously used for signing the data to verify.

Depending on the algorithm implementation, its *output* may be either a generated *signature* or the*information* whether the generated signature matches the one included in the response or callback.

The algorithm description, the examples, and test forms below use the most common algorithm implementation that includes a callback or response body in the JSON format as input \(without the `signature` parameter\) and the result of signature verification as output \(with the `signature` parameter\).

Thus, the *algorithm* includes *the following steps*:

1.  *Validating input*. Make sure the following requirements are met:

    1.  Data conforms to the JSON format.
    2.  Data to verify contains a `signature` parameter with the signature value.
    3.  The signing key is readily available.
2.  *Extracting the signature from the data to verify*. Store the value of the `signature` parameter value for further reference and remove the parameter from the input data.
3.  When working with the responses received from the platform via the Data API, at this step you need to replace values of all parameters nested at level four and deeper with empty strings. For example, in the response with operation information for a specified time period you need to remove key-value pairs of the following object: `"sum_initial": {"amount": 2000, "currency": "EUR"}`. Next, you need to replace the value of the parameter with an empty string `"sum_initial": ""` and then generate the signature. As for responses and callbacks received from other interfaces of the platform, there are no nesting depth restrictions, and, therefore, no actions to remove data are required.

4.  *Generating a signature for the data to verify*.
    1.  *Converting all strings to UTF-8 with parameters sorted in natural order*. Complete the following steps:
        1.  Encode any Boolean values as follows: replace `false` with `0`, replace `true` with `1`. Mind that this rule applies only to Boolean values. If any string parameter contains `"false"` or `"true"` string value, the value is not replaced with `0` or `1` but is treated as any other string value\(for example the `recurring: "{type: \"U\",register: true}"` parameter does not require replacing `true` with `1`\).
        2.  Convert each parameter into a string that contains the full path to the parameter \(with all its parents\), parameter name, and parameter value:

            ```language-c
            <*parent\_1*>:...:<*parent\_n*>:<*parameter\_name*>:<*parameter\_value*>
            ```

            where *parents* are the object\(s\) and/or arrays in which the parameter is contained. Parents are ordered by the embedding level starting with the topmost one. The parent names, parameter name, and parameter value are delimited by colon \(:\); delete any commas between key-value pairs and any quotation marks that delimit string values.

        3.  Leave any empty parameter values empty. In other words, do not replace any empty values with blank space or `null`. For instance, `"payment_description":""` is replaced with `payment_description:`.
        4.  Add index numbers to array elements starting with zero, for example, `["alpha", "beta", "gamma"]` is replaced with three strings: `0:alpha`, `1:beta`, and `2:gamma`.
        5.  Empty arrays are ignored and not included in the string set used to generate the signature.
        6.  Convert all strings to UTF-8.
        7.  Sort the strings in natural sort order and join them into a single string by using semicolon \(;\) as a delimiter.
    2.  *Calculating the HMAC code by using the key and the SHA-512 hash function*. Calculate the HMAC code for the string by using the SHA-512 hash function and secret key. The HMAC code must be calculated as raw binary data.
    3.  *Encoding the HMAC code by using the Base64 scheme*. Encode the HMAC code using Base64 to obtain the signature for the initial data.
5.  *Signature matching*. Compare the generated signature with the signature you have previously stored. If the signatures match, the data is authentic and its integrity is considered confirmed; otherwise, the data is considered compromised and cannot be used for production purposes.

### Example of callback verification {#section_fwr_3wj_1jb .section}

Suppose that you need to verify the signature of a callback in the following scenario:

-   Signing key : `secret`.
-   The callback body contains the following information:

    ``` {#codeblock_wh1_41j_1fc .language-json}
    {
        "customer": {
            "id": "782572"
        },
        "account": {
            "number": "424242******4242",
            "token": "c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2025"
        },
        "project_id": 28051,
        "payment": {
            "id": "5242723",
            "type": "purchase",
            "status": "success",
            "date": "2023-03-10T12:26:17+0000",
            "method": "card",
            "sum": {
                "amount": 5200,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 5200,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 5200,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6,
                "payment_id": "16784511766816",
                "auth_code": "563253",
                "endpoint_id": 6,
                "date": "2023-03-10T10:26:17+0000"
            },
            "id": 5028800010128225,
            "type": "sale",
            "status": "success",
            "date": "2023-03-10T12:26:17+0000",
            "created_date": "2023-03-10T12:26:15+0000",
            "request_id": "1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801"
        },
        "signature": "IszjSnH+UqFp88DF0giI/jUTDHOnfPxc83j2VD/jN4loB9wbHwiO5+KvHfdFE4nBPHhhxD6TXbOkGnRINFTTmg=="
    }
    ```


The signature is verified as follows:

1.  Remove the `signature` parameter and its value from the callback:

    ``` {#codeblock_yh1_41j_1fc .language-json}
    {
        "customer": {
            "id": "782572"
        },
        "account": {
            "number": "424242******4242",
            "token": "c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2025"
        },
        "project_id": 28051,
        "payment": {
            "id": "5242723",
            "type": "purchase",
            "status": "success",
            "date": "2023-03-10T12:26:17+0000",
            "method": "card",
            "sum": {
                "amount": 5200,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 5200,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 5200,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6,
                "payment_id": "16784511766816",
                "auth_code": "563253",
                "endpoint_id": 6,
                "date": "2023-03-10T10:26:17+0000"
            },
            "id": 5028800010128225,
            "type": "sale",
            "status": "success",
            "date": "2023-03-10T12:26:17+0000",
            "created_date": "2023-03-10T12:26:15+0000",
            "request_id": "1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801"
        },
        **"signature": "IszjSnH+UqFp88DF0giI/jUTDHOnfPxc83j2VD/jN4loB9wbHwiO5+KvHfdFE4nBPHhhxD6TXbOkGnRINFTTmg=="**
    }
    ```

2.  Convert all parameter strings to UTF-8 as per algorithm description:

    ``` {#codeblock_a31_41j_1fc .language-json}
    customer:id:782572
    account:number:424242******4242
    account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359
    account:type:visa
    account:card_holder:TEST TEST
    account:expiry_month:01
    account:expiry_year:2025
    project_id:28051
    payment:id:5242723
    payment:type:purchase
    payment:status:success
    payment:date:2023-03-10T12:26:17+0000
    payment:method:card
    payment:sum:amount:5200
    payment:sum:currency:EUR
    payment:description:
    operation:sum_initial:amount:5200
    operation:sum_initial:currency:EUR
    operation:sum_converted:amount:5200
    operation:sum_converted:currency:EUR
    operation:code:0
    operation:message:Success
    operation:provider:id:6
    operation:provider:payment_id:16784511766816
    operation:provider:auth_code:563253
    operation:provider:endpoint_id:6
    operation:provider:date:2023-03-10T10:26:17+0000
    operation:id:5028800010128225
    operation:type:sale
    operation:status:success
    operation:date:2023-03-10T12:26:17+0000
    operation:created_date:2023-03-10T12:26:15+0000
    operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801
    
    ```

3.  Sort the strings in natural sort order:

    ``` {#codeblock_pmt_lkp_31c .language-json}
    account:card_holder:TEST TEST
    account:expiry_month:01
    account:expiry_year:2025
    account:number:424242******4242
    account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359
    account:type:visa
    customer:id:782572
    operation:code:0
    operation:created_date:2023-03-10T12:26:15+0000
    operation:date:2023-03-10T12:26:17+0000
    operation:id:5028800010128225
    operation:message:Success
    operation:provider:auth_code:563253
    operation:provider:date:2023-03-10T10:26:17+0000
    operation:provider:endpoint_id:6
    operation:provider:id:6
    operation:provider:payment_id:16784511766816
    operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801
    operation:status:success
    operation:sum_converted:amount:5200
    operation:sum_converted:currency:EUR
    operation:sum_initial:amount:5200
    operation:sum_initial:currency:EUR
    operation:type:sale
    payment:date:2023-03-10T12:26:17+0000
    payment:description:
    payment:id:5242723
    payment:method:card
    payment:status:success
    payment:sum:amount:5200
    payment:sum:currency:EUR
    payment:type:purchase
    project_id:28051
    ```

4.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ``` {#codeblock_d31_41j_1fc}
    account:card_holder:TEST TEST;account:expiry_month:01;account:expiry_year:2025;account:number:424242******4242;account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359;account:type:visa;customer:id:782572;operation:code:0;operation:created_date:2023-03-10T12:26:15+0000;operation:date:2023-03-10T12:26:17+0000;operation:id:5028800010128225;operation:message:Success;operation:provider:auth_code:563253;operation:provider:date:2023-03-10T10:26:17+0000;operation:provider:endpoint_id:6;operation:provider:id:6;operation:provider:payment_id:16784511766816;operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801;operation:status:success;operation:sum_converted:amount:5200;operation:sum_converted:currency:EUR;operation:sum_initial:amount:5200;operation:sum_initial:currency:EUR;operation:type:sale;payment:date:2023-03-10T12:26:17+0000;payment:description:;payment:id:5242723;payment:method:card;payment:status:success;payment:sum:amount:5200;payment:sum:currency:EUR;payment:type:purchase;project_id:28051
    ```

5.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ``` {#codeblock_f31_41j_1fc}
    Y0qjN9dDnPTdddkVvXKS1pGp2z8ZpIl60P1CocND3YRxuBNx05ZMnhUaGFt90fPzgwsI/UpLw0q2RR/XTiDQBg==
    ```

6.  Compare the generated signature and the one included in the callback.

    In our case, the signatures differ which means that the callback is invalid and must be ignored.


### Signature verification form for callbacks {#section_h31_41j_1fc .section}

Below you can find an interactive form that allows you to test signature verification.

### Example of verifying a response via the Gate API {#section_eb4_nlm_xzb .section}

Suppose that you need to verify the signature of a response in the following scenario:

-   Signing key : `secret`.
-   The response body contains the following information:

    ```language-json
    {
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-23T10:54:37+0000",
            "method": "card",
            "sum": {
                "amount": 45000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "425000******0000",
            "token": "13n121******4991",
            "type": "visa",
            "card_holder": "****************",
            "expiry_month": "**",
            "expiry_year": "****"
        },
        "customer": {
            "id": "customer_007"
        },
        "operations": [
            {
                "id": 9529253065607,
                "type": "auth",
                "status": "success",
                "date": "2025-04-23T10:54:27+0000",
                "created_date": "2025-04-23T10:53:48+0000",
                "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd",
                "sum_initial": {
                    "amount": 45000,
                    "currency": "EUR"
                },
                "sum_converted": {
                    "amount": 45000,
                    "currency": "EUR"
                },
                "code": "0",
                "message": "Success",
                "eci": "05",
                "provider": {
                    "id": 3651,
                    "payment_id": "00000000123456",
                    "auth_code": "070707",
                    "endpoint_id": 0000,
                    "date": "2025-04-23T10:54:26+0000"
                }
            }
        ],
        "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
    }
    ```


The signature is verified as follows:

1.  Remove the `signature` parameter and its value.

    ```language-json
    {
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-23T10:54:37+0000",
            "method": "card",
            "sum": {
                "amount": 45000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "425000******0000",
            "token": "13n121******4991",
            "type": "visa",
            "card_holder": "****************",
            "expiry_month": "**",
            "expiry_year": "****"
        },
        "customer": {
            "id": "customer_007"
        },
        "operations": [
            {
                "id": 9529253065607,
                "type": "auth",
                "status": "success",
                "date": "2025-04-23T10:54:27+0000",
                "created_date": "2025-04-23T10:53:48+0000",
                "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd",
                "sum_initial": {
                    "amount": 45000,
                    "currency": "EUR"
                },
                "sum_converted": {
                    "amount": 45000,
                    "currency": "EUR"
                },
                "code": "0",
                "message": "Success",
                "eci": "05",
                "provider": {
                    "id": 3651,
                    "payment_id": "00000000123456",
                    "auth_code": "070707",
                    "endpoint_id": 0000,
                    "date": "2025-04-23T10:54:26+0000"
                }
            }
        ],
    **"signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="**
    }
    ```

2.  Convert all parameter strings to UTF-8 as per algorithm description:

    ```language-json
    project_id:200
    payment:id:abc12345
    payment:type:purchase
    payment:status:success
    payment:date:2025-04-23T10:54:37+0000
    payment:method:card
    payment:sum:amount:45000
    payment:sum:currency:EUR
    payment:description:
    account:number:425000******0000
    account:token:13n121******4991
    account:type:visa
    account:card_holder:****************
    account:expiry_month:**
    account:expiry_year:****
    customer:id:customer_007
    operations:0:id:9529253065607
    operations:0:type:auth
    operations:0:status:success
    operations:0:date:2025-04-23T10:54:27+0000
    operations:0:created_date:2025-04-23T10:53:48+0000
    operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd
    operations:0:sum_initial:amount:45000
    operations:0:sum_initial:currency:EUR
    operations:0:sum_converted:amount:45000
    operations:0:sum_converted:currency:EUR
    operations:0:code:0
    operations:0:message:Success
    operations:0:eci:05
    operations:0:provider:id:3651
    operations:0:provider:payment_id:00000000123456
    operations:0:provider:auth_code:070707
    operations:0:provider:endpoint_id:0
    operations:0:provider:date:2025-04-23T10:54:26+0000
    ```

3.  Sort the strings in natural sort order:

    ```language-json
    account:card_holder:****************
    account:expiry_month:**
    account:expiry_year:****
    account:number:425000******0000
    account:token:13n121******4991
    account:type:visa
    customer:id:customer_007
    operations:0:code:0
    operations:0:created_date:2025-04-23T10:53:48+0000
    operations:0:date:2025-04-23T10:54:27+0000
    operations:0:eci:05
    operations:0:id:9529253065607
    operations:0:message:Success
    operations:0:provider:auth_code:070707
    operations:0:provider:date:2025-04-23T10:54:26+0000
    operations:0:provider:endpoint_id:0
    operations:0:provider:id:3651
    operations:0:provider:payment_id:00000000123456
    operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd
    operations:0:status:success
    operations:0:sum_converted:amount:45000
    operations:0:sum_converted:currency:EUR
    operations:0:sum_initial:amount:45000
    operations:0:sum_initial:currency:EUR
    operations:0:type:auth
    payment:date:2025-04-23T10:54:37+0000
    payment:description:
    payment:id:abc12345
    payment:method:card
    payment:status:success
    payment:sum:amount:45000
    payment:sum:currency:EUR
    payment:type:purchase
    project_id:200
    ```

4.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ```
    account:card_holder:****************;account:expiry_month:**;account:expiry_year:****;account:number:425000******0000;account:token:13n121******4991;account:type:visa;customer:id:customer_007;operations:0:code:0;operations:0:created_date:2025-04-23T10:53:48+0000;operations:0:date:2025-04-23T10:54:27+0000;operations:0:eci:05;operations:0:id:9529253065607;operations:0:message:Success;operations:0:provider:auth_code:070707;operations:0:provider:date:2025-04-23T10:54:26+0000;operations:0:provider:endpoint_id:0;operations:0:provider:id:3651;operations:0:provider:payment_id:00000000123456;operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd;operations:0:status:success;operations:0:sum_converted:amount:45000;operations:0:sum_converted:currency:EUR;operations:0:sum_initial:amount:45000;operations:0:sum_initial:currency:EUR;operations:0:type:auth;payment:date:2025-04-23T10:54:37+0000;payment:description:;payment:id:abc12345;payment:method:card;payment:status:success;payment:sum:amount:45000;payment:sum:currency:EUR;payment:type:purchase;project_id:200
    ```

5.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ```
    qUVvwChGUOSWRXwKQI6ZIkKvvWJsvx2luS8cYvN+M7iRiBAKkGE+WwfgAztgGU+vZNMr2bd4Lnn0J0KkhwYS1A==
    ```

6.  Compare the generated signature and the one included in the response.

    In our case, the signatures differ which means that the response is invalid and must be ignored.


### Signature verification form for responses via the Gate API {#section_ay4_wdf_52c .section}

Below you can find an interactive form that allows you to test signature verification.

### Example of verifying a response via the Data API {#section_hvv_q1j_1fc .section}

Suppose that you need to verify the signature of a response in the following scenario:

-   Signing key : `secret`.
-   The response body contains the following information:

    ``` {#codeblock_kvv_q1j_1fc .language-json}
    {
      "operations": [
        {
          "project_id": "183",
          "operation_id": "9048253065548",
          "payment_id": "EP834a-40521580376090593",
          "operation_type": "cancel",
          "operation_status": "success",
          "account_number": "431422******0056",
          "customer_ip": "192.0.0.255",
          "payment_method_name": "visa",
          "payment_method_type": "visa",
          "payment_description": null,
          "operation_created_at": "2020-01-30T12:29:03+03:00",
          "operation_completed_at": "2020-01-30T12:29:04+03:00",
          "provider_date": null,
          "shipment_date": "",
          "mid": "3416123",
          "sum_initial": {
            "amount": 2000,
            "currency": "EUR"
          },
          "sum_converted": {
            "amount": 2000,
            "currency": "EUR"
          },
          "provider_name": "Dashboard Provider Card",
          "fee_currency": null,
          "fee_amount": 0,
          "arn": null,
          "rrn": null
        }
      ],
      "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
      }
    ```


The signature is verified as follows:

1.  Remove the `signature` parameter and its value.

    ``` {#codeblock_znl_nx3_1fc .language-json}
    {
      "operations": [
        {
          "project_id": "183",
          "operation_id": "9048253065548",
          "payment_id": "EP834a-40521580376090593",
          "operation_type": "cancel",
          "operation_status": "success",
          "account_number": "431422******0056",
          "customer_ip": "192.0.0.255",
          "payment_method_name": "visa",
          "payment_method_type": "visa",
          "payment_description": null,
          "operation_created_at": "2020-01-30T12:29:03+03:00",
          "operation_completed_at": "2020-01-30T12:29:04+03:00",
          "provider_date": null,
          "shipment_date": "",
          "mid": "3416123",
          "sum_initial": {
            "amount": 2000,
            "currency": "EUR"
          },
          "sum_converted": {
            "amount": 2000,
            "currency": "EUR"
          },
          "provider_name": "Dashboard Provider Card",
          "fee_currency": null,
          "fee_amount": 0,
          "arn": null,
          "rrn": null
        }
      ],
    **  "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="**
    }
    ```

2.  Replace the data nested at the fourth level with an empty string:

    ``` {#codeblock_g4b_fhq_1fc .language-json}
    {
      "operations": [
        {
          "project_id": "183",
          "operation_id": "9048253065548",
          "payment_id": "EP834a-40521580376090593",
          "operation_type": "cancel",
          "operation_status": "success",
          "account_number": "431422******0056",
          "customer_ip": "192.0.0.255",
          "payment_method_name": "visa",
          "payment_method_type": "visa",
          "payment_description": null,
          "operation_created_at": "2020-01-30T12:29:03+03:00",
          "operation_completed_at": "2020-01-30T12:29:04+03:00",
          "provider_date": null,
          "shipment_date": "",
          "mid": "3416123",
          **"sum\_initial": \{
            "amount": 2000,
            "currency": "EUR"
          \},**
          **"sum\_initial":"",**
          **"sum\_converted": \{
            "amount": 2000,
            "currency": "EUR"
          \},**
          **"sum\_converted":"",**
          "provider_name": "Dashboard Provider Card",
          "fee_currency": null,
          "fee_amount": 0,
          "arn": null,
          "rrn": null
        }
      ]
    }
    ```

3.  Convert all parameter strings to UTF-8 as per algorithm description:

    ``` {#codeblock_pvv_q1j_1fc .language-json}
    operations:0:project_id:183
    operations:0:operation_id:9048253065548
    operations:0:payment_id:EP834a-40521580376090593
    operations:0:operation_type:cancel
    operations:0:operation_status:success
    operations:0:account_number:431422******0056
    operations:0:customer_ip:192.0.0.255
    operations:0:payment_method_name:visa
    operations:0:payment_method_type:visa
    operations:0:payment_description:
    operations:0:operation_created_at:2020-01-30T12:29:03+03:00
    operations:0:operation_completed_at:2020-01-30T12:29:04+03:00
    operations:0:provider_date:
    operations:0:shipment_date:
    operations:0:mid:3416123
    operations:0:sum_initial:
    operations:0:sum_converted:
    operations:0:provider_name:Dashboard Provider Card
    operations:0:fee_currency:
    operations:0:fee_amount:0
    operations:0:arn:
    operations:0:rrn:
    ```

4.  Sort the strings in natural sort order:

    ``` {#codeblock_rvv_q1j_1fc .language-json}
    operations:0:account_number:431422******0056
    operations:0:arn:
    operations:0:customer_ip:192.0.0.255
    operations:0:fee_amount:0
    operations:0:fee_currency:
    operations:0:mid:3416123
    operations:0:operation_completed_at:2020-01-30T12:29:04+03:00
    operations:0:operation_created_at:2020-01-30T12:29:03+03:00
    operations:0:operation_id:9048253065548
    operations:0:operation_status:success
    operations:0:operation_type:cancel
    operations:0:payment_description:
    operations:0:payment_id:EP834a-40521580376090593
    operations:0:payment_method_name:visa
    operations:0:payment_method_type:visa
    operations:0:project_id:183
    operations:0:provider_date:
    operations:0:provider_name:Dashboard Provider Card
    operations:0:rrn:
    operations:0:shipment_date:
    operations:0:sum_converted:
    operations:0:sum_initial:
    ```

5.  Join all strings into a single string by using semicolon \(;\) as a delimiter:

    ``` {#codeblock_f4l_nx3_1fc}
    operations:0:account_number:431422******0056;operations:0:arn:;operations:0:customer_ip:192.0.0.255;operations:0:fee_amount:0;operations:0:fee_currency:;operations:0:mid:3416123;operations:0:operation_completed_at:2020-01-30T12:29:04+03:00;operations:0:operation_created_at:2020-01-30T12:29:03+03:00;operations:0:operation_id:9048253065548;operations:0:operation_status:success;operations:0:operation_type:cancel;operations:0:payment_description:;operations:0:payment_id:EP834a-40521580376090593;operations:0:payment_method_name:visa;operations:0:payment_method_type:visa;operations:0:project_id:183;operations:0:provider_date:;operations:0:provider_name:Dashboard Provider Card;operations:0:rrn:;operations:0:shipment_date:;operations:0:sum_converted:;operations:0:sum_initial:
    ```

6.  Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:

    ``` {#codeblock_h4l_nx3_1fc}
    F58IW7JCqHsUthlmgQ/i1plf6lRPfdSVTGMXeEfhUMpdmwDMHKlO/rbtTy+V8cmQtvPNBjvuyQnl/rWxT7gPGg==
    ```

7.  Compare the generated signature and the one included in the response.

    In our case, the signatures differ which means that the response is invalid and must be ignored.


### Signature verification form for responses via the Data API {#section_itb_s1j_1fc .section}

Below you can find an interactive form that allows you to test signature verification.

**Note:** When working with the requests sent to the platform via the Data API and the responses to such requests, mind the restriction for signing multi-level nested data included in the payload. The signature is generated for data with three levels of nesting and the data nested at deeper levels is ignored.



---

# Handling payment processing information {#en_platform_payment_information}

Articles about receiving and processing data about payments executed via the platform in order to analyse, monitor, and respond to payment processing activity.

To implement efficient processes of monitoring, analysing, and responding when working with the payment platform, you need to configure receiving and processing payment information. This section contains essential information that can help you with setting up:

-   [Overview](en_platform_payment_information_overview.md)—a brief review of main ways to receive and process information about payments and operations, with the description of key differences and specific characteristics.
-   [Handling callbacks](en_platform_callbacks.md)—an article about working with callbacks which are programmatic messages that allow you to receive up-to-date information significant for processing of each payment.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—an article about statuses and codes that are used in the platform to communicate the statuses of operations in progress and the reasons for declines.

In addition, to learn more about working with payment information, you can refer to:

-   An article about sending requests to the the Gate API in order to receive current information about individual payments—[Checking current payment information](en_Gate_payment_status_request.md).
-   Articles about using interfaces that provide you with different options to monitor payment processing—[Dashboard](en_dbl_about.md)and [Using Data API](en_dbl_api_protocol.md).

-   **[Overview](en_platform_payment_information_overview.md)**  
An article with a brief review comparing main ways of receiving and processing information about payments and operations.
-   **[Handling callbacks](en_platform_callbacks.md)**  
An article about working with callbacks which are programmatic messages that allow merchants to receive up-to-date information significant for processing of each payment, includes the description of callback types and data structures used in them.
-   **[Handling operation processing information](en_platform_payment_info_codes.md)**  
An article about statuses and codes that are used in the platform to communicate the statuses of operations and the reasons for declines.

**Parent topic:**[Platform](en_platform_about.md)



---

# Overview {#en_platform_payment_information_overview}

An article with a brief review comparing main ways of receiving and processing information about payments and operations.

When payments are processed, it is important for merchants to remain timely informed. They need to monitor statuses of individual payments and operations, consolidated payment processing results filtered by different attributes, finalised financial data, and so on. The platform offers a wide range of specific capabilities to ensure that merchants stay up-to-date on all necessary data required for accomplishing these tasks. The main capabilities are:

-   *Receiving callbacks*. If you need your web service to be automatically updated with the current information about individual payments, use callbacks \([learn more](en_platform_callbacks.md)\). They are sent from the platform to the web service in predetermined cases and contain a flexibly configured set of parameters and a signature.Callbacks can be sent without any delay when their trigger event is registered in the platform or with a specified delay.

    When payments are processed via Gate, you are required to set up handling of the *prescriptive* callbacks that are triggered by the necessity of a certain action. In other cases, you can opt out of receiving callbacks, but it is highly recommended that you use them because callbacks are the fastest and the most reliable option for obtaining information about each payment.

-   *Using the Gate API.* If you need to receive up-to-date information about individual payments within the time period determined by the web service specifics and not the platform\(for example, when certain events occur in the web service, or at a specified time after the payment was initiated\), you can use specialised requests to the Gate API \([learn more](en_Gate_payment_status_request.md)\). Payment status requests are synchronous: the responses to them are sent within one HTTP session and contain a configurable set of parameters and a signature.As in case with callbacks, responses to payment status requests provide immediate information, updated without delays.
-   *Using the Data API*. If you need automated retrieval of data on payment processing results for specific time periods, you can use the Data API \([learn more](en_dbl_api_protocol.md)\).This can be relevant, for example, when you utilise the in-house or external BI system either instead of Dashboard or as a supplementary tool. The Data API allows you to retrieve operation data\(including fraudulent operation data\), chargeback data, and balance information.Since the Data API retrieves information from a remote long-term storage, it can take up to several minutes for updates to be reflected.
-   *Using the Dashboard interface*. If you need to receive up-to-date information about payment processing results via a user interface, you can use Dashboard \([learn more](en_dbl_about.md)\). This interface ensures a comprehensive approach to working with payment processing data: it allows you to monitor information about payments and operations from different angles and use various registries, information tabs, and reports.In addition, Dashboard allows you not only to view different information, but also to perform a number of actions to manage payments, whitelists and blacklists of payment criteria, chargebacks, balances, and so on. At the same time, keep in mind that as in the case with the Data API, Dashboard retrieves information from a remote long-term storage, so it can take up to several minutes for updates to be reflected.

Along with that, when you work with specific tools\(for example, with SDKs for mobile applications\), there can be other ways to receive payment processing information. They are described in the articles about these tools and can be used in addition to the main capabilities described above.

Overall, it should be noted that the most up-to-date information is available via callbacks and requests to the Gate API, the most exhaustive—via Dashboard and the Data API, while the most convenient way to deal with payment processing information is to combine available capabilities with consideration to the web service specifics. To learn more about this topic, explore this documentation or contact the technical support.

**Parent topic:**[Handling payment processing information](en_platform_payment_information.md)



---

# Handling callbacks {#en_platform_callbacks}

An article about working with callbacks which are programmatic messages that allow merchants to receive up-to-date information significant for processing of each payment, includes the description of callback types and data structures used in them.

**Parent topic:**[Handling payment processing information](en_platform_payment_information.md)

## Overview {#en_callbacks_overview}

### Introduction {#section_zcz_nrw_z5b .section}

A *callback* is a system message sent from the Ecommpay payment platform to the merchant's web service. It contains information about a specific event in the payment platform that usually takes place in the context of processing a paymentor storing customer payment data.

Callbacks allow merchants to receive information about various events. Along with that, the callback payload as well as the conditions of sending callbacks can be flexibly configured: you can define what data the callback should contain as well as specify in what cases, in what format, and where it should be sent. This article covers general information about callbacks, the procedure and special aspects of working with them.

### Callback types {#section_idc_bsw_z5b .section}

Callbacks can be roughly divided into two groups: *prescriptive* \(that require certain actions from the web service side\) and *informational* \(that are sent for informational purposes\).

Prescriptive callbacks are triggered by the necessity of a certain action: for example, specific data has to be sent to the payment platform, the customer must be provided with specific information or redirected to third-party services, and so on. Such callbacks always contain intermediate information, and you cannot opt out of receiving them since timely response to this category of callbacks is indispensable for payments to be processed correctly.

Informational callbacks are triggered by such events as the change of the payment status or the generation of the payment card token. These callbacks can contain intermediate or final payment information, and you can opt out of receiving them \(selectively or fully\).

**Note:** Even if you decide not to receive informational callbacks, there still remain other options for obtaining payment information. These options include sending requests via the Gate API \([details](en_Gate_payment_status_request.md)\) andthe Data API \([details](en_dbl_using_api.md)\) as well as using the tools of the Dashboard interface. At the same time, callbacks are the fastest and the most reliable option for obtaining information \(with the confirmation of the information receipt\), and opting out of callbacks receipt should take place only in reasonable cases when it aligns with the aspects of the web service operation.

### Common use cases {#section_jpr_31m_1vb .section}

Callbacks are typically triggered by the following events.

-   *Payment status has changed.*

    In this case, callbacks can contain intermediate or final information about payment processing.

    ```language-json
    {
        "project_id": 42,
        "customer": {
            "id": "6361696170"
        },
        "payment": {
            "id": "456789",
            "type": "purchase",
            "status": "awaiting capture",      // intermediate payment status
            "date": "2022-01-11T13:00:40+0000",
            "method": "card",
            "sum": {
                "amount": 20000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056 ",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "03",
            "expiry_year": "2026"
        },
        "operation": {
            "id": 2777000002350,
            "type": "auth",
            "status": "success",
            "date": "2022-01-11T13:00:40+0000",
            "created_date": "2022-01-11T13:00:37+0000",
            "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
            "sum_initial": {
                "amount": 20000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "USD"
            },
            "provider": {
                "id": 120,
                "payment_id": "224750650",
                "date": "2022-01-11T13:00:39+0000",
                "result_code": "000",
                "result_message": "Approved",
                "auth_code": "505050",
                "endpoint_id": 120
            },
            "code": "0",
            "message": "Success",
            "description": "SUCCESS",
            "eci": "00"
        },
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
    }
    ```

    ```language-json
    {
        "project_id": 42,
        "payment": {
            "id": "456789",
            "type": "purchase",
            "status": "success",      // final payment status
            "date": "2022-01-11T15:54:40+0000",
            "method": "card",
            "sum": {
                "amount": 20000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056 ",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "03",
            "expiry_year": "2026"
        },
        "customer": {
            "id": "6361696170"
        },
        "operation": {
            "id": 7178000006597,
            "type": "capture",
            "status": "success",
            "date": "2022-01-11T15:54:40+0000",
            "created_date": "2022-01-11T15:54:39+0000",
            "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
            "sum_initial": {
                "amount": 20000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "USD"
            },
            "provider": {
                "id": 120,
                "payment_id": "227307324",
                "date": "2022-01-11T15:54:40+0000",
                "auth_code": "919372",
                "endpoint_id": 120
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
    }
    ```

-   *Actions on the web service side are required.*

    In this case, callbacks usually contain information for redirecting customers, displaying specific information to them, or specifying additional data necessary for payment processing.

    ```language-json
    "redirect_data":{
        "method": "GET",
        "body": [],
        "encrypted": [], 
        "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
      }
    ```

    ```language-json
     "display_data": [
                {
                    "type": "qr_data",
                    "title": "QR code",
                    "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
                },
                {
                    "type": "add_info",
                    "title": "QR Code Timeout",
                    "data": "600"
                }
            ]
    ```

-   *Payment card token has been generated or deleted.*

    In this case, callbacks contain information about events related to payment card tokens \(such as token generation or deletion\).

    ```language-json
    {
        "general":{
        "project_id":42,
        "customer_id":6361696170,
        "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ",
            "request": {
    			"id": "3c7f53fdbb5b8c96f9707457d75f",
    			"action": "tokenize",
    			"status": "success"
            },
        "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654",
        "token_created_at":"2021-01-28 13:30:57",
        "token_status":"active"
    }
    ```


## Setup and configuration {#en_callbacks_configuration}

### Configuring for projects {#section_jlb_dcm_1vb .section}

Callbacks for the merchant's production projects are usually set up during the integration of the web service with the Ecommpay payment platform. Along with that, to change callback settings, you can always use the capabilities of Dashboard \([details](en_dbl_projects.md)\), specify certain parameters in payment requests, and when necessary, contact the Ecommpay technical support specialists.

The following properties can be configured on the part of the merchant:

-   Requirement for sending callbacks.

    Callbacks can be triggered by all events or only by the events that correspond to the specified set of conditions.Such conditions include certain event types, payment methods as well as types and statuses of payments and operations.For example, callbacks can be disabled for the completed payouts and enabled for the declined ones. This allows you to promptly receive only the necessary information.

-   URLs for delivering callbacks.

    Callbacks triggered by different events can be sent to different web service URLs with regard to the event type,the payment method, the payment type and status. For example, callbacks with final information about declined payments can be sent to one URL, while callbacks with final information about completed payments can be sent to another URL.

-   Delay time for sending callbacks.

    If necessary, callbacks can be sent with a delay of up to 600 seconds \(inclusive\), for example, to streamline the handling of these callbacks on the web service side.

-   Set of parameters.

    For more convenient handling of callbacks on the web service side, you can vary their payload by adding and removing parameters, changing their names, and setting the requirement to include parameters with empty values. At the same time, you cannot change the callback structure and remove required parameters.

    Bear in mind that certain parameters can be required for all or only specific types of callbacks. The required parameters are always included in callbacks, while the optional ones are only sent in cases when the corresponding information has been received, or when sending such parameters with empty values has been set up.

    Thus, callbacks triggered by the same events can include different information depending on the settings.

    ```language-json
    {
        "account": {
            "number": "431422******0056 ",
            "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "11",
            "expiry_year": "2027"
        },
        "customer": {
            "id": "6361696170",
            "phone": "441223262463"
        },
        "payment": {
            "date": "2022-11-11T13:02:42+0000",
            "id": "456789",
            "method": "card",
            "status": "success",
            "sum": {
                "amount": 40000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": ""
        },
        "project_id": 42,
        "operation": {
            "id": 969000002636,
            "type": "sale",
            "status": "success",
            "date": "2022-11-11T13:02:42+0000",
            "created_date": "2022-11-11T13:01:45+0000",
            "request_id": "c6eed1eb14c6290088cbc0be4667c",
            "sum_initial": {
                "amount": 40000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "USD"
            },
            "provider": {
                "id": 408,
                "payment_id": "330157196",
                "date": "2022-11-11T13:02:32+0000",
                "auth_code": "",
                "endpoint_id": "612266625"
            },
            "code": "0",
            "message": "Success",
            "eci": "07"
        },
        "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
    ```

    ```language-json
    {
        "account": {
            "number": "431422******0056 ",
            "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "id": 45678,
            "expiry_month": "11",
            "expiry_year": "2027"
        },
        "customer": {            // object with extended customer information
            "id": "6361696170",
            "email": "siraseddington@gmail.com"
            "phone": "441223262463",
            "first_name": "Arthur",
            "last_name": "Eddington"
        },
        "payment": {
            "date": "2022-11-11T13:02:42+0000",
            "id": "456789",
            "method": "card",
            "status": "success",
            "sum": {
                "amount": 40000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": ""
        },
        "project_id": 42,
        "operation": {
            "id": 969000002636,
            "type": "sale",
            "status": "success",
            "date": "2022-11-11T13:02:42+0000",
            "created_date": "2022-11-11T13:01:45+0000",
            "request_id": "c6eed1e088cbc0be4667c",
            "sum_initial": {
                "amount": 40000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "USD"
            },
            "provider": {
                "id": 408,
                "payment_id": "330157196",
                "date": "2022-11-11T13:02:32+0000",
                "auth_code": "",
                "endpoint_id": "612266625"
            },
            "code": "0",
            "message": "Success",
            "eci": "07"
        },
        "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...=="
    }
    ```


### Managing callbacks for individual payments {#section_kld_ffm_1vb .section}

When processing payments via Gate, you can set up the URLs where callbacks will be delivered to, the requirement, and the delay time for sending callbacks. To do this, use the following parameters when sending payment requests:

-   `merchant_callback_url` \(passed in the `general` object\)—the callback URL for this specific request;
-   `force_disable` \(passed in the `callback` object\)—an indicator for disabling callbacks \(possible values: `true`, for disabling callbacks with information about the given payment, and `false`, for enabling these callbacks\).
-   `delay` \(passed in the `callback` object\)—the delay time for sending callbacks, in seconds \(possible values are 0 to 600; for example `42`\);

To learn if these parameters can be used in requests to certain endpoints, see [the Gate API](https://api-developers.ecommpay.com/) specification.

```language-json
{
    "general":{
        "project_id":42,
        "payment_id":"456789",
        "merchant_callback_url":"https://example.com",
        "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "customer":{
        "ip_address":"192.0.2.32",
        "id":"6361696170"
    },
    "payment":{
        "amount":40000,
        "currency":"USD",
        "callback":{
            "delay":42                // delay time set to 42 seconds
        }
    },
    "card":{
        "pan":"4314220000000056",
        "year":2027,
        "month":11,
        "card_holder":"ARTHUR EDDINGTON",
        "cvv":"123"
    }
}
```

## Use {#en_callbacks_usage}

### Handling callbacks {#section_nc3_vkm_1vb .section}

A callback is an HTTP POST message sent to the URL provided by the merchant. The procedure of responding to each callback on the web service side consists of the following steps:

1.  Accept and verify the callback.

    Callbacks should be accepted only if they have been sent from the payment platform's IP addresses provided by the Ecommpay technical support specialists. Along with that, it is recommended not to limit the waiting time for callbacks since different events can occur at different times while callbacks can be sent with a specified delay.

    The callback sender and data integrity should be validated by way of verifying the signature included in every callback. For more information, see [Signature generation and verification](en_platform_signature.md).

2.  Confirm the callback receipt.

    For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes. If no errors have been detected upon the receipt, the response code should be `200 OK`. In other cases, the response code should correspond to the error type: for example, use `HTTP 400 Bad Request` if a parameter string could not be converted into an array or `HTTP 500 Internal Server Error` if the callback has been received at an incorrect URL of the web service.

    If the `200 OK` response has not been received from the web service, the callback will be sent again regardless of the error type.

3.  Perform the required actions.

    Upon the receipt of prescriptive callbacks, the actions that are stated in these callbacks as required should be performed; and upon the receipt of informational callbacks, the actions that correspond to the aspects of the web service operation should be performed \(for example, customer notification\).


### Resending callbacks {#section_qc3_vkm_1vb .section}

If the information about a callback receipt error has been communicated to the payment platform or the callback receipt has not been confirmed, this callback is sent again. Keep in mind that the data in such callbacks can change due to the changes of the corresponding information in the payment platform: for example, if a payment status changes, all subsequent callbacks contain the newly assigned status.

Generally, resending callbacks is carried out as follows:

1.  6 attempts at an increasing interval of 10 to 60 seconds.The interval increases by 10 seconds at each attempt.
2.  58 attempts at an increasing interval of 84 seconds to 2.5 hours.

    The interval, measured in seconds, is increased according to the formula `70 + 10 × 1.12n − 4` where *n* is the sequence number of the attempt.

3.  56 attempts every 4 hoursuntil a total of 120 attempts is reached. After that, callbacks triggered by the given event are no longer sent.

This order can slightly change depending on the load on servers and communication channels, but in general the time span for automatic callback delivery attempts does not exceed 11 days. You can change this order via the Ecommpay technical support specialists.

In addition to automatic resending of callbacks, you can also initiate one-time resending via Dashboard.

### Troubleshooting {#section_tc3_vkm_1vb .section}

There can be cases when callbacks are not received at the specified URLs for various reasons. These situations and the ways to resolve them can be divided into the following groups:

-   *There are no callbacks triggered by any of the events.*

    This can happen because certain requests and events have not been initiated in the platform, or issues with communication channels have been detected, or the web service URLs are invalid, or callbacks have been disabled in the project.

    In such cases, it is recommended to proceed as follows:

    1.  Ensure that the correct requests\(i.e. they do not disable callbacks\) were sent from the web service and accepted in the platform. It may be necessary to send a test request, for example, to generate a payment card token.
    2.  If requests are accepted in the platform, but callbacks are still not received, check if the URLs for delivering callbacks are correct. If problems are found, fix the URLs or replace them with the correct ones—on your own via Dashboard, or with the help of the Ecommpay technical support specialists.
    3.  If the previous steps did not help, contact the Ecommpay technical support specialists.
-   *There are no callbacks triggered by specific event types.*

    This can happen for the following reasons: there are no events of such types, web service URLs are invalid, or callbacks have been disabled for such event types.

    In such cases, it is recommended to proceed as follows:

    1.  Ensure that the events of the types for which callbacks are not received have been initiated. You can do this by using payment information tabs in the Dashboard interface.
    2.  Check the correctness of the URLs for receiving callbacks triggered by the corresponding event types. If problems are found, fix the URLs or replace them by the correct ones—on your own via Dashboard, or with the help of the Ecommpay technical support specialists.
    3.  If the previous steps did not help, contact the Ecommpay technical support specialists.
-   *There are no callbacks for a specific operation.*

    This can happen because the `callback` object in the request for processing the operation contains the `force_disable` parameter with the `true` value.

    In this case, you can check the operation status via Gate using requests for checking current payment information\([details](en_Gate_payment_status_request.md)\),[Dashboard](en_dbl_payments.md).


## Callback parameters {#en_callbacks_parameters}

### Callback parameters for payments and operations {#section_e4h_s5m_1vb .section}

The set of parameters sent in callbacks with payments and operations information can be standard or customised for separate projects. The following table contains the standard set of parameters.

|Parameter|Description|tree|
|---------|-----------|----|
|account   
 object, optional

|Object with the customer's payment details\(for example, the details of a payment card, an account, or a digital wallet\).|10|
|card\_holder  
 string, optional

|Cardholder's name.

 Example: `ARTHUR EDDINGTON`

|10-10 10|
|expiry\_month  
 string, optional

|Payment card expiration month.

 Example: `11`

|10-20 10|
|expiry\_year  
 string, optional

|Payment card expiration year.

 Example: `2027`

|10-30 10|
|id  
 integer, optional

|Saved payment data identifier used in the payment platform\([details](en_gate_saved_data.md)\).

 Example: `56789`

|10-40 10|
|number   
 string, required

|Masked number or another identifier of the customer's payment instrument \(for example, a payment card, an account, or a digital wallet\).

 Example: `424242***4243`

|10-50 10|
|token   
 string, optional

|Payment card token if it has been generated during the request execution\([details](en_Gate_Token.md)\).

|10-60 10|
|type  
 string, optional

|Payment card brand that was used in the processing of the payment: `amex`,`mastercard`, `maestro`, `visa`and others|10-70 10|
|acs  
 object, optional

|Object with information about the result of the customer's 3‑D Secure authentication.|20|
|acs\_url  
 string, required

|URL of the page to which the customer is redirected for the 3‑D Secure authentication \(ACS page\).

|20-10 20|
|md  
 string, required

|Merchant data received from a global card network during the customer's 3‑D Secure authentication.

|20-20 20|
|pa\_req  
 string, required

|PAReq \(Payer Authentication Request\) message received during the customer's 3‑D Secure authentication 3‑D Secure.|20-30 20|
|avs\_data  
 object, optional

|Object with information about the Address Verification Service check \(AVS, [details](en_Gate_avs.md)\)|30|
|avs\_post\_code  
 string, optional

|Customer's postal code passed for performing the AVS check.

 Example: `BS23 1XF`

|30-10 30|
|avs\_street\_address  
 string, optional

|Customer's address passed for performing the AVS check.

 Example: `42 Walliscote Road, Weston-super-Mare`

|30-20 30|
|avs\_result  
 string, optional

|Code of the AVS check result \([details](en_Gate_avs.md)\).

 Example: `F`

|40|
|bank  
 object, optional

|Object with information about the issuer of the payment card used during payment processing.|50|
|name  
 string, optional

|Issuer's name in the payment platform.

 Example: `LLOYDS`

|50-10 50|
|customer   
 object, optional

|Object with customer information.|70|
|billing  
 object, optional

|Object with information about the customer's billing address received in the payment platform during payment processing.|70-10 70|
|address  
 string, optional

|Street name specified in the customer's billing address.

 Example: `Walliscote Road`

|70-10-10 70-10|
|city  
 string, optional

|City name specified in the customer's billing address.

 Example: `Weston-super-Mare`

|70-10-20 70-10|
|country  
 string, optional

|ISO 3166-1 alpha-2 code of the country specified in the customer's billing address.

 Example: `GB`

|70-10-30 70-10|
|postal  
 string, optional

|Postal code specified in the customer's billing address.

 Example: `BS23 1XF`

|70-10-40 70-10|
|region  
 string, optional

|Name of the state, province, or region specified in the customer's billing address.

 Example: `Somerset County`

|70-10-50 70-10|
|city  
 string, optional

|Name of the customer's city.Example: `Weston-super-Mare`

|70-20 70|
|country  
 string, optional

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|70-30 70|
|day\_of\_birth  
 string, optional

|Customer's birth date in the format of DD-MM-YYYY.

 Example: `22-12-1882`

|70-40 70|
|first\_name  
 string, optional

|Customer's name.

 Example: `Arthur`

|70-50 70|
|id   
 string, optional

|Customer's identifier within the merchant's project.

 Example: `6361696170`

|70-60 70|
|ip\_address  
 string, required

|Customer's IP address relevant for the given operation.

 Example: `192.0.2.32`

|70-70 70|
|last\_name  
 string, optional

|Customer's last name.Example: `Eddington`

|70-80 70|
|middle\_name  
 string, optional

|Customer's middle name.Example: `Stanley`

|70-90 70|
|phone   
 string, optional

|Customer's phone number that contains 4 to 24 digits.

 Example: `441223262463`

|70-100 70|
|decision  
 string, optional

|String with information about payment processing admissibility assessment performed on the payment platform side.|80|
|decision\_message  
 array, optional

|Array of records with information about payment processing admissibility assessment performed on the payment platform side.

 Example: `reject.message("RCS reject. Amount less than allowed")`

|90|
|display\_data  
 object, optional

|Object with information that should be displayed to the customer.

 This object usually contains the data received from a provider or a payment system.The specifics of what information has to be displayed for various payment methods are usually described in the articles about these methods.

 Example: `Approve the payment request sent to your phone`

|100|
|errors   
 array, optional

|Array of error messages received during request execution.|110|
|ErrorItem  
 object, required

|Object with information about the error that occurred during request execution.|110-10 110|
|code  
 integer, optional

|Error code.

 Example: `3287`

|110-10-10 110-10|
|description  
 string, optional

|Error reason details.

 Example: `EMPTY_REFUND_CURRENCY`

|110-10-10 110-10|
|field  
 string, optional

|Name of the parameter that was erroneously specified \(if such parameter is identified\).|110-10-20 110-10|
|message  
 string, optional

|Error code description.

 Example: `The property currency is required`

|110-10-30 110-10|
|interface\_type  
 object, optional

|Object with information about the way the payment was initiated.|120|
|id  
 integer, optional

|Indicator of the interface that was used for sending the initial request:-   `1`—request was sent via Gate.
-   `5`—request was sent via Dashboard.
-   `6`—request was sent via Payment Page opened in a modal window.
-   `7`—request was sent via Payment Page opened in an iframe object.

|120-10 120|
|user  
 string, optional

|Details about an account of the Dashboard user who sent the initial request.

 Example: `janedoe@cosmoshop.com`

|120-20 120|
|operation  
 object, optional

|Object with information about the operations related to the payment.|130|
|code  
 string, optional

|Code of the operation status \([details](en_platform_payment_info_codes.md)\).

 Example: `0`

|130-10 130|
|created\_date  
 string, optional

|Date and time of the operation creation.

 Example: `2022-10-08T18:52:19+0000`

|130-20 130|
|date  
 string, optional

|Date and time of the latest change of the operation status in the payment platform.

 Example: `2022-10-08T18:52:54+0000`

|130-30 130|
|eci  
 string, optional

|Indicator of the customer's 3‑D Secure authentication result \([details](en_ECI_codes.md)\).

 Example: `07`

|130-40 130|
|id  
 integer, optional

|Operation identifier in the payment platform.

 Example: `17007255`

|130-50 130|
|message  
 string, optional

|Description of the operation status code \([details](en_platform_payment_info_codes.md)\).

 Example: `Success`

|130-60 130|
|provider  
 object, optional

|Object with the payment result information received from a providerora payment system.|130-70 130|
|auth\_code  
 string, optional

|Authorisation code received from a providerora payment system.

 Example: `331040`

|130-70-10 130-70|
|date  
 string, optional

|Date and time of the payment processing completion on a providerora payment system side.

 Example: `2022-10-08T18:52:53+0000`

|130-70-20 130-70|
|endpoint\_id  
 string \(integer\), optional

|CRC32 identifier of the payment gateway of a providerora payment system.

 Example: `2`

|130-70-30 130-70|
|id  
 integer, optional

|Identifier of a providerora payment system in the payment platform.

 Example: `2`

|130-70-40 130-70|
|payment\_id  
 string, optional

|Payment identifier on a providerora payment system side.

 Example: `603458`

|130-70-50 130-70|
|recurring\_retry  
 object, optional

|Object with the information about retrying the debit operation executed as part of the regular COF purchase \([details](en_Gate__cof_gate_side.md)\).|130-75 130|
|next\_retry\_date  
 string, optional

|Date and time of the next scheduled retry attempt.

 Example: `2022-10-08T18:52:19+0000`

|130-75-10 130-75|
|next\_retry\_exists  
 boolean, optional

|Indicator that shows whether the next scheduled attempt is available.

 -   `true`—a retry attempt is scheduled
-   `false`— a retry attempt is not scheduled

 This parameter is required if the `recurring_retry` object is passed.

|130-75-20 130-75|
|retry\_count  
 integer, optional

|Identifier of the retry attempt for the specific debit operation \(an integer from 1 to 7\).

 Example: `3`

|130-75-30 130-75|
|trigger\_operation\_id  
 integer, optional

|Identifier of the retried debit operation in the payment platform.

 Example: `17007255`

|130-75-40 130-75|
|request\_id  
 string, required

|Identifier of the latest request within the operation in the payment platform.

|130-80 130|
|status  
 string, required

|Operation status \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `success`

|130-90 130|
|sum\_converted  
 object, optional

|Object with information about the operation amount and currency after conversion \([learn more about currency conversion](en_Gate_Conversion.md)\).|130-100 130|
|amount  
 integer, optional

|Operation amount. Specified in minor currency units \(if they are applicable\) or in major currency units.

 Example: `8726`

|130-100-10 130-100|
|currency  
 string, optional

|Operation currency code in the ISO 4217 alpha-3 format.

 Example: `EUR`

|130-100-20 130-100|
|sum\_initial  
 object, optional

|Object with information about the operation amount and currency sent in the request.|130-110 130|
|amount  
 integer, required

|Initial operation amount in minor currency units.

 Example: `9055`

|130-110-10 130-110|
|currency  
 string, required

|Code of the initial operation currency in the ISO 4217 alpha-3 format.

 Example: `USD`

|130-110-20 130-110|
|type  
 string, required

|Operation type \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `sale`

|130-120 130|
|payment   
 object, required

|Object with essential payment details.|140|
|cascading\_with\_redirect  
 boolean, optional

|Indicator of the requirement to obtain customer's confirmation of an additional purchase attempt in case of the 3‑D Secure failure \([details](en_gate_cascading.md)\):-   `true`—additional attempt is needed.
-   `false`—additional attempt is not needed.

|140-10 140|
|date   
 string, optional

|Date and time of the latest payment status update in the payment platform.

 Example: `2022-10-08T18:52:54+0000`

|140-20 140|
|description   
 string, optional

|Payment description sent in the initial request.

 Example: `Radio-controlled flying saucer nano size with delivery`

|140-30 140|
|id  
 string, required

|Payment identifier sent in the initial request.

 Example: `18641868`

|140-40 140|
|is\_new\_attempts\_available  
 boolean, optional

|Indicator of the additional purchase attempt availability \([details](en_PP_Try_Again.md)\): -   `true`—additional attempt is available.
-   `false`—additional attempt is not available.

|140-50 140|
|method   
 string, optional

|Payment method code\([details](en_pm_codes.md)\).

 Example: `card`

|140-60 140|
|merchant\_refund\_id   
 string, optional

|Refund identifier in the merchant's web service.

 Example: `refund_143`

|140-61 140|
|OperationFee  
 object, optional

|Object with information about the fee amount.|140-70 140|
|amount  
 string, optional

|Fee amount in minor currency units if this amount is included in the total operation amount.|140-70-10 140-70|
|currency  
 string, optional

|Code of the charged fee currency in the ISO 4217 alpha-3 format.|140-70-20 140-70|
|sum\_with\_surcharge  
 string, optional

|Total amount of the operation and the fee surcharge in minor currency units.|140-70-30 140-70|
|surcharge\_amount  
 string, optional

|Fee amount added to the payment amount in minor currency units \(applicable to microfinancing organisations\).|140-70-40 140-70|
|surcharge\_currency  
 string, optional

|Code of the currency in which the fee added to the payment amount was charged \(specified in the ISO 4217 alpha-3 format\).|140-70-50 140-70|
|region  
 string, optional

|Code of the region of operation processing \([details](en_region_codes.md)\).

 Example: `eea`

|140-80 140|
|status   
 string, required

|Payment status \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `partially refunded`

|140-90 140|
|sum  
 object, optional

|Object with payment amount and currency details.|140-100 140|
|amount  
 integer, required

|Payment amount with regard to all processed operations in minor currency units.

 Example: `8855`

|140-100-10 140-100|
|currency  
 string, required

|Payment code sent in the initial request in the ISO 4217 alpha-3 format.

 Example: `USD`

|140-100-20 140-100|
|timeout\_attempts  
 string, optional

|Time allocated for a purchase retry attempt \([details](en_PP_Try_Again.md)\), in seconds.

 Example: `360`

|140-110 140|
|type     
 string, required

|Payment type \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `purchase`

|140-120 140|
|scheme\_id   
 string, optional

|Identifier of the operation that initialised a COF payment. Assigned by the global card scheme \(Mastercard, Visa\). Can be passed when the COF payment is registered in the European Economic Area.

 Example: `MCS38A0790706`

|210|
|project\_id  
 integer, required

|Merchant's project identifier in the payment system.

 Example: `42`

|150|
|provider\_extra\_fields   
 object, optional

|Object with the details received from a providerora payment system.|160|
|recurring   
 object, optional

|Object with a COF purchase data \([details](en_Gate__payments_on_saved_data.md)\)|170|
|currency   
 string, optional

|Code of the COF purchase currency in the ISO 4217 alpha-3 format.

 Example: `USD`

|170-10 170|
|id   
 integer, optional

|Identifier of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\) in the payment platform.

 Example: `1001648`

|170-20 170|
|register\_payment\_id  
 string, optional

|Identifier of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\) in the merchant's web service.

 Example: `18641865`

|170-30 170|
|status  
 string, optional

|Status of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\):-   `active`—record about a series of funds debiting is active.
-   `canceled`—record about a series of funds debiting is inactive \(for example, if a COF purchase was cancelled by the merchant's request\).

|170-40 170|
|type  
 string, optional

|COF purchase type \([details](en_Gate__saved_cards_payments_type.md)\):-   `C`—OneClick purchase
-   `U`—autopurchase
-   `R`— regular purchase

|170-50 170|
|valid\_thru   
 string, optional

|Expiration date of the record about a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\).

 Example: `2023-05-20T00:00:00+0000`

|170-60 170|
|redirect\_data  
 object, optional

|Object with data for customer redirection.|180|
|body  
 object, optional

|Data for customer redirection.|180-10 180|
|method  
 string, optional

|Method required for sending the redirection request: `POST` or `GET`.|180-20 180|
|url  
 string, optional

|URL to which the customer should be redirected.|180-30 180|
|signature   
 string, required

|Callback signature \([details](en_platform_signature.md)\).|190|

### Callback parameters for tokens {#section_f4h_s5m_1vb .section}

The set of parameters sent in callbacks triggered by actions with tokens \(for example, creating or deleting a token\) can be standard or customised for separate projects. The following table contains the standard set of parameters.

|Parameter|Description| |
|---------|-----------|--|
|general  
 object, required

|Object with general identification information from the initial tokenisation request.|1|
|project\_id  
 string, required

|Merchant's project identifier in the payment platform.

 Example: `42`

|1-11|
|customer\_id  
 string, optional

|Customer identifier in the merchant's project.

 Example: `17008`

|1-21|
|signature  
 string, required

|Callback signature.|1-31|
|request  
 object, required

|Object with the initial request information.|2|
|id  
 integer, required

|Initial request identifier.

|2-12|
|action  
 string, optional

|Type of the initial request:-   `tokenize`—request for generating a token;
-   `token_revoke`—request for revoking a token.

Callbacks can be sent without this parameter if a token was revoked due to its expiration that leads to automatic sending of the callback.

|2-22|
|status  
 string, required

|Request status:-   `success`—request is completed;
-   `error`—request is not completed due to the errors specified in the `errors` array.

|2-32|
|errors  
 array, optional

|Array with information about the errors that occurred during the request execution.This array is not sent in case of a successful request processing.

|2-42|
|ErrorItem  
 object, required

|Object with information about an error that occurred during the request execution.|2-4-12-4|
|code  
 string, optional

|Code of the error that occurred during the request execution.

 Example: `3021`

|2-4-1-12-4-1|
|message  
 string, optional

|Error code description.

 Example: `Card expired`

|2-4-1-22-4-1|
|field  
 string, optional

|Name of the parameter in the initial request where an error occurred. This name is sent if the corresponding parameter is identified.|2-4-1-32-4-1|
|token  
 string, optional

|Payment card token.

|3|
|token\_created\_at  
 string, optional

|Date and time of the token generation.

 Example: `2022-07-22T03:31:24+0000`

|4|
|token\_status  
 string, optional

|Token status:-   `active`—token is active and can be used in payment processing.
-   `expiry`—token is inactive due to its expiration.
-   `revoke`—token is inactive because it was deleted upon the request from the merchant's web service.

|5|

## Related topics {#en_callbacks_links}

During the work with callbacks, the following information can come in handy:

-   [Interaction concepts](en_gate_interaction_organisation.md)—the section with general information about the interaction with the payment platform via Gate.
-   [Signature generation and verification](en_platform_signature.md)—the section with information about the work with data signing.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—the section with information about the error codes used in the payment platform.
-   [Monitoring and performing payments](en_dbl_payments.md)—the section with information about processing and monitoring payments and operations via Dashboard.
-   [Using tokens](en_Gate_Token.md)—the section with information about working with card tokens.
-   [API Reference](https://api-developers.ecommpay.com/)—the Gate API interface specification.



---

# Handling operation processing information {#en_platform_payment_info_codes}

An article about statuses and codes that are used in the platform to communicate the statuses of operations and the reasons for declines.

The current state of the operation created as part of the payment in the Ecommpay payment platform is indicated by its status. The operation status may be received from the payment platform in the intermediate and final callbacks and in responses to the request for [Checking current payment information](en_Gate_payment_status_request.md) in the operation.status parameter, as well as may be seen in Dashboard.

In addition to statuses, the payment platform uses service codes and messages, which specify information about the operation performing or the possible reasons of operation declining, including those received from external payment systems. All the response and error codes, as well as its related messages are unified in the payment platform so that it is convenient to provide the information. The unified codes and messages are sent to the merchant web service same way as the status in the operation.code and operation.message parameters. You can also view this information in Dashboard in the payment details.

```
"operation": {
            "id": 65658000001111,
            "type": "sale",
            "status": "success",  // operation status
            "date": "2024-08-30T13:58:12+0000",
            "created_date": "2024-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "0",  // code specifying the status
            "message": "Success"  // explanation to the code
        }
```

If an error occurs while operation request processing, it is indicated by the `error` request status. Since the operation is not created in this case, the payment platform sends error data in a synchronous response in the code and message parameters. For more information and examples of synchronous error responses, see [Response format](en_gate_interaction_organisation.md).

When working with errors, some actions may be required on the merchant's side. Various recommendations are provided according to the received status and error code are provided in the table below.

|Statuses|Comment|Action|
|--------|-------|------|
|`success`|Operation is performed. There are no further actions required|No action required|
|-   `awaiting 3ds result`
-   `awaiting redirect result`
-   `awaiting clarification`
-   `awaiting customer action`
-   `awaiting merchant auth`
-   `processing`

|Operation performing is in progress|It is necessary to wait|
|`decline`|Operation performing was declined: by a customer, by exceeding the requests number limit, by net connection failure or by insufficient funds on the customer account at current moment|Resend the request or Resend the request later|
|Operation performing was declined due to incorrect data in the request. Eliminate the error on your side by correcting the request or contact the technical support for help|Correct the request before resending|
|Operation processing was declined due to a technical failure, contact the technical support|Contact the technical support|
|Operation performing was declined by the risk control system \(RCS\) or due to other reasons that cannot be eliminated. Comments on the decline can be obtained from the technical support|No action required|
|`error`|Error occurred while operation request processing. Operation is not performed|Correct the request before resending|

The possible values of the codes and the messages that are displayed to customers, and suggested to the merchant further actions are given in the tables below.

## General codes {#section_ick_2ds_xzb .section}

|Code|Message|Description|Action|
|----|-------|-----------|------|
|0|Success|Operation successfully completed|No action required|
|100|General decline|Operation was declined. Payment platform general error|Contact the technical support|
|104|Declined by 3DS check|Operation was declined due to unsuccessful authentication|Resend the request|
|108|Customer has not returned from ACS|Operation was declined. Customer has not returned from ACS page of the issuing bank.|Resend the request|
|109|Declined by AVS check|Operation was declined due to the incorrect entry of billing address|Correct the request before resending|
|301|Cancelled|Operation was cancelled by the participant|Resend the request|
|303|Access denied|Request is prohibited due to lack of permits|Contact the technical support|
|309|The amount received during conversion exceeds the limit|Operation was declined as the payment amount exceeds the limit specified by the payment provider|Correct the request before resending|
|310|This operation is not allowed by project settings|Operation was declined. This type of operation is not available for the project.|Contact the technical support|
|314|Provider is not available now to perform the operation|Operation was declined as the provider is not available now|Resend the request later|
|318|Use of token\_data is disabled for the project|Operation was declined because the capability of processing payments with network tokens is not enabled for the project|Contact the technical support|
|319|There is not enough data to create an operation|Operation was declined because the request did not contain the data required for creating an operation|Correct the request before resending|
|402|RCS reject. Declined by Risk System|Operation was declined due to suspicion of a fraud. General anti-fraud decline|No action required|
|501|Internal error|An internal error has occurred|Contact the technical support|
|502|Validation error|Received data cannot be validated|Contact the technical support|
|504|Insufficient funds on the balance|Request is prohibited due to lack of funds|Contact the technical support|
|601|Try again|An error has occurred|Resend the request|
|602|Network error|A network error occurred with one of the external services|Resend the request|
|603|Auto decline|Operation was declined because of auto decline settings|Resend the request|
|604|Payout Session Terminated. UUID Expired|Operation was declined because the `uuid` is no longer valid|Resend the request with the valid `uuid`|
|702|Malformed request|Request was rejected due to malformed format|Correct the request before resending|
|903|Exceeded allowed amount for refund|Total amount of refunds by the bank card exceeds the amount of init payments|Contact the technical support|
|904|Exceeded allowed amount for payout|The bank card exceeded the limits on the amount for payouts|Contact the technical support|
|2003|Invalid JSON string|Invalid JSON string was sent in the request|Correct the request before resending|
|2004|Required field not provided|Required parameter was not sent in the request|Correct the request before resending|
|2014|Addendum data disallowed with COF purchase registration|Addendum data in request with COF purchase registration is not allowed|Correct the request before resending|
|2061|Avs Data Not Found|Operation was declined. The AVS data is needed to proceed|Try to correct the request before resending|
|2123|Account verification is not allowed|Account verification is not allowed|Correct the request before resending|
|2124|Invalid Customer ID|Invalid customer\_id was sent in the request|Correct the request before resending|
|2147|Lock Error|Operation was declined due to time-out.|Resend the request later|
|2154|Customer ID is required for project|The project settings require to pass the customer\_id parameter in the request|Correct the request before resending|
|2261|Country not found|Parameter country was not found in the request|Correct the request before resending|
|2426|Invalid Email|Invalid email parameter was sent in the request|Correct the request before resending|
|2442|Project ID not found|Parameter project\_id was not found in the request|Correct the request before resending|
|2466|Declined By Pares Settings|An incorrect 3‑D Secure authentication code was entered or an error occurred during the entering|Resend the request|
|2467|3DS SDK request is not supported|The `device_channel` parameter specified for performing 3‑D Secure contains the App-based value that is not allowed for the payment initiated by this request|Create a new request with the allowed value for the `device_channel` parameter and a new payment identifier or contact the technical support|
|2468|3DS 3RI request is not supported|The `device_channel` parameter specified for performing 3‑D Secure contains the 3DS Requestor Initiated value that is not allowed for the payment initiated by this request|Create a new request with the allowed value for the `device_channel` parameter and a new payment identifier or contact the technical support|
|2541|Unknown Payment Method|Unknown payment\_method was sent in the request|Correct the request before resending|
|2606|Withdrawal without initial payment is not allowed|Withdrawal without initial payment is not allowed|Correct the request before resending|
|2609|Invalid day of birth|Invalid day\_of\_birth was sent in the request|Correct the request before resending|
|2610|Invalid Country|Invalid country was sent in the request|Correct the request before resending|
|2611|Invalid City|Invalid city was sent in the request|Correct the request before resending|
|2641|Invalid Bank Code or Currency|Invalid bank\_id or currency was sent in the request|Correct the request before resending|
|2642|Operation amount is greater than limit|Operation amount is greater than allowed limit|Correct the request before resending|
|2701|Rules Failed Code|Operation processing failed due to business rules|Contact the technical support|
|2801|Bank ID not found|Parameter bank\_id was not found in the request|Correct the request before resending|
|2945|Invalid operation type for try again request|Invalid operation type for try again the request|Correct the request before resending|
|2949|Invalid amount for try again request|Invalid amount for try again the request|Correct the request before resending|
|3001|Invalid day of birth from UK merchant|Invalid day of birth was sent in the request from UK merchant|Correct the request before resending|
|3002|Invalid Post Code from UK merchant|Invalid post code was sent in the request from UK merchant|Correct the request before resending|
|3003|Invalid Surname from UK merchant|Invalid surname was sent in the request from UK merchant|Correct the request before resending|
|3004|Invalid Street Address from UK merchant|Invalid street address was sent in the request from UK merchant|Correct the request before resending|
|3020|Period of card validity is required for the project|Card expiry date is required but was not sent in the request|Correct the request before resending|
|3021|Card expired|Card has expired|Correct the request before resending|
|3022|Customer is not presented in saved card request|Customer was not sent in the request for payment by using a saved card|Correct the request before resending|
|3023|Provided currency disabled for Project ID|Provided currency is disabled for the project\_id|Contact the technical support|
|3024|Invalid Payment ID|Invalid payment\_id was sent in the request|Correct the request before resending|
|3026|Internal Decline|Payment performing through this payment system is not available|Contact the technical support|
|3027|Invalid token provided|Invalid token was sent in the request|Correct the request before resending|
|3028|Insufficient funds on merchant balance|Insufficient funds on the balance to perform payout|Contact the Ecommpay key account manager|
|3029|Operation with expired card is not allowed for this provider|Operation performing was declined due to the provider does not allow using an expired card|Contact the technical support|
|3041|Payment ID already exists|Payment ID already exists in the system|Correct the request before resending|
|3060|Current payment or operation status does not allow this action|Current payment or operation status does not allow the attempted action|Contact the technical support|
|3061|Transaction not found|Payment is not found in the system|Resend the request or contact the technical support|
|3062|Payment details not received|Failed to get payment details at the moment|Resend the request later|
|3081|State Machine Flow Break|Error payment processing|Contact the technical support|
|3101|Card not found|Card data from Token does not belong to the customer in the request|Correct the request before resending|
|3102|Invalid payment constraint|Operation by the card failed to validate system business rules|Contact the technical support|
|3103|Payout was declined due to constraint for card type|Payout was declined due to issuer restrictions related to card type|Contact the technical support|
|3104|Payment Constraint Invalid Payout Amount|Maximum payout limit has been exceeded|Correct the request before resending|
|3105|Card country is forbidden|Performing an operation with the card issued in the specified country is not allowed|Correct the request before resending|
|3106|Payment Constraint Invalid Monthly Payout|Monthly payout limit has been exceeded|Resend the request later|
|3107|Payout Constraint, card without successful purchase|Payout is declined because the purchase that contains the information about the payout recipient's card could not be identified|Contact the technical support|
|3108|Payment Constraint Invalid Weekly Payout|Weekly payout limit has been exceeded|Resend the request later|
|3109|Payment Constraint Invalid 24 Hour Payout|Daily payout limit has been exceeded|Resend the request later|
|3110|Payment Constraint Monthly payout operations number exceeded|Monthly limit on the number of payouts has been exceeded|Resend the request later|
|3111|Payment Constraint Weekly payout operations number exceeded|Weekly limit on the number of payouts has been exceeded|Resend the request later|
|3112|Payment Constraint 24 hour payout operations number exceeded|Daily limit on the number of payouts has been exceeded|Resend the request later|
|3117|Operation is prohibited because residual payment amount is less than one minor in USD|The operation is declined because the difference between the actual payment amount and the operation amount is less than required \(0.01 USD\)|Correct the request before resending: specify a lesser amount or a full amount of the payment|
|3118|Operation amount will be less than one minor unit after conversion by IPS|The operation is rejected because the operation amount will be less than one minor unit after the conversion performed by the global card network|Correct the request before resending|
|3119|Request currency does not match channel currency|Currency specified in the request does not match the channel currency|Correct the request before resending|
|3120|The payment amount should not exceed 25 USD for the MCC|Operation performing was declined as the payment amount for the MCC should not exceed `25 USD` or equivalent amount|Correct the request before resending|
|3121|Invalid currency|Invalid currency was sent in the request|Correct the request before resending|
|3123|Invalid API Key|Invalid API Key was sent in the request|Correct the request before resending|
|3124|Invalid certificate|Error while request processing|Contact the technical support|
|3125|Incremental authorization requests are forbidden for the MCC|Requests to increment authorization amount are forbidden for the MCC|Correct the request before resending|
|3141|CVV is required|CVV is required in the request|Correct the request before resending|
|3161|Invalid Holder|Invalid card\_holder was sent in the request|Correct the request before resending|
|3162|Cardholder is required|The card\_holder parameter was not included in the request|Correct the request before resending|
|3181|COF purchase registration ID not found|Identifier of the COF purchase registration passed in the request was not found|Correct the request before resending|
|3182|Duplicate COF purchase scheduled payment ID|Payment identifier for the COF purchase is duplicated|Correct the request before resending|
|3183|COF purchase registration ID is invalidated due to card expiry date|Card for the specified COF purchase registration ID has expired|No actions required|
|3184|COF purchase registration ID is cancelled|The COF purchase for the passed recurring\_id was canceled|Contact the technical support|
|3186|Trigger operation ID is not found|Identifier of the debit operation that requires cancelling retry attempts was not found.|Correct the request before resending|
|3190|Remittance payment method mismatched|Request payment method and the recipient account's payment method do not match|Correct the request before resending|
|3191|Need clarification|Additional payment information submission is needed|Correct the request before resending|
|3192|Remittance currency mismatched|Request currency and the recipient account's currency do not match|Correct the request before resending|
|3193|Remittance is not allowed for this project|B2B remittances are not available for this project|Contact the technical support|
|3194|Recipient ID is not found|Specified Recipient ID is not found|Correct the request before resending|
|3195|Recipient ID is forbidden|B2B payment to the account with the specified Recipient ID is forbidden|Correct the request before resending|
|3196|Remittance is not supported by payment system|The `remittance` payment type is not supported by the payment system|Contact the technical support|
|3197|Remittance is not allowed for this payment method|The `remittance` payment type is not allowed for this payment method|Contact the technical support|
|3198|Auto decline due to long verification|Operation was declined because the approval check by the AML specialists of Ecommpay timed out|Contact the technical support and try sending the request later|
|3199|Operation was declined by AML checks|Operation was declined following the approval check by the AML specialists of Ecommpay|Contact your account manager|
|3201|Expected error|Operation performing was rejected due to payment routing error|Contact the technical support|
|3221|Card token not found|Token was not found in the request|Correct the request before resending|
|3230|The operation with such merchant\_refund\_id already exists|Operation performing was rejected as the merchant refund ID passed in the request already exists in the payment platform|Correct the request before resending|
|3241|Customer not found|Customer is not match the token in the request|Correct the request before resending|
|3242|Account must be defined|Account object is required for this payment method|Correct the request before resending|
|3243|Account must not be defined|Account object is disallowed for this payment method|Correct the request before resending|
|3244|Bank id must be defined|Bank ID is required for this payment method|Correct the request before resending|
|3261|Invalid signature|Invalid signature was sent in the request|Correct the request before resending|
|3262|Empty signature|The value of the signature in the request is empty|Correct the request before resending|
|3281|Converted amount is less than one minor unit|Converted amount is less than one minor currency unit|Contact the technical support|
|3283|Refund amount more than init amount|Refund amount is more than initial amount|Correct the request before resending|
|3284|Refund currency mismatched or empty|Refund currency mismatches or is empty|Correct the request before resending|
|3285|Cannot make refund because of timeout block for repeat refund|The operation was rejected due to restrictions on the frequency of refund requests|Contact the technical support|
|3286|The property amount is required|Missing amount in request. When passing the currency parameter, you must pass the amount parameter|Correct the request before resending|
|3287|The property currency is required|The currency parameter in the request is missing. When passing the amount parameter, you must pass the currency parameter|Correct the request before resending|
|3288|Refund prohibited on disputed transaction|Refund performing is prohibitedfor payments with chargebacks|Contact the technical support|
|3289|The operation amount is less than fix fee of tariff|The operation was rejected because the amount is less than fix fee of tariff|Correct the request before resending|
|3291|Incorrect merchant account settings for operation|The operation was rejected because only one operation type is allowed for the merchant account|Correct the request before resending|
|3292|Online gambling payouts are not available for this MCC|Online gambling payouts are not available for this MCC|Contact the technical support|
|3293|Payout method not filled in merchant account|Payout method not filled in merchant account|Contact the technical support|
|3297|The provider's daily limit for the merchant account for the total amount of transactions has been exceeded|Operation was declined because the total amount of operations exceeds the daily limit imposed by the payment provider for the merchant account|Resend the request later|
|3298|The provider's daily limit on the total amount of transactions has been exceeded|Operation was declined because the total amount of operations exceeds the daily limit imposed by the payment provider|Resend the request later|
|3299|Sorry, the merchant status does not allow you to create an operation|Operation cannot be created for this merchant|Contact the technical support|
|3301|Recurring registration is expired|Operation was rejected because a registered COF purchase associated with this ID has expired|Correct the request before resending|
|3305|Payment Constraint 30-days Payout operations number exceeded for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the monthly operations limit on payouts for MCC 7995, 9406 Domestic|Resend the request later|
|3306|Payment Constraint 30-days Payout operations number exceeded for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the monthly limit operations on payouts for MCC 7995, 9406 Cross-border|Resend the request later|
|3307|Payment Constraint 30-days Payout operations number exceeded for Money transfer Domestic|Operation performing was rejected due to exceeding the monthly operations limit on payouts for domestic money transfers|Resend the request later|
|3308|Payment Constraint 30-days Payout operations number exceeded for Money transfer Cross-border|Operation performing was rejected due to exceeding the monthly operations limit on payouts for cross-border money transfers|Resend the request later|
|3309|Payment Constraint 30-days Payout operations number exceeded for Funds disbursement Domestic|Operation performing was rejected due to exceeding the monthly operations limit on payouts for domestic funds disbursements|Resend the request later|
|3310|Payment Constraint 30-days Payout operations number exceeded for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the monthly operations limit on payouts for cross-border funds disbursements|Resend the request later|
|3311|Payment Constraint Invalid Weekly Payout for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the weekly limit on payouts for MCC 7995, 9406 Domestic|Resend the request later|
|3312|Payment Constraint Invalid Weekly Payout for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the weekly limit on payouts for MCC 7995, 9406 Cross-border|Resend the request later|
|3313|Payment Constraint Invalid Weekly Payout for Money transfer Domestic|Operation performing was rejected due to exceeding the `100 000 USD` weekly limit on payouts for domestic money transfers|Resend the request later|
|3314|Payment Constraint Invalid Weekly Payout for Money transfer Cross-border|Operation performing was rejected due to exceeding the `100 000 USD` weekly limit on payouts for cross-border money transfers|Resend the request later|
|3315|Payment Constraint Invalid Weekly Payout for Funds disbursement Domestic|Operation performing was rejected due to exceeding the `600 000 USD` weekly limit on payouts for domestic funds disbursements|Resend the request later|
|3316|Payment Constraint Invalid Weekly Payout for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the `250 000 USD` weekly limit on payouts for cross-border funds disbursements|Resend the request later|
|3317|Payment Constraint Invalid 24 Hour Payout for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the daily limit on payouts for MCC 7995, 9406 Domestic|Resend the request later|
|3318|Payment Constraint Invalid 24 Hour Payout for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the daily limit on payouts for MCC 7995, 9406 Cross-border|Resend the request later|
|3319|Payment Constraint Invalid 24 Hour Payout for Money transfer Domestic|Operation performing was rejected due to exceeding the `50 000 USD` daily limit on payouts for domestic money transfers|Resend the request later|
|3320|Payment Constraint Invalid 24 Hour Payout for Money transfer Cross-border|Operation performing was rejected due to exceeding the `50 000 USD` daily limit on payouts for cross-border money transfers|Resend the request later|
|3321|Payment Constraint Invalid 24 Hour Payout for Funds disbursement Domestic|Operation performing was rejected due to exceeding the `250 000 USD` daily limit on payouts for domestic funds disbursements|Resend the request later|
|3322|Payment Constraint Invalid 24 Hour Payout for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the `100 000 USD` daily limit on payouts for cross-border funds disbursements|Resend the request later|
|3323|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the monthly limit on payouts amount for MCC 7995, 9406 Domestic|Resend the request later|
|3324|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the monthly limit on payouts amount for MCC 7995, 9406 Cross-border|Resend the request later|
|3325|Payment Constraint Invalid 30-days Payout for Money transfer Domestic|Operation performing was rejected due to exceeding the `200 000 USD` monthly limit on payouts amount for domestic money transfers|Resend the request later|
|3326|Payment Constraint Invalid 30-days Payout for Money transfer Cross-border|Operation performing was rejected due to exceeding the `200 000 USD` monthly limit on payouts amount for cross-border money transfers|Resend the request later|
|3327|Payment Constraint Invalid 30-days Payout for Funds disbursement Domestic|Operation performing was rejected due to exceeding the `1 250 000 USD` monthly limit on payouts amount for domestic funds disbursements|Resend the request later|
|3328|Payment Constraint Invalid 30-days Payout for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the `500 000 USD` monthly limit on payouts amount for cross-border funds disbursements|Resend the request later|
|3329|Payment Constraint Weekly payout operations number exceeded for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the weekly limit on payouts number for MCC 7995, 9406 Domestic|Resend the request later|
|3330|Payment Constraint Weekly payout operations number exceeded for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the weekly limit on payouts number for MCC 7995, 9406 Cross-border|Resend the request later|
|3331|Payment Constraint Weekly payout operations number exceeded for Money transfer Domestic|Operation performing was rejected due to exceeding the weekly limit on payouts number for domestic money transfers|Resend the request later|
|3332|Payment Constraint Weekly payout operations number exceeded for Money transfer Cross-border|Operation performing was rejected due to exceeding the weekly limit on payouts number for cross-border money transfers|Resend the request later|
|3333|Payment Constraint Weekly payout operations number exceeded for Funds disbursement Domestic|Operation performing was rejected due to exceeding the weekly limit on payouts number for domestic funds disbursements|Resend the request later|
|3334|Payment Constraint Weekly payout operations number exceeded for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the weekly limit on payouts number for cross-border funds disbursements|Resend the request later|
|3335|Payment Constraint 24 hour payout operations number exceeded for MCC 7995, 9406 Domestic|Operation performing was rejected due to exceeding the daily limit on payouts number for MCC 7995, 9406 Domestic|Resend the request later|
|3336|Payment Constraint 24 hour payout operations number exceeded for MCC 7995, 9406 Cross-border|Operation performing was rejected due to exceeding the daily limit on payouts number for MCC 7995, 9406 Cross-border|Resend the request later|
|3337|Payment Constraint 24 hour payout operations number exceeded for Money transfer Domestic|Operation performing was rejected due to exceeding the daily limit on payouts number for domestic money transfers|Resend the request later|
|3338|Payment Constraint 24 hour payout operations number exceeded for Money transfer Cross-border|Operation performing was rejected due to exceeding the daily limit on payouts number for cross-border money transfers|Resend the request later|
|3339|Payment Constraint 24 hour payout operations number exceeded for Funds disbursement Domestic|Operation performing was rejected due to exceeding the daily limit on payouts number for domestic funds disbursements|Resend the request later|
|3340|Payment Constraint 24 hour payout operations number exceeded for Funds disbursement Cross-border|Operation performing was rejected due to exceeding the daily limit on payouts number for cross-border funds disbursements|Resend the request later|
|3341|Payout was declined due to card constraints|Operation was declined due to issuer restrictions|Contact the technical support|
|3355|Payment Constraint 24 hour operations number exceeded for same card|Operation performing was rejected due to exceeding the daily limit on operations number for the same card|Resend the request later|
|3356|The operation is not allowed for this card|The payment is declined because payment operations are prohibited for this card|No action required|
|3357|Payment Constraint 30-days operations number exceed for same card|Operation performing was rejected due to exceeding the monthly limit on operations number for the same card|Resend the request later|
|3358|Operation amount is less than limit|Operation amount is less than allowed limit|Correct the request before resending|
|3360|Payment amount cannot exceed 50 EUR for prepaid non-reloadable card|If the sender uses a prepaid non-reloadable card, the amount to be debited cannot exceed `50 EUR`|Correct the request before resending|
|3362|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406|Operation performing was rejected due to exceeding the `50 000 USD` monthly limit on payouts amount for MCC 7995, 9406|Resend the request later|
|3363|Trace ID must be present in recurring payment and MIT|There was an error while processing the request|Contact the technical support|
|3400|AFT Payment Constraint for Commercial cards|Operation was declined due to restrictions on using commercial cards by sender|Correct the request before resending|
|3402|Payment Constraint 25000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Operation performing was rejected due to exceeding the `25 000 USD` limit on one MoneySend Funding Transaction for consumer cards|Correct the request before resending|
|3403|Payment Constraint 50000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `50 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resending|
|3404|Payment Constraint 25000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Operation performing was rejected due to exceeding the `25 000 USD` limit on one MoneySend payout for consumer cards|Correct the request before resending|
|3406|Payment Constraint 50000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `50 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resending|
|3407|Payment Constraint Invalid 30-days MoneySend payout for Consumer cards|Operation performing was rejected due to exceeding the monthly `25 000 USD` limit on MoneySend payouts for consumer cards|Resend the request later|
|3408|Payment Constraint Invalid 30-days MoneySend payout for Small business cards|Operation performing was rejected due to exceeding the monthly `50 000 USD` limit on MoneySend payouts for small business cards|Resend the request later|
|3409|Payment Constraint 2500 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Operation performing was rejected due to exceeding the `2 500 USD` limit on one MoneySend Funding Transaction for consumer cards|Correct the request before resending|
|3410|Payment Constraint 2500 USD Amount limit exceeded for MoneySend payout by Consumer cards|Operation performing was rejected due to exceeding the `2 500 USD` limit on one MoneySend payout for consumer cards|Correct the request before resending|
|3411|Payment cannot be made due to location of the sender's card issuer outside the Europe Region|The sender's card issuer must be located in the European region|Correct the request before resending|
|3412|Payment Constraint 25000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `25 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resending|
|3413|Payment Constraint 25000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `25 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resending|
|3414|Payment Constraint 50000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Operation performing was rejected due to exceeding the `50 000 USD` limit on one MoneySend payout for consumer cards|Correct the request before resending|
|3415|Payment Constraint 100000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `100 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resending|
|3416|Payment Constraint 50000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Operation performing was rejected due to exceeding the `50 000 USD` limit on one MoneySend Funding Transaction for consumer cards|Correct the request before resending|
|3417|Payment Constraint 100000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `100 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resending|
|3418|Payment Constraint 75000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `75 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resending|
|3419|Payment Constraint 75000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `75 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resending|
|3431|Money transfer is not possible for two identical cards|The sender's PAN matches the recipient's PAN|Correct the request before resending|
|3432|The request must contain either the identifier of the saved card or complete card details|Both the saved card ID and complete card details have been passed in objects `sender` and/or `recipient`|Correct the request before resending|
|3433|The request contains complete card details for both cards. This endpoint is for making a payment using saved card data only|Complete card details of both the sender and the recipient have been specified in the request. Note that this endpoint is intended only for sending requests to make payments using saved card data|Correct the request before resending|
|3434|The sender's card expired|The card of the sender has expired|Correct the request before resending|
|3435|The recipient's card expired|The card of the recipient has expired|Correct the request before resending|
|3436|The sender's card is invalid|The sender's card specified in the request is invalid|Correct the request before resending|
|3437|The recipient's card is invalid|The recipient's card specified in the request is invalid|Correct the request before resending|
|3438|Saved sender card has no expiration date|The sender's card expiry date is needed to proceed|Correct the request before resending|
|3439|The saved card has no expiration date|The card expiry date is needed to proceed|Correct the request before resending|
|3450|Payment Constraint Invalid 24 Hour AFT for Money transfer Domestic|Operation performing was rejected due to exceeding the `100 000 USD` daily limit on AFT amount for domestic money transfers|Resend the request later|
|3451|Payment Constraint Invalid Weekly AFT for Money transfer Domestic|Operation performing was rejected due to exceeding the `250 000 USD` weekly limit on AFT amount for domestic money transfers|Resend the request later|
|3452|Payment Constraint Invalid 30-days AFT for Money transfer Domestic|Operation performing was rejected due to exceeding the `500 000 USD` monthly limit on AFT amount for domestic money transfers|Resend the request later|
|3470|Payment was declined due to sender's card constraints|Operation performing was rejected due to the type of the sender's card|Contact the technical support|
|3471|Payment was declined due to recipient's card constraints|Operation performing was rejected due to the type of the recipient's card|Contact the technical support|
|3472|Payment was declined due to constraints in the region of the recipient card|Operation performing was rejected due to the region of the recipient's card issuer|Contact your key account manager|
|3480|Payment cannot be made due to location of the sender's card issuer outside the EEA|The sender's card issuer cannot be located outside the EEA|Correct the request before resending|
|3490|Required fields for Debt Repayment are missing|The required parameters for performing a debt repayment operation are not specified in the request|Correct the request before resending|
|3491|Invalid card type for Debt Repayment|Invalid card type for performing a debt repayment operation|Correct the request before resending|
|3606|Payment Constraint Invalid 30-days MoneySend Funding Transaction for Consumer cards|Operation performing was rejected due to exceeding the monthly amount limit on Moneysend Funding Transaction for consumer cards|Resend the request later, upon the expiration of the current 30-day period|
|3607|Payment Constraint Invalid 30-days MoneySend Funding Transaction for Small business cards|Operation performing was rejected due to exceeding the monthly amount limit on Moneysend Funding Transaction for small business cards|Resend the request later, upon the expiration of the current 30-day period|
|3609|Operation amount must be equal to the initial amount|Operation amount must be the same as the amount of the initial operation|Correct the request before resending|
|3610|Refund unavailable for the current operation|Refund is prohibited for this operation|Contact the technical support|
|3611|AFT reversal must be used to refund within the first 24 hours of the original AFT|This operation can be cancelled only within the first 24 hours after it was initially executed|Contact the technical support|
|3612|One or more required money transfer fields are empty|Additional information about the sender and/or the recipient is required|Correct the request before resending|
|3613|Duplicate operation|Operation rejected because an operation with the same customer ID and payment amount already exists|Resend the request later|
|3617|Not allowed mcc for pan with product code = F2|Merchants using this MCC are not eligible for performing operations with this type of card \(product code F2\)|Contact the technical support|
|3618|Payment Constraint 10000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Operation performing was rejected due to exceeding the `10 000 USD` limit on one MoneySend payout for consumer cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3619|Payment Constraint 10000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `10 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3620|Payment Constraint 125000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Operation performing was rejected due to exceeding the `125 000 USD` limit on one MoneySend payout for consumer cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3621|Payment Constraint 125000 USD Amount limit exceeded for MoneySend payout by Small business cards|Operation performing was rejected due to exceeding the `125 000 USD` limit on one MoneySend payout for small business cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3622|Payment Constraint 125000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Operation performing was rejected due to exceeding the `125 000 USD` limit on one MoneySend Funding Transaction for consumer cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3623|Payment Constraint 125000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `125 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3624|Payment Constraint 10000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Operation performing was rejected due to exceeding the `10 000 USD` limit on one MoneySend Funding Transaction for consumer cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3625|Payment Constraint 10000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Operation performing was rejected due to exceeding the `10 000 USD` limit on one MoneySend Funding Transaction for small business cards|Correct the request before resendingYou can split the operation amount into several and send several requests with each amount not exceeding the limit

|
|3626|Payment Constraint Invalid 24 Hour payout for MoneySend by Consumer cards|Operation performing was rejected due to exceeding the daily limit on the number of payouts for consumer cards|Resend the request later, upon the expiration of the 24-hour period|
|3627|Payment Constraint Invalid 24 Hour payout for MoneySend by Small business cards|Operation performing was rejected due to exceeding the daily limit on the number of payouts for small business cards|Resend the request later, upon the expiration of the 24-hour period|
|3628|Payment Constraint Invalid 24 Hour funding for MoneySend by Consumer cards|Operation performing was rejected due to exceeding the daily limit on the number of funding operations for consumer cards|Resend the request later, upon the expiration of the 24-hour period|
|3629|Payment Constraint Invalid 24 Hour funding for MoneySend by Small business cards|Operation performing was rejected due to exceeding the daily limit on the number of funding operations for small business cards|Resend the request later, upon the expiration of the 24-hour period|
|3630|Payment Constraint Invalid Weekly payout for MoneySend by Consumer cards|Operation performing was rejected due to exceeding the weekly limit on the number of payouts for consumer cards|Resend the request later, upon the expiration of the current 7-day period|
|3631|Payment Constraint Invalid Weekly payout for MoneySend by Small business cards|Operation performing was rejected due to exceeding the weekly limit on the number of payouts for small business cards|Resend the request later, upon the expiration of the current 7-day period|
|3632|Payment Constraint Invalid Weekly funding for MoneySend by Consumer cards|Operation performing was rejected due to exceeding the weekly limit on the number of funding operations for consumer cards|Resend the request later, upon the expiration of the current 7-day period|
|3633|Payment Constraint Invalid Weekly funding for MoneySend by Small business cards|Operation performing was rejected due to exceeding the weekly limit on the number of funding operations for small business cards|Resend the request later, upon the expiration of the current 7-day period|
|3634|Payment Constraint Invalid 24 Hour for Payout mcc 7995, 9406 by Consumer cards|Operation performing was rejected due to exceeding the daily limit on the number of payouts for consumer cards applicable if the MCC is 7995 or 9406|Resend the request later, upon the expiration of the 24-hour period|
|3635|Payment Constraint Invalid Weekly for Payout mcc 7995, 9406 by Consumer cards|Operation performing was rejected due to exceeding the weekly limit on the number of payouts for consumer cards applicable if the MCC is 7995 or 9406|Resend the request later, upon the expiration of the current 7-day period|
|3900|Payment Constraint 50000 USD Amount limit exceeded for Money transfer|Operation performing was rejected due to exceeding the `50 000 USD` amount limit for money transfers|Correct the request before resending|
|3901|Payment Constraint 25000 USD Amount limit exceeded for Money transfer|Operation performing was rejected due to exceeding the `25 000 USD` amount limit for money transfers|Correct the request before resending|
|9999|Awaiting processing|Awaiting internal processing. Please wait|It is necessary to wait|

## Codes from Risk Control System \(RCS\) {#section_yrx_2ds_xzb .section}

|Code|Message|Description|Action|
|----|-------|-----------|------|
|1401|RCS reject. PAN is Blacklisted in RCS|Card PAN is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1402|RCS reject. Customer is Blacklisted in RCS|Customer is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1403|RCS reject. Cardholder is Blacklisted in RCS|Cardholder is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1404|RCS reject. IIN is Blacklisted in RCS|Card IIN is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1405|RCS reject. IP is Blacklisted in RCS|Customer IP address is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1406|RCS reject. Email is Blacklisted in RCS|Customer email address is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1407|RCS reject. Phone is Blacklisted in RCS|Customer phone number is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1408|RCS reject. Card is compromised|Customer card is lost or stolen|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1409|RCS Reject. Interval too short|Operation frequency limit has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1410|RCS reject. Domain is forbidden|The customer's email domain is blacklisted in RCS|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1411|RCS reject. Country is forbidden|Operation processing is prohibited for this country|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1412|RCS reject. Country mismatch|Country mismatch for a customer|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1413|RCS reject. Country limit exceeded|The limit of countries from which operations were carried out has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1414|RCS Reject. Country is forbidden for cross-border transaction|AFT operation processing is prohibited for this country|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1415|RCS reject. Rejected by Scoring system|Operation is rejected because it was deemed suspicious by the scoring system|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1421|RCS reject. Invalid amount|The specified payment amount is out of range|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1422|RCS reject. Amount limit exceeded|Payment amount limit has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1431|RCS reject. Allowed number of cards exceeded|Allowed number of cards used for payment processing has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1432|RCS reject. Allowed number of emails exceeded|Allowed number of emails used for payment processing has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1433|RCS reject. Count limit exceeded|Operation count limit has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1434|RCS reject. Duplicate operation|High risk of duplicated operation|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1435|RCS reject. Allowed number of users exceeded|Allowed number of different identifiers for the customer has been exceeded|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1437|RCS reject. Allowed number of names exceeded|Exceeded the allowed number of different spellings of the customer name which are treated by the RCS as different cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1441|RCS reject. Rejected by compliance restriction|Rejected due to compliance restrictions|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1450|RCS reject. Rejected by sanctions lists|Rejected due to a match with one or several sanctions lists of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1451|RCS reject. Rejected by AML restriction|Rejected as a result of an AML check|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1452|RCS reject. Rejected by AML UK sanction list|Rejected due to a match with the AML UK sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1453|RCS reject. Rejected by AML US sanction list|Rejected due to a match with the AML US sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1455|RCS reject. Rejected by AML phrase list|Rejected due to a match with the AML phrase list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1456|RCS reject. Rejected by holdername format validation|Rejected due to failing a cardholder name validation check|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1457|RCS reject. Rejected by AML EU sanction list|Rejected due to a match with the AML EU sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1458|RCS reject. Rejected by AML UN sanction list|Rejected due to a match with the AML UN sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1459|RCS reject. Rejected by AML NL sanction list|Rejected due to a match with the AML NL sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1460|RCS reject. Rejected by AML UAE sanction list|Rejected due to a match with the AML UAE sanctions list of cardholder names|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1461|RCS reject. Restricted card product code|Restricted card product code|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1462|RCS reject. Restricted card type|Restricted card type|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1463|RCS reject. Cardholder name mismatch|Cardholder name mismatch|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|1499|RCS reject. Machine Learning recommendation|Operation is rejected as suspicious following the assessment with the use of the artificial intelligence|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|

## Codes from external card payment systems {#section_h2j_fds_xzb .section}

|Code|Message|Description|Action|
|----|-------|-----------|------|
|10000|General decline|Operation was declined by PSP for an unknown reason|Resend the request|
|10100|Declined by external provider|Operation was declined by PSP without explanation|Resend the request|
|10101|Decline due to amount or frequency limit|Operation was declined due to amount or frequency limitation|Correct the request before resending or resend the request later|
|101011|Decline due to amount limit|Operation was declined due to limitation of amount|Correct the request before resending|
|101012|Decline due to amount limit per period for the customer|Operation was declined due to limitation of payment amount per period for a customer|Resend the request later|
|101013|Decline due to frequency limit|Operation was declined due to limitation of payment attempts frequency|Resend the request later|
|101014|Too much declined operations per period for the customer|Operation was declined due to limitation of payment attempts frequency per period for a customer|Resend the request later|
|10102|Incorrect data entered|Operation was declined due to incorrect card data entry|Correct the request before resending|
|101021|Incorrect PAN|Operation was declined due to incorrect card PAN entry|Correct the request before resending|
|10103|Incorrect PIN or CVV|Operation was declined due to incorrect PIN or CVV entry|Correct the request before resending|
|10104|Incorrect 3DS password|Operation was declined due to incorrect 3DS password entry|Resend the request|
|10105|Insufficient funds on card|Operation was declined due to insufficient funds on the card|Resend the request|
|10106|Card expired|Operation was declined due to incorrect card expiry date entry|Correct the request before resending|
|10107|Allowable PIN tries exceeded|Operation was declined due to multiple entry of incorrect PIN|Resend the request|
|10108|Maestro MO/TO operation is prohibited for this country|Operation was declined due to a MO/TO payment is not allowed for the country in the request|Correct the request before resending|
|10109|COF payment registration or customer payment data saving is not approved by external provider|COF payment registration or customer payment data saving is not approved by external provider|Resend the request later|
|10110|Subscription is canceled by customer on the issuer side|Operation was declined because the customer cancelled the COF purchase|No required action necessary.

 You can also register a new COF purchase

|
|10112|Insufficient Funds. Retry later|Operation was declined due to insufficient funds on the card|Resend the request later|
|10113|Insufficient Funds. Do not retry|Operation was declined due to insufficient funds on the card|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10114|Declined by 3DS Check|Operation was declined following the 3‑D Secure authentication attempt|Resend the request later|
|10201|Refer to card issuer|Operation was declined by the issuer|You can recommend your customer the following actions:

 -   Refer to the issuer in order to determine the cause of the problem with the card and what can be done to solve it.
-   Use a different payment instrument to make a payment.

|
|10202|Issuer inoperative|Operation was declined due to the unavailability of the card issuer|Resend the request|
|10203|Pick-up card|Operation was declined due to a special response from the bank that the card was compromised|No action required|
|10204|Restrictions for the customer card|Operation was declined due to restrictions on the customer card. Contact the card issuer|Correct the request before resending|
|10205|Not enrolled for 3DS|Operation was declined because the customer card does not support 3‑D Secure authentication|Correct the request before resending|
|10206|Restrictions for the customer data|Operation performing for this customer was rejected by the external provider|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10301|Operation was cancelled|Operation was cancelled by the participant|Resend the request|
|10401|Declined by PSP risk system|Operation was declined by PSP risk department. Do not show this message to a customer|Correct the request before resending|
|10402|Suspicious operation|Operation was declined by PSP anti-fraud system|No action required|
|10403|Fraud/Security. Try again using 3DS authentication|Operation was declined by PSP anti-fraud system because the 3‑D Secure authentication is necessary|Complete the procedure of the 3‑D Secure authentication|
|10404|Suspected fraud. Do not try again|Operation was declined by PSP anti-fraud system|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10405|Fraud or closed account. Do not try again|Operation was declined by PSP anti-fraud system|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10501|Refer to acquirer|Operation was declined due to incorrect interaction with PSP|Contact the technical support|
|10502|Error during operation validation|Operation was declined during the operation data validation process|Correct the request before resending|
|10503|Incorrect acquirer settings|Operation was declined due to incorrect settings. Contact the acquirer|Contact the technical support|
|10504|Insufficient funds on acquirer balance|Operation was declined due to insufficient funds on the acquirer balance|Contact the technical support|
|10505|PSP system is inoperative|Operation was declined due to the unavailability of PSP. Please try again later|Resend the request|
|10601|Try again|Operation was declined. Please try again|Resend the request|
|10602|Time-out|Operation was declined due to time-out. Please try again|Resend the request|
|10603|Operation could not be authorized. Try again later|Operation could not be authorized now. Please try again later|Resend the request|
|10701|Wrong requests sequence|Operation was declined due to incorrect sequence of requests|Correct the request before resending|
|10702|Invalid request|Operation was declined due to malformed format of the request|Contact the technical support|
|10703|Incorrect eci|Operation was declined due to incorrect ECI code received by the acquirer|Contact the technical support|
|10704|Card holder not found|Operation was declined because the acquirer requires a cardholder parameter|Contact the technical support|
|10705|The request contains no fields of the customer object|Operation was declined due to insufficient customer data requested by the acquirer|Contact the technical support|
|10706|Refund unavailable for current operation|Refund operation was declined by acquirer as it is unavailable|Contact the technical support|
|10707|Required rental information is not present|Operation was declined due to insufficient rental information|Contact the technical support|
|10708|Required flight details is not present|Operation was declined due to insufficient flight details|Contact the technical support|
|10709|Additional customer 3‑D Secureauthentication required|Operation was declined by issuer as the customer did not passed the 3‑D Secure authentication. Please contact the card issuer|Contact the technical support|
|10722|Strong Customer Authentication mandated according to PSD2|Operation was declined since it was not authenticated in accordance with the SCA \(Strong Customer Authentication\) requirements|Contact the technical support|
|10801|External provider approved but did not process the operation|External provider approved but did not process the operation|Contact the technical support|
|10805|Life cycle \(Mastercard use only\)|Operation was declined by issuer due to incorrect entry of card expiry date or card number|Try to correct the request before resending|
|10806|Policy \(Mastercard use only\)|Operation was declined by issuer|Please contact the technical support|
|10807|Fraud/Security|Operation was declined by issuer due to suspicion of fraud|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10810|Life cycle. Do not try again|Operation was declined by the issuer due to incorrect entry of card expiry date or card number|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10811|Policy. Do not try again|Operation was declined by the issuer|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|10812|Invalid card. Do not try again|Operation was declined by the issuer|No required action necessary.

 You can also contact the technical support to find out what else can be done in this situation

|
|19999|Awaiting processing|Awaiting external processing of the request. Please wait|It is necessary to wait|

## Codes from external alternative payment systems {#section_uxt_fds_xzb .section}

|Code|Message|Description|Action|
|----|-------|-----------|------|
|20000|General decline|Operation was declined for an unknown reason|Resend the request|
|20100|Declined by external provider|Operation was declined by PSP without explanation|Resend the request|
|20101|Decline due to amount or frequency limit|Operation was declined due to limitation of amount or frequency|Correct the request before resending or resend the request later|
|201011|Decline due to amount limit|Operation was declined due to limitation of amount|Correct the request before resending|
|201012|Decline due to amount limit per period for the customer|Operation was declined due to limitation of payment amount per period for a customer|Resend the request later|
|201013|Decline due to frequency limit|Operation was declined due to limitation of payment attempts frequency|Resend the request later|
|201014|Too much declined operations per period for the customer|Operation was declined due to limitation of payment attempts frequency per period for a customer|Resend the request later|
|20102|Incorrect account data entered|Operation was declined due to incorrect account data entry|Correct the request before resending|
|20103|Incorrect login or password|Operation was declined due to incorrect customer login or password entry|Correct the request before resending|
|20104|Password attempts entry exceeded|Operation was declined due to multiple entry of incorrect password|Resend the request|
|20105|Insufficient funds on customer account|Operation was declined due to insufficient funds on the customer account|Resend the request|
|20106|Customer account is no longer available|Operation was declined due to the customer account is expired or unavailable|Correct the request before resending|
|20107|Customer account does not support requested currency|Operation was declined due to the customer account does not support requested currency|Correct the request before resending|
|20109|COF payment registration or customer payment data saving is not approved by external provider|COF payment registration or customer payment data saving is not approved by external provider|Resend the request later|
|20110|Subscription is canceled by customer on the issuer side|Subscription is canceled by customer on the issuer side|No action required|
|20111|Operation declined by PSP because the Direct Debit mandate is inactive, cancelled, or expired|Operation declined by PSP because the Direct Debit mandate is inactive, cancelled, or expired|No action required|
|20201|Restrictions for the customer account|Operation was declined due to restrictions on customer account. Contact the PSP|Correct the request before resending|
|20202|PSP system is unavailable|Operation was declined due to the unavailability of PSP. Please try again later|Resend the request|
|20203|Compromised customer account|Operation was declined due to a special response from the bank: customer account was compromised|No action required|
|20204|Crediting this customer account is blocked|Operation was declined. The customer account is not allowed to perform crediting. Contact the PSP|Correct the request before resending|
|20205|Payment method is not available for customer country|Payment method is not available for customer country|No action required|
|20206|Difficulties on the mobile operator side|Operation was declined due to the technical problems on the mobile operator side|Resend the request later|
|20301|Account owner cancelled operation|Operation was declined by the account owner|Resend the request|
|20302|Unacceptable password|Password does not meet the requirements. Please try another|Correct the request before resending|
|20303|Customer is not permitted to perform the action|Request is prohibited due to lack of permits|Correct the request before resending|
|20304|Incorrect amount paid|Operation was declined due to incorrect amount paid by a customer|Resend the request|
|20401|Declined by PSP risk system|Operation was declined by PSP risk department. Do not show this message to a customer|Correct the request before resending|
|20402|Suspicious operation|Operation was declined by PSP anti-fraud system|No action required|
|20450|The Verification of Payee cannot be performed due to technical reasons.|The initiated Verification of Payee cannot be carried out due to errors in the interaction between the platform and the provider service|Resend the request in several minutes.If the error persists, contact the technical support

|
|20451|Payout or refund cannot be processed based on the Verification of Payee result.|The initiated operation cannot be processed due to the discrepancy between the final Verification of Payee status and one of the approved algorithms \([details](en_verification_of_payee.md)\)|You can notify the customer about the spelling discrepancy between the specified name and the account holder's name and offer to try again, clarifying the name.If the error persists, contact the technical support

|
|20501|Refer to acquirer|Operation was declined due to incorrect interaction with PSP|Contact the technical support|
|20502|Error during operation validation|Operation was declined during the operation validation process|Correct the request before resending|
|20503|Incorrect acquirer settings|Operation was declined due to incorrect settings. Contact the acquirer|Contact the technical support|
|20504|Insufficient funds on acquirer balance|Operation was declined due to insufficient funds on the acquirer balance|Contact the technical support|
|20601|Try again|Operation was declined. Please try again|Resend the request|
|20602|Time-out|Operation was declined due to time-out. Please try again|Resend the request|
|20603|Operation could not be authorized. Try again later|Operation cannot be authorized now. Please try again later|Resend the request|
|20604|Notification is not delivered|Operation was declined. Notification cannot be delivered|Contact the technical support|
|20701|Wrong requests sequence|Operation was declined due to incorrect sequence of requests|Correct the request before resending|
|20702|Invalid request. Try again|Operation was declined due to malformed format of the request|Contact the technical support|
|20703|Invoice not found|Operation was declined. Invoice was not found in the system|Contact the technical support|
|20705|Merchant account is blocked|Operation was declined due to the merchant’s account being blocked|Contact the technical support|
|20706|Operation not supported by provider|Operation was declined because the provider does not support this type of operation|Contact the technical support|
|20801|Payment provider approved but did not process the operation|Payment provider approved but did not process the operation|Contact the technical support|
|20802|The payment provider did not confirm neither successful nor negative status of the payment transaction|The payment provider cannot confirm status of the payment|It is necessary to wait|
|20812|The service provider did not confirm the account crediting|The operation was declined because the payment service provider did not confirm that the funds were deposited to the bank account of the customer|Resend the request|
|20899|The payment is processed on the provider side. It can take up to several days. Inform customer if needed|The payment is processed on the provider or payment system side. It can take up to several days. Inform the customer if needed|No additional interactions with the platform are required|
|29999|Awaiting processing|Awaiting external processing. Please wait|It is necessary to wait|

## Codes from merchants {#section_im2_gds_xzb .section}

|Code|Message|Description|Action|
|----|-------|-----------|------|
|30000|Operation was declined by merchant|Operation processing was declined by merchant|No action required|
|30100|Operation was declined by merchant for an unknown reason|Operation processing was declined by merchant for an unknown reason|No action required|
|30301|Merchant did not confirm operation processing|Operation processing was not confirmed by merchant|No action required|
|30302|Merchant did not respond during the operation confirmation process|Merchant did not respond during the operation confirmation process|No action required|
|30303|The amount or currency confirmed by the merchant is different from the requested one|The amount or currency confirmed by the merchant is different from one in the request|No action required|
|30401|Empty draws list|The list of amounts available for payment is empty|No action required|

**Parent topic:**[Handling payment processing information](en_platform_payment_information.md)



---

# Payment Page {#en_PP_about .concept}

A section with the information about working with the payment form.

This section provides the information about working with the Payment Page payment form.

## Overview {#section_tjy_s2b_dbb .section}

This article introduces the information about the payment form, the general workflow of using the form, and the capabilities overview—[Overview](en_PP_general.md).

## Integration {#section_xqb_k5g_btb .section}

The information about setting up Payment Pagein different cases:

-   [Quickstart](en_pp_quickstart.md)—about quick and easy ways to organise payment processing with the application of ready-to-use solutions, such as SDKs and source code examples, to their fullest extent.
-   [Interaction concepts](en_pp_interaction_organisation.md)—about organising the work with Payment Page on the web service side in various cases based on the principles of the payment platform operation.
-   [Integration using SDK](en_sdk_overview.md)—about using SDKs for mobile applications anddata signing.
-   [Integration using plug-ins](en_CMS.md)—about embedding the payment form into the websites on the basis of various CMSs and specialised platforms with the help of plug-ins.
-   [Using Payment Page in embedded mode for card payments](en_pp_microframe_solution.md)—about using Payment Page embedded mode edition to accept standard card payments.
-   [Using embedded buttons for Apple Pay and Google Pay payments](en_pp_embedded_payment_buttons.md)—about embedding branded payment buttons into the web service to process express checkout payments, with the support for collecting customer information and providing shipping details in the services of Apple Pay and Google Pay.

## UX configuration {#section_m4b_k5g_btb .section}

The information about various options of the payment form UX configuration:

-   [Options for opening Payment Page](en_PP_Integration.md)—about the ways of opening the form, including its opening in a separate tab, modal window, and an iframe object.
-   [Options for redirecting customers to third-party services](en_PP_pm_redirect_mode.md)—about the ways of opening auxiliary pageswhen working with different payment methods.
-   [Options for redirecting customers to the web service](en_PP_redirect_modes.md)—about the ways of redirecting customers from the payment form to the web service via the specified URLs.

## Basic actions {#section_ywk_z5g_btb .section}

The information about the basic actions that can be performed via the payment form:

-   [Purchase processing](en_pp_purchase.md)—about processing purchases that result in immediate debiting of funds.
-   [Authorisation hold](en_pp_purchase_auth.md)—about placing a hold on funds within a two-step purchase.
-   [COF purchase registration](en_pp_recurring.md)—about registering purchases followed by a series of recurring debits.
-   [Performing payouts](en_pp_payout.md)—about issuing payouts.
-   [Payment instrument verification](en_pp_account_verification.md)—about debiting of a zero amount or placing a hold on funds for validating the payment instrument.
-   [Tokenization](en_pp_token.md)—about opening the payment form for registering payment data and forming a token for this data.

## Additional capabilities {#section_ejc_nvg_btb .section}

The information about various capabilities for boosting payment acceptance rates, customer convenience, and the quality of the provided services—[Auxiliary procedures and additional capabilities](en_PP_Additional.md)and [Customisation](en_PP__design_customisation.md).

## Technical aspects {#section_jkz_2ml_pjc .section}

The information about various technical aspects of working with program requests—[Payment Page API specification](en_PP_Parameters.md).

-   **[Overview](en_PP_general.md)**  
An article with the introductory information about Payment Page, the general workflow of using the form, and the overview of its capabilities.
-   **[Quickstart](en_pp_quickstart.md)**  
A quickstart guide on how to implement payment processing via Payment Page with the use of SDKs and source code examples.
-   **[Interaction concepts](en_pp_interaction_organisation.md)**  
An article about organising the work with Payment Page on the web service side based on the principles of the payment platform operation.
-   **[Integration using SDK](en_sdk_overview.md)**  
Articles about using SDKs for integrating Payment Page in mobile applications and for data signing.
-   **[Integration using plug-ins](en_CMS.md)**  
Articles about using plug-ins for embedding Payment Page into websites powered by various CMS and specialised platforms.
-   **[Using Payment Page in embedded mode for card payments](en_pp_microframe_solution.md)**  
An article about using Payment Page embedded mode edition to accept standard card payments.
-   **[Using embedded buttons for Apple Pay and Google Pay payments](en_pp_embedded_payment_buttons.md)**  
An article about using a specialised version of Payment Page that enables seamless, native-style integration of the Apple Pay and Google Pay services.
-   **[UX configuration](en_pp_ux_configuration.md)**  
Articles about the primary workflows for the standard version of Payment Page, including options for opening it, handling redirects to third-party services and back to the web service, and managing these processes.
-   **[Basic actions](en_pp_basic_actions.md)**  
Articles about the core actions that can be performed via the payment form, with the description of user scenarios and relevant request and callback formats for standard card payments.
-   **[Auxiliary procedures and additional capabilities](en_PP_Additional.md)**  
Articles about auxiliary procedures and additional capabilities of Payment Page for boosting payment acceptance rates, customer convenience, and the quality of the provided services.
-   **[Customisation](en_PP__design_customisation.md)**  
An article about the capability of customising the appearance of the payment form with the use of the Payment Page Designer in the Dashboard interface.
-   **[Payment Page API specification](en_PP_Parameters.md)**  
An API specification with the description of data structures used in requests for opening Payment Page.



---

# Overview {#en_PP_general .concept}

An article with the introductory information about Payment Page, the general workflow of using the form, and the overview of its capabilities.

**Parent topic:**[Payment Page](en_PP_about.md)

## Introduction {#en_pp_general_introduction}

Payment Page is a payment form by Ecommpay: it is a flexibly configured software module with user interface designed to processpurchases and payoutsand to perform other actions involving various payment methods.Payment Page can be used in web services and mobile applications and allows processing card payments even if the merchant does not have the PCI DSS compliance certificate.

![](images/eng_functional_pp.svg)

Payment Page is opened via the API, and the merchant can use the API itself or special components that can facilitate its usage: a pluggable JavaScript library, SDK for projects developed in various programming languages, and plug-ins for websites based on a range of the widely used CMS. This diversity of techniques allows efficiently configuring Payment Page for very different projects.

Payment Page is opened on the customer's device as a separate browser tab, a modal window or an iframe object embedded into the HTML pagewith the standard or a customised design applied. Payment Page display mode, the way of handling intermediate actions and showing information about the result can be configured in the request for opening the payment form.Therefore, this variety of options allows efficiently configuring Payment Page for different user stories.

![](images/ecommpay/en_pp_general_1.svg "Payment Page displayed as an iframe object embedded into the HTML page")

![](images/ecommpay/en_pp_general_2.svg "Payment Page displayed as a modal window")

![](images/ecommpay/en_pp_general_3.svg "Payment Page displayed as a separate browser tab")

This section contains the overview of capabilities of Payment Page and interaction process through itas well as the emulator showing its functioning in accordance with different scenarios.

## Interaction model {#en_pp_general_interaction}

When Payment Page is used, all interactions between the payment platform, on the one side, and, on the other side, the customer's device and the server side of the web service are handled with the use of HTTP, version 1.1 or higher, and TLS, version 1.2 or higher. Payment Page supports the latest versions of such browsers as Google Chrome, Safari, Opera, Mozilla Firefox, Microsoft Edge, QQ Browser, Mi Browser, Samsung Internet, 360 Secure Browser and others. For more detailed information about using Payment Page in different technical environments, contact the Ecommpay technical support \([support@ecommpay.com](mailto:support@ecommpay.com)\).

In terms of the interaction diagram, the customer, the front end and the back end of the web service, the payment platform, Payment Page and the payment environment are all seen as separate parts.

![](images/eng_paymentpage_functional.svg "Interaction diagram")

Generally interaction process through Payment Page is handled as follows:

1.  In the user interface of the web service the customer invokes the payment form by clicking payment button or using some other pre-configured method of invoking the payment form.
2.  A set of Payment Page invocation parameters is formed on the client side and then transferred to the server side.
3.  On the server side verification and addition of the parameters are performed if needed. The signature for the final set of parameters is formed, and after that the signed data is transferred back to the client side. It is the final set of the parameters that must be signed, containing all parameters required by the API and information about preferred way of opening the payment form; otherwise the request will be incorrect.
4.  On the client side request for opening Payment Page is generated and sent to the payment platform.
5.  On the side of the payment platform Payment Page is configured in accordance with the Payment Page invocation parameters. The data is transferred to the customer's device for the payment form to be opened.
6.  The payment form is displayed in the user interface.
7.  The customer makes necessary steps on the payment form: selects the payment method \(if it is not specified in the request for opening the payment form\),enters payment information and other requested details and confirms paymentor another operation \(for instance, card verification\).
8.  A request to perform the required action including all data specified by the customer is sent from Payment Page to the payment platform.
9.  In the payment platform the payment is registered and all technical activities are performed, including transferring the required data toproviders and payment systems.
10. In the payment environment the required systems process the payment, and information about the payment result is transferred to the payment platform.
11. The information about the result is processed in the payment platform, and a callback is sent to the URL specified by the merchant \(the same is true for other interfaces of the payment platform as well\).
12. Information about the result is transferred from the payment platform to Payment Page.
13. Information about the result is displayed in the user interface on Payment Page itself or on the page to which the customer is redirected, according to the configuration.

The diagram shows the key points of interaction process through Payment Page on the side of the merchant. However, in particular cases intermediate actions among the customer, Payment Page, the payment platform and the payment environment \(steps 7–10\) can be different.For instance,during 3‑D Secure authentication or payment processing confirmation in alternative payment system, additional steps may be required, or if Payment Page is used for saving payment data, the payment is not registered \(step 9\) and step 10 is omitted. The variety of options taking place on steps 7–10 can affect user stories, and, on the one hand, no additional actions are required on the side of the web service when these steps are performed; on the other hand, the set of parameters that is formed on steps 2–3 can significantly affect the subsequent user story. In order to meet the needs of a specific project, it is possible to use Payment Page capabilities described below and configure the required scenario in cooperation with the Ecommpay technical support.

The basic usage scenario is the following:

1.  The customer selects the option to make a purchase, opens Payment Page, and selects the payment method.

    \(Steps 1–6 and partially step 7 in the interaction diagram\)

    ![](images/ecommpay/en_pp_general_4.svg)

2.  The customer specifies the requiredpayment data, confirms the purchase and waits for information about the result.

    \(Steps 7–12 in the interaction diagram\)

    ![](images/ecommpay/en_pp_general_5.svg)

3.  The customer receives the information about the payment result.

    \(Step 13 in the interaction diagram\)

    ![](images/ecommpay/en_pp_general_6.svg)


Technically, it is possible to use Ecommpay components as well as technologies preferred by the merchant to open Payment Pageand process program notifications. These Ecommpay components are:

-   Pluggable JavaScript library. It is connected to the client side and supports various ways of opening Payment Page \(step 4\)and event handling in the user interface, which includes the functionality of payment buttons embedded in the web service for processing express checkout payments with Apple Pay and Google Pay.
-   Software development kits \(SDK\) for web services developed in different programming languages.
-   Software development kits for mobile applications based on Android and iOS. They are connected to the client side of application and allow using payment platform which is compatible with mobile interfaces \(support for steps 2 and 4 with no need for using browser on steps 6–13\).
-   Plug-ins based on a range of the widely used CMS.They are enabled through administrative panel of the CMS and provide all necessary actions both in the client and in the server side with no need for programming by the merchant.

In addition to the described features, the merchant can monitor Payment Page functioning. By default, the merchant is not notified about the opening of Payment Page; however, this option can be configured. Using the Ecommpay JavaScript library the merchant can collect and process information about the opening of Payment Page or about an error while opening Payment Page \(if an error occurs\), about confirmation of operation by the customer or about closing the payment form, and about other actions in the interface of the payment form. After operation is confirmed in Payment Page and the payment is registered in the payment platform, it is possible to obtain information about the payment status by sending a request through Gate and Dashboard.

## Capabilities {#en_pp_general_capabilities}

### Support for various required actions {#section_nfk_wlz_mlb .section}

Payment Page allows performing the following required actions:

-   *Payment processing.* Payment processing, especially processing one-step purchases, is the most common way of using the payment form. One-step purchase means that during one Payment Page session a one-time transfer of funds from the customer to the merchant is made; for instance, this option can be used for payment for an item of goods.
-   *Authorization hold.* When authorization hold is performed, in terms of one Payment Page session the payment amount is deducted from the customer's account, and after that the merchant can either charge the held amount or, alternatively, release the funds \(using Gate, Dashboard, or automatically after a specific time lag\). For instance, this option is relevant when the customer books a hotel or rents a car.
-   *COF purchases registration.* When building lasting customer relationships, it can be convenient to be able to process COF purchases without requiring the customer to enter payment information or make any steps at all \(for instance, this is relevant for subscription payments\). The payment platform supports COF purchases processing, and using Payment Page the merchant can register all types of COF purchases — regular payments, automatic payments and express payments \(OneClick\), by specifying correspondent parameters in the request for opening the payment form.
-   *Performing payouts.* This option allows transferring funds from the merchant to the customer following the initial registration of a payout via Gate.
-   *Payment instrument verification.* This option is designed to verify the payment instrument\(most commonly, payment card\), for instance, for performing payouts to the customers. In terms of one Payment Page session the payment instrument is validated by either transferring a dummy \(zero\) amount from the customer to the merchantor by authorizing a specific amount \(non-zero\) on the customer's card or account and then voiding the transfer or the authorization.
-   *Tokenization.* During tokenization no payment operations, including transfer of dummy amount, are performed, but information about the payment instrument is registered, and a secure identifier \(token\) for the customer's payment instrument is created. Tokenization is applicable to payment cards and serves for saving customer's payment information, for instance, during customer's registration on the web service, and then using this payment information for facilitated processing of payments.

The required action is configured by specifying corresponding parameters in the request for opening the payment form and defines the way of using the payment form. For different scenarios various features are available, including entering and saving payment information, collecting additional information and using other options described below.

### Support for different data input options {#section_ztb_mzn_nlb .section}

Payment Page supports various ways ofselecting payment methodandentering payment information.

*Payment method* can be selected as follows:

-   *On the payment form, out of all available methods.* This is the basic option which means that the customer selects the payment method out of all methods available for the merchant in terms of the project.
-   *On the payment form, out of the specified methods.* In some cases it may be necessary to show only some of all available payment methods. For instance, this option is especially convenient when specific regional features should be taken into account. The required payment methods are specified by using corresponding parameters in the request for opening the payment form, and the customer selects one of the methods from the defined list.
-   *Outside the payment form, before the payment form is opened.* Payment method can also be selected on the web service side before Payment Page is opened \(for instance, in an “Add to Cart” section\). In this case the payment method is specified in the request for opening the payment form, and user input starts from the step of entering the payment information, without selecting the payment method.

*Payment information* can be entered as follows:

-   *On the payment form, by completing the fields.* In this case the customer completes all the fields on the payment form.

    In case of card payments, it is possible to make the field with the cardholder name optional instead of required. Note it can only be done upon consultation with your account manager which includes examination and assessment of associated risks.

-   *On the payment form, with an option to use saved payment information.* If the customer's identifier is specified in the request for opening the payment form, the customer can either choose one of the saved payment instruments or enter new payment information; the new payment instrument can also be saved for subsequent purchases.

    In addition to selecting payment instrument, for some payment instruments entering verification code is required \(such as CVC, CVV or CID for card payments\).

-   *Outside the payment form, with an option to use saved payment information.* In this case the customer selects specific card in the web service, the token of this card is specified in the request for opening the payment form, and, when the payment form is opened, it already contains all required payment information, except for verification code \(CVC, CVV, CID\) which the customer is required to enter on the payment form.

Along with these options that require the customer to complete the fields,*Payment Page supports MO/TO payments* which mean that *the data is entered by merchant's employee*. The type of the order \(Mail Order/Telephone Order\) is specified in the request for opening the payment form and affects the scenario of using the payment form.

### Support for additional features {#section_s3v_mzn_nlb .section}

In addition to basic scenarios \(with each of them containing an option to select payment method,enter payment information and perform other necessary steps\), Payment Page also supports the following features:

-   *Currency selection by the customer.* In this case the customer can select one of the currencies available on the payment form for processing the payment. If needed, currency conversion is performed on the side of the payment platform in accordance with the current exchange rate.
-   *Collection of additional information about the customer.* Additional fields can be placed on the payment form in order to collect additional information about the customer, for instance, their address, telephone number and date of birth. The fields can be selected out of those available in the payment platform and can be marked as mandatory and optional for the customer to complete.
-   *Additional attempts to enter payment information.* If this option is used, in case of an error while performing required action the customer gets an error message \(for instance, indicating insufficient funds\) and has an option to repeat the attempt.After that, if the customer agrees to repeat the attempt, the customer can selecta different or the same payment method with no need to enter the data that was filled in during the previous attempt.
-   *Cascading.* This feature resembles the option of making additional attempts to enter the payment information: if something goes wrong, the customer can repeat the attempt to process the payment. However, this feature is aimed at preventing errors that occur on the side ofproviders and payment systems and not as a result of incorrect data input. In this case, in accordance with the configurations, additional attempts to process the payment are performed through stand-byproviders and payment systems.
-   *Sending notifications to the customer.* This option allows sending notifications about payment processing to the customer's email. It is possible to configure the content and format of the email messages and use different patterns for different types and statuses of the operations \(this is especially relevant for `success` and `decline` statuses\).

All these features are enabled and configured in cooperation with the Ecommpay technical support by agreement with Ecommpay Key Account Manager, which makes it possible to find and implement the best solution for every particular case.

### Support for auxiliary procedures {#section_zrl_nzn_nlb .section}

In some cases payment processing may require auxiliary procedures, such as authentication on the issuer's side. Generally, the need for such procedures depends on protocols and rules ofpayment providers and payment systems, but in some cases merchant's preferences can also be taken into account \(these preferences should be discussed with Ecommpay Key Account Manager\).

These auxiliary procedures do not require any additional actions on the merchant's side. However, it may be useful to know what features are available and if they require the customer to make any steps.

Payment Page supports the following auxiliary procedures:

-   *3‑D Secure authentication.* 3‑D Secure \(Three-Domain Secure\) authentication is applied to card payment processing in order to prevent fraud.

    In terms of 3‑D Secure authentication, either the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed \(while issuer confirms authentication with no customer effort required\).

-   *Authentication on merchant's request.* This type of authentication is supported by some providers and, at merchant's option, can be used to replace 3‑D Secure authentication or in addition to it. For instance, authentication on merchant's request can be appropriate if authentication methods used by the issuer are not secure enough.

    In terms of authentication on merchant's request, an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account.

-   *Address Verification Service check.* Address Verification Service \(AVS\) check is aimed at providing additional anti-fraud protection during card payment processing. AVS check consists in matching the address specified by the customer during payment processing with the address specified for the cardholder on the side of the card issuer. Address Verification Service check is mandatory for payments committed in the UK and optional in the USA, Australia, Canada and New Zealand.

    To complete AVS check, the customer needs to specify their address and post code.

-   *Providing additional payment information.* This procedure allows processing payments when payment system or payment platform require additional data that otherwise is not required. This data may be needed due to particular regional requirements, additional anti-fraud check or other circumstances.

    When providing additional information is required, corresponding notification and fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form, and once they are, the procedure continues in the ordinary way.


In case of any questions about auxiliary procedures check the corresponding section of documentation or contact the Ecommpay technical support.

### Support for different ways of displaying information about the result {#section_l52_4zn_nlb .section}

The information about the payment processing result can be displayed on the payment form as well as in the merchant's web service.

-   When information is displayed on the payment form, standard final page of the payment form is used with a message saying that the action is completed \(`success` status\) or declined \(`decline` status\) and a button leading to the web service, if needed.
-   When information is displayed in the web service, the final page of the payment form is not used, and the customer is redirected to the merchant's web service to receive information about the result in any format at merchant's option.

The way of displaying information about the result can be configured by using corresponding parameters in the request for opening the payment form, and for redirecting the customer to the web service, either the default URLs or the URLs specified in the request for opening the payment form can be used. The URLs can be similar or different for `success` and `decline` statuses.

This diversity of options provides the required flexibility and allows showing different final pages for different required actions, regions, groups of customers when it is needed.

### Monitoring payment form usage and required actions result {#section_j1x_4zn_nlb .section}

Payment Page user experience is monitored primarily by the Ecommpay payment platform; however, it is also possible to monitor user experience on the merchant's side using the following features:

-   *Monitoring the payment form events.* Using Ecommpay JavaScript libraries, the merchant can collect and process information about opening Payment Page or an error during this step \(if an error occurs\), about confirmation of the required action by the customer or closing the payment form, and about other payment form events.

    This feature allows to efficiently react to important payment form events on the client side. Thus, the customer can be asked about the reason of closing the payment form or additionally notified about the expiring time lag to enter the payment information. These monitoring options also provide the merchant with a basis for the further analysis of Payment Page user experience in different user stories.

-   *Time limit for entering payment information.* Specific time lag for the customer to enter the payment information can be configured at opening Payment Page. In this case the timer is displayed on the payment form, and if the customer does not confirm the required action during the configured time lag, an error message is displayed.

    This feature allows to avoid “freezing” of the opened payment form for a long or indefinite time and controlling delivery of services to the customer \(for instance, this may be especially applicable to sale of tickets, goods and other events relevant during specific time\).

-   *Result monitoring.* There are different features that allow the merchant to check the result of interaction process through Payment Page. These include:
    -   *Notifications* that are sent automatically to the specified URLs upon result of performing required actions and contain detailed information about the result. With these notifications automatic monitoring can be handled on the server side.
    -   Special *requests that are sent to the Gate API and Data API* and allow receiving detailed information about specific payments and groups of payments when it is necessary on the web service side.
    -   *Features of Dashboard* that allow monitoring and analysing the process by merchant's employees, including specific payments as well as common rates.

These features allow the merchant to monitor almost all aspects that can be important when the payment form is used.

### Support for customisation {#section_mtn_pzn_nlb .section}

The visual appearance of Payment Page can be flexibly customised. It is possible to customise the following:

-   *Payment form opening mode.* Payment Page can be opened by clicking a button or using other interface events.To configure the mode of opening the payment form, the merchant can either use the pluggable Ecommpay JavaScript library that contains the required methods, or configure required functions in the web service.
-   *Payment form display mode.* Payment Page can be displayed as follows:

    -   as a separate browser tab
    -   as a modal window
    -   as an iframe object embedded into the HTML page
    The merchant can use the most appropriate option for specific type of device and user story by specifying the required option in the request for opening the payment form.

-   *Options of redirecting the customer.* Performing required actions sometimes involve redirecting the customer to the third-party services, for instance, in order to perform 3‑D Secure authentication orconfirm payment processing on the payment system side. To perform redirection to the third-party service, a separate HTML-page \(in a current or a new browser tab\) or an iframe object embedded into the HTML page can be used. Redirection option is configured by the Ecommpay technical support with consideration to merchant's preferences.
-   *Template customisation options.* Standard or customised design of the payment form can be used—depending on the needs and preferences of the merchant. To configure a customised version of the payment form, the merchant can use [the Payment Page Designer](en_PP__design_customisation.md). If there are any questions or suggestions regarding customisation that is beyond the scope of the designer, the merchant should contact their Ecommpay account manager.
-   *Language configuration of the payment form.* The interface of Payment Page can be displayed in various languages. The required language can be specified in the request for opening the payment form. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default\). In addition, it is possible to configure a drop-down list of languages and therefore give the customer an option to select the language of the payment form. This functionality is configured by the Ecommpay technical support.

Configuration of all these features allows to efficiently incorporate Payment Page in almost any web service, thus highlighting its unique character.

## Exploring Payment Page {#en_pp_emulator}

To explore the Payment Page user interface, you can use the demo version available [on the Ecommpay website](https://ecommpay.com/core-functionalities/integrations/hosted-payment-page/). It replicates a workflow of a standard one-step purchase that can be made with a range of payment methods and showcases different options for opening the 5th generation of Payment Page.

In addition, you can use the emulator provided below to explore various payment processing scenarios via the 4th generation of Payment Page.

|This interactive preview of different card payment processing scenarios in a hypothetical integration that involves a sample web service, Payment Page and third-party services \(such as ACS, for example\) allows you to select various options to modify these payment scenarios, so you can later compare and contrast them.

 Note that in production the exact replication \(i.e. accurate to a single character or pixel\) of the scenarios provided in this preview is not guaranteed. The purpose of these scenarios is to showcase Payment Page and the steps that may be required of the customer in different cases.

 In case of the 5th generation Payment Page, the general workflow of processing scenarios, as a rule, remains the same, while the design style and certain interface elements of the payment form may differ. Illustrations for most of the existing payment processing scenarios via the 5th generation Payment Page can be found in the articles on this documentation portal.

 **Note:**

Cookies are required for the emulator to function properly. It will not load without cookies.

The load time of the emulator may vary depending on communication channel, device, and browser. The typical load time is 30–50 seconds. If the load time is much longer or if an error occurs, reload the page.

||



---

# Quickstart {#en_pp_quickstart}

A quickstart guide on how to implement payment processing via Payment Page with the use of SDKs and source code examples.

**Parent topic:**[Payment Page](en_PP_about.md)

## Overview {#en_pp_quickstart_overview}

This guide explains how to organise payment processing via Payment Page. So that the form would open from the web service and return customers to this web service. And so that you could use tested and quick solutions—with clear instructions, libraries, and code examplesin one of the three popular programming languages—PHP, Python, or JavaScript.

![](images/ecommpay/en_pp_quickstart_1.svg)

If you are interested in something else, there are other options available.

-   To learn how to generate payment links for opening Payment Page, you can figure out how to work with them either manually [via Dashboard](en_dbl_payments.md) or automatically [via Gate](en_gate_invoice.md).
-   To get deep understanding of the workflow and the capabilities of the work with Payment Page, you can see [this article](en_pp_interaction_organisation.md).
-   To address other things relevant to you, you can to refer to other sections \(for example, starting [here](en_PP_general.md)\) and contact the Ecommpay specialists.

With that, let’s get started.

## Brief theory {#en_pp_quickstart_theory}

### Projects and keys {#section_bqj_cx2_4tb .section}

Working with the Ecommpaypayment platform can be compared to using hotel services: to check into a hotel, you need a room and a key for this room, and to start working with the platform, you need *a project and a key* for this project. And like in case of hotel rooms, there can be a different number of projects for one client—for different aims and purposes—and each project requires its own key.

Usually, to work with the platform, having one test and one production project is enough. This case is typical and is used as the basis within the Quickstart guide. If for any reason you need more projects, make sure to identify this need in the communication with your account manager. In the meantime, you don't have to wait till this issue gets resolved: you can already start working on the implementation and setup with one test project.

If you have already obtained the identifier \(`project_id`\) and the secret key \(`secret_key`\) of the test project, have them at hand as you proceed with the implementation.Otherwise, you can [get an access](https://ecommpay.com/sign-up/) to the test project and return to this article.

### Workflow {#section_v1f_4x2_4tb .section}

For Payment Page to open correctly, the collection of parameters, signature generation, and the form opening should be set up. Along with that, it is important that data signing \(which requires the secret key\) is performed on the server side of the web service and the payment form opening—on the client side of the web service. Additionally, for the timely monitoring of results, setting up the server side to receive callbacks from the payment platform can be helpful.

This is an overall workflow.

| |Web service front end|Web service back end|In the payment platform|
|--|---------------------|--------------------|-----------------------|
|1|Creating an order. Collecting payment parameters and sending them to the web service back end \(for signing the parameters\)|–|–|
|2|–|Submitting additional parameters \(if relevant\) and signing them, then sending the information to the front end|–|
|3|Creating the request for opening Payment Page and sending it to the payment platform|–|–|
|4|–|–|Accepting the request, preparing and displaying the form to the customer, processing the customer actions and the payment, after that sending the callback with the payment result information and returning the customer to the web service|
|5|–|Accepting the callback with the payment result information and updating the order status

|–|
|6|Displaying the payment information to the customer and the information about the customer further actions \(if such actions are required, for example, for the product delivery\)|–|–|

Generally, this workflow scheme on the client and server sides of the web service can be implemented in a number of ways. This article—for the convenient and quick launch of the work with Payment Page—describes all necessary procedures with the application of ready-to-use components \(such as SDKs\) and code examples to their fullest extent. Still it is always possible to combine our ready-to-use components with your solutions.

### Parameters for opening the form {#section_bf3_rdf_4tb .section}

To display the payment form to the customer, in the simplest case, you just need to decide on the parameters of the payment amount and currency and add the following three identifiers to these two parameters: the identifier of the project, the payment, and the customer. In total, this makes up five required parameters.\(And signing these parameters is technically required.\)

|Parameter|Description|
|---------|-----------|
|`project_id`  
 integer

|Project identifier. Together with the key, it is provided by Ecommpay and should be precisely specified even in test requests. Otherwise, this is going to look as if you are trying to enter someone else's hotel room and the payment platform reacts accordingly.  
 Example: `57123  
`

|
|`payment_id`  
 string

|Payment identifier. It can have random values but always should be unique within the project used. Otherwise, an error occurs.  
 Example: `payment_443  
`

|
|`payment_amount`  
 integer

|Payment amount. In test requests it can be a random amount, while in real ones the amount should correspond to the amount of the order. The amount is specified in minor currency units.  
 Example: `1815` \(for the amount of `18.15`\)  


|
|`payment_currency`  
 string

|Payment currency code. It is specified in the three-letter ISO 4217 alpha-3 format.Test requests can contain any of the applicable codes, while every real request should contain the code of the currency in which the payment is being initiated.  
 The currency codes are provided in the corresponding [reference](en_currency_codes.md).  
 Example: `EUR`  


|
|`customer_id`  
 string

|Customer identifier.It can have random values and be reused in different requests, however, the identifier of every real customer should exactly match the account of this very customer in the web service and be unique within the project.Otherwise, there can occur different issues that also concern displaying to the customer saved payment data of another customer.  
 Example: `customer_112`

|

How to collect these parameters\(as well as which of them should be specified on the client and on the server side of the web service\) is for you to decide\(with regards to your web service architecture and other factors\). For the initial few times of opening the payment form, it is not necessary to automate the collection of parameters, you can deal with this after the primary testing of the payment form operation. There is just one thing left to mention—in addition to the required parameters, you can use other parameters, for managing the payment form look and behaviour; but since it is better to use these parameters after setting up the standard Payment Page opening, they are substantially described [further](en_pp_quickstart.md#section_omd_pzf_4tb).

## Basic implementation {#en_pp_quickstart_basic_implementation}

### Variants of working with the form {#section_h4l_5hf_4tb .section}

The work of the web service functions with the payment form and callbacks can be implemented in different ways, which include creating in-house solutions and applying the CMS modules.Within this article, we consider the two variants of implementation:

-   with the use of the SDKs from Ecommpay on the server side of the web service;
-   with the use of the ready-to-use code from Ecommpay on the server side of the web service.

You can choose among these variants, with regards to their differences, at your discretion.The SDKs can make the work with other programming languages a little easier and more available \(full information about working with the SDKs is provided [in a separate section](en_sdk_overview.md)\). The work with the code examples can be a little more transparent and flexible in terms of embedding them in your own solutions \(as well as when working with signatures\). Still both variants are quite quick and complete, and you can choose any of them.

Along with that, whatever variant of the server functions implementation is used, within this article, we look at different variants of the payment form opening on the client side of the web service, including the usage of libraries from Ecommpay. In general, this is what should be done for the implementation.

|Web service back end|Web service front end|
|--------------------|---------------------|
|-   link the libraries \(when using SDKs\)
-   ensure the submission of additional parameters \(the relevant ones\)
-   ensure data signing
-   ensure the receipt of callbacks

|-   link the libraries \(if relevant\)
-   ensure the collection of parameters \(the relevant ones\)
-   ensure the form opening

|

The collection of parameters and submission of additional ones, as said in the brief theory overview, can be implemented in various ways \(for the primary testing, manual implementation is possible\)which are up to you. Other actions are regarded further.

### Work with SDK {#section_v3j_53f_4tb .section}

Linking and setting up.

**1 Linking SDK**

1.  If this has not been done previously, download, install, and set up the dependency manager Composer \([https://getcomposer.org/](https://getcomposer.org/)\).
2.  Use the operating system command line to open the directory with the web service source code and execute the following command `composer require ecommpay/paymentpage-sdk`.
3.  Include the script `autoload.php` into the web service source code.

```language-php
// linking libraries
require` __DIR__.'../../vendor.autoload.php';
```

 

**2 Ensuring data signing**

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

```language-php
// Generating the signature and the link 

// creating the object of the Payment class and specifying the project and payment identifiers
$payment = new ecommpay Payment('57123', 'payment_443');

// specifying other required parameters
$payment->setPaymentAmount(1815)->setPaymentCurrency('EUR'); // payment amount and currency
$payment->setCustomerId('customer_112'); // customer identifier

// creating the object of the Gate class and specifying the secret key
$gate = new ecommpay\Gate('<secret_key>');

// generating the link for opening the payment form
$url = $gate->getPurchasePaymentPageUrl($payment);
```

 

**3 Setting up the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  Define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-php
// Working with callbacks

// creating the object of the Gate class and specifying the secret key
$gate = new ecommpay\Gate('<secret_key>');

// creating the object of the Callback class and parsing the JSON string
// with the callback data ($data), with the data integrity validation
$callback = $gate->handleCallback($data);

// using methods for receiving information
Callback::getPaymentId();        // receiving the payment identifier
Callback::getPaymentStatus();    // receiving the payment status
Callback::getPayment();          // receiving all information from the callback
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

**1 Linking SDK**

1.  If this has not been done previously, download, install, and set up the package-management system—pip \([https://pip.pypa.io/en/stable/](https://pip.pypa.io/en/stable/)\).
2.  Use the operating system command line to open the directory with the web service source code and execute the following command `pip install ecommpay-sdk`.
3.  Include the libraries from the SDK into the web service source code.

```language-python
# Linking libraries
from payment_page_sdk.gate import Gate
from payment_page_sdk.payment import Payment
```

 

**2 Ensuring data signing**

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

```language-python
# Generating the signature and the link 

# creating the object of the Payment class and specifying the project and payment identifiers
payment = Payment('57123', 'payment_443')

# specifying other required parameters
payment.payment_amount = 1815 # payment amount
payment.payment_currency = 'EUR' # payment currency
payment.customer_id = 'customer_112' # customer identifier

# creating the object of the Gate class and specifying the secret key
gate = Gate('<secret_key>')

# generating the link for opening the payment form
payment_url = gate.get_purchase_payment_page_url(payment)
```

 

**3 Setting up the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  Define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-python
# Working with callbacks

# creating the object of the Gate class and specifying the secret key
gate = Gate('<secret_key>')

# creating the object of the Callback class and parsing the JSON string
# with the callback data (data), with the data integrity validation
callback = gate.handle_callback(data)

# using methods for working with callbacks
callback.get_payment_id()        # receiving the payment identifier
callback.get_payment_status()    # receiving the payment status
callback.get_payment()           # receiving all information from the callback
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

**1 Linking SDK**

1.  If you have not yet installed a package-management system, you need to download, install and check settings. For more information, see: Yarn \([https://yarnpkg.com/en/docs/getting-started](https://yarnpkg.com/en/docs/getting-started)\) or npm \([https://www.npmjs.com/package/ecommpay](https://www.npmjs.com/package/ecommpay)\).
2.  Navigate into the web service source code directory in command line and run one of the following commands: `yarn add ecommpay` or `npm install ecommpay`.
3.  Import the modules into your web service project:

    ``` {#codeblock_ivj_hzy_w1c .language-javascript}
    const { Payment } = require('ecommpay');
    const { Callback } = require('ecommpay');
    
    ```


 

**2 Ensuring data signing**

Only then, when the values for all necessary parameters are defined, this data can be collected on the server side of the web service and the signature and the URL for opening the payment form can be generated. Here is an example of how to do this.

``` {#codeblock_nvx_3zy_w1c .language-javascript}
// Generating the signature and the link

// creating the object of the Payment class and specifying the project identifier and the secret key
const payment = new Payment('57123', 'payment_443');

// specifying the payment identifier
payment.paymentId = 'payment_443;

/// specifying other required parameters
payment.paymentAmount = 1815 // payment amount
payment.paymentCurrency = 'EUR' // payment currency
payment.customerId = 'customer_112' // customer identifier

// generating the link for opening the payment form
const url = payment.getUrl();
```

 

**3 Setting up the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  In the payment platform, define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

``` {#codeblock_zcw_21z_w1c .language-javascript}
// Working with callbacks

// creating the object of the Callback class and specifying the secret key
const callback = new Callback(<secret_key>, req.body);

// using methods for working with callbacks
app.post('/payment/callback', function(req, res) {
  const callback = new Callback(<*secret\_key*>, req.body);
  if (callback.isPaymentSuccess()) {
    const paymentCont = callback.payment();    // receiving all information from the callback
    const paymentId = callback.getPaymentId(); // receiving the payment identifier

    // Add your code for proccessing successful payment
  }
});
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

### Work with code {#section_mhx_p5f_4tb .section}

Embedding and using.

**1 Ensuring data singing**

```language-php
// Coding the algorithm
class Signer
{
    const ALGORITHM = 'sha512';
    const ITEMS_DELIMITER = ';';
 
 
    /**
     * Generate signature
     *
     * @param array $params
     * @param string $secretKey
     * @param array $ignoreParamKeys
     * @param bool $doNotHash
     *
     * @return string
     */
    public static function sign(array $params, string $secretKey, array $ignoreParamKeys = [], bool $doNotHash = false): string
    {
        $paramsPrepared = self::getParamsToSign($params, $ignoreParamKeys, 1, '');
        $stringToSign = implode(self::ITEMS_DELIMITER, $paramsPrepared);
 
        return $doNotHash
            ? $stringToSign
            : base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $secretKey, true));
    }
 
    /**
     * Get parameters to sign
     *
     * @param array $params
     * @param array $ignoreParamKeys
     * @param int $currentLevel
     * @param string $prefix
     *
     * @return array
     */
    private static function getParamsToSign(
        array  $params,
        array  $ignoreParamKeys = [],
        int    $currentLevel = 1,
        string $prefix = ''
    ): array
    {
        $paramsToSign = [];
 
        foreach ($params as $key => $value) {
            if (in_array($key, $ignoreParamKeys, true)) {
                continue;
            }
 
            $paramKey = ($prefix ? $prefix . ':' : '') . $key;
 
            if (is_object($value)) {
                $value = get_object_vars($value);
            }
 
            if (is_array($value)) {
                    $subArray = self::getParamsToSign($value, $ignoreParamKeys, $currentLevel + 1, $paramKey);
                    $paramsToSign = array_merge($paramsToSign, $subArray);               
            } else {
                if (is_bool($value)) {
                    $value = $value ? '1' : '0';
                } else {
                    $value = (string)$value;
                }
 
                $paramsToSign[$paramKey] = (string)$paramKey . ':' . $value;
            }
        }
 
        if ($currentLevel == 1) {
            ksort($paramsToSign, SORT_NATURAL);
        }
 
        return $paramsToSign;
    }


// Usage example

// specifying the secret key and the parameters for opening the payment form
$secretKey = "jwfbfjhewbrw33383kr3js9d987";
 
$params = [
    'project_id' => 57123,     
    'payment_amount' => 1815,
    'payment_currency' => 'EUR',
    'customer_id' => 'customer_112',
    'payment_id' => 'payment_443',
];
 
// generating the signature
$params['signature'] = Signer::sign($params, $secretKey);
 
// receiving the link for opening the payment form
$uriParams = http_build_query($params);
$link = implode('?', ['https://paymentpage.ecommpay.com/payment', $uriParams]);
```

 

**2 Ensuring the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  In the payment platform, define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-php
// Working with callbacks. The example of comparing the received
// signature to the generated one

require_once 'Signer.php';

$secretKey = '<secret_key>';

$requestBody = '{
       "project_id": 57123,
       "payment": {
           "id": "payment_443",
           "type": "purchase",
           "status": "success",
           "date": "2022-03-03T10:50:29+0000",
           "method": "card",
           "sum": {
               "amount": 1815,
               "currency": "EUR"
           },
           "description": "Test payment"
       },
       "customer": {
           "id": "customer_112",
           "ip": "127.0.0.1",
           "phone": "60358490238",
           "email": "jane.doe@testmail.com"
       },
       "operation": {
           "id": 15788000002076,
           "type": "sale",
           "status": "success",
           "date": "2022-03-03T10:50:29+0000",
           "sum_initial": {
               "amount": 1815,
               "currency": "EUR"
           },
           "code": "0",
           "message": "Success"
       },
       "signature": "zwoFECy7H+WZFziw9IgR9031Uu878TuIv3dhFyHvCuvzIdRAzDQA=="
   }';

$requestBodyArray = json_decode($requestBody, true);

$actualSignature = $requestBodyArray['signature'];
unset($requestBodyArray['signature']);
$expectedSignature = Signer::sign($requestBodyArray, $secretKey);

print_r('Actual signature: ' . $actualSignature . PHP_EOL);
print_r('Expected signature: ' . $expectedSignature . PHP_EOL);

if ($expectedSignature === $actualSignature) {
    print_r('Signatures are equal');
} else {
    print_r('Signatures are not equal');
}

print_r(PHP_EOL);
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

**1 Ensuring data singing**

```language-python
# Coding the algorithm
import hmac
import base64
import hashlib
 
 
class Signer:
    def getSign(self, params, key):
        byteKey = key.encode()
        paramsPrepared = self.getParamsToSign(params)
        toSignString = ';'.join(paramsPrepared.values())
        hmacObj = hmac.new(byteKey, toSignString.encode(), hashlib.sha512)
 
return base64.b64encode(hmacObj.digest())

def getParamsToSign(self, params, currentLevel = 1, prefix = ''):
        paramsToSign = dict()
 
for paramKey in params.keys():
 
newParamKey = (prefix + ':' if prefix else '') + paramKey
 
if isinstance(params[paramKey], (dict)):
                subDict = self.getParamsToSign(params[paramKey], currentLevel + 1, newParamKey)
                paramsToSign.update(subDict)
else:
                if isinstance(params[paramKey], (bool)):
                    value = '1' if params[paramKey] == True else '0'
                else:
                    value = str(params[paramKey])
 
sortedParams = dict()
 
for key in sorted(paramsToSign.keys()):
            sortedParams[key] = paramsToSign[key]
 
return sortedParams


# Usage example

# specifying the secret key and the parameters for opening the payment form
import urllib.parse
import Signer
 
params = {
    'project_id': 57123, 
    'payment_amount': 1815,
    'payment_currency': 'EUR',
    'customer_id': 'customer_112',
    'payment_id': 'payment_443',
}

# Generating signature
signer = Signer.Signer()
 
params['signature'] = signer.getSign(params, '<secret_key>')
 
print(params['signature'])

# creating the signature
jointParams = urllib.parse.urlencode(params)
 
link = '?'.join(['https://paymentpage.ecommpay.com/payment', jointParams])
```

 

**2 Ensuring the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  In the payment platform, define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-python
# Working with callbacks. The example of comparing the received
# signature to the generated one

from Signer import Signer
import base64

secretKey = '<secret_key>'
params = {
    "project_id": 57123,
    "payment": {
        "id": "payment_443",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "method": "card",
        "sum": {
            "amount": 1815,
            "currency": "EUR"
        },
        "description": "Astronaut set"
    },
    "customer": {
        "id": "customer_112",
        "ip": "127.0.0.1",
        "phone": "60358490238",
        "email": "jane.doe@testmail.com"
    },
    "operation": {
        "id": 15788000002076,
        "type": "sale",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "sum_initial": {
            "amount": 1815,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "zwoFECy7H+WZFziw9IgR90SEmC+o3qXD7OIaHqgQuqcSwBC09W6yQA=="
}

signer = Signer()
actualSign = params['signature']
del params['signature']
expectedSign = signer.getSign(params, secretKey).decode()

print('Actual signature:' + actualSign)
print('Expected signature:' + expectedSign)

if (expectedSign == actualSign):
    print('Signature is correct')
else:
    print('Signature is incorrect')
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

**1 Ensuring data signing**

``` {#codeblock_fpz_q3z_w1c .language-javascript}
// Coding the algorithm
import hmacSHA512 from 'crypto-js/hmac-sha512';
import encBase64 from 'crypto-js/enc-base64';

export class Signer {
  getSign(params, key) {
    const paramsPrepared = this.getParamsToSign(params, 1);

    const joinedString = Object.values(paramsPrepared).join(';');

    const hash = hmacSHA512(joinedString, key);

    return hash.toString(encBase64);
  }

  getParamsToSign(
    params,
    prefix = '',
  ) {
    let paramsToSign = {};
    let value = '';

    let keys = Object.keys(params);
    let key = '';
    for (let i = 0; i < keys.length; i++) {
      key = keys[i];

      let paramKey = (prefix ? prefix + ':' : '') + key;

      if (typeof params[key] === 'object') {
        let subParams = this.getParamsToSign(
            params[key],
            paramKey,
          );

          Object.assign(paramsToSign, subParams);
      } else {
        if (typeof params[key] === 'boolean') {
          value = params[key] === true ? '1' : '0';
        } else {
          value = params[key].toString();
        }

        paramsToSign[paramKey] = paramKey + ':' + value;
      }
    }

    let orderedKeys = Object.keys(paramsToSign).sort();

    let ordered = {};

    for (let k = 0; k < orderedKeys.length; k++) {
      ordered[orderedKeys[k]] = paramsToSign[orderedKeys[k]];
    }

    return ordered;
  }
}

// Usage example

import { Signer } from './signer.js';

// specifying the secret key and the parameters for opening the payment form
let params = {
  project_id: 57123,
  payment_amount: 1815,
  payment_currency: 'EUR',
  customer_id: 'customer_112',
  payment_id: 'payment_443',
};

// generating signature
params['signature'] = new signer().getSign(params, '<secret_key>');

// receiving the link for opening the payment form
const uriParams = Object.keys(params)
  .sort()
  .reduce((paramsArray, key) => {
    paramsArray.push(key + '=' + encodeURIComponent(params[key]));
    return paramsArray;
  }, []);
const link = [
'https://paymentpage.ecommpay.com/payment',
  uriParams.join('&'),
].join('?');
```

 

**2 Ensuring the receipt of callbacks**

To keep track of the payment results and other significant information, you can set up receiving and processing program callbacks sent from the payment platform. This is done in three steps:

1.  In the payment platform, define and specify the URL for receiving callbacks by the web service within the project\(at first, one URL can be specified, and then there can be several ones for various events\). This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbacks, which are sent to the specified URL, with the use of the SDK.
3.  Set up sending of synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-java
// Working with callbacks. The example of comparing the received
// signature to the generated one

import { Signer } from './Signer';

const secretKey = '<secret_key>';

const params = {
    "project_id": 57123,
    "payment": {
        "id": "payment_443",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "method": "card",
        "sum": {
            "amount": 1815,
            "currency": "EUR"
        },
        "description": "Astronaut set"
    },
    "customer": {
        "id": "customer_112",
        "ip": "127.0.0.1",
        "phone": "60358490238",
        "email": "jane.doe@testmail.com"
    },
    "operation": {
        "id": 15788000002076,
        "type": "sale",
        "status": "success",
        "date": "2022-03-03T10:50:29+0000",
        "sum_initial": {
            "amount": 1815,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "zwoFECy7H+WZFziw9IgR90SHvCuvqXD7OIaHqgQuqcSwBC09W6yQA=="
};

const actualSignature = params['signature'];
delete params.signature;
const expectedSignature = (new signer()).getSign(params, secretKey);

console.log('Actual: ' + actualSignature);
console.log('Expected: '+expectedSignature);

if (actualSignature == expectedSignature) {
    console.log('Signatures is correct');
} else {
    console.log('Signature is incorrect');
}
```

The payment statuses used in the payment platform are described [in a separate section](en_platform_payment_model.md), and the information about callbacks and their usage is provided [in a separate article](en_platform_callbacks.md). It should be noted that when a purchase is not confirmed by the customer in the payment form, it is not registered in the payment platform \(thus does not have any status as well\).

The information retrieved from the callbacks can be used for promptly updating the statuses of the orders in the web service, informing customers, and for other purposes—according to the web service operation model.

### Actions on the client side {#section_tmn_nwf_4tb .section}

Payment Page can be opened on the client side of the web service in various ways, and to get the feel of them, you can try several options even within the Quickstart guide.

The easiest option is to open the payment form in a separate browser tab.

To open the payment form as a separate HTML page, you should use the link obtained during signature generation.The link has the format of `https://paymentpage.ecommpay.com/payment?<parameters>` where `<parameters>` is a data string containing the names and values of the parameters.

In this case, the HTTP request with the use of the GET method can look as follows:

```language-xml
GET
/payment?payment_currency=EUR&project_id=42&payment_amount=1000&
customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1

Host: https://paymentpage.ecommpay.com
```

To use other options—opening the payment form in a modal window and in an iframe element—you need to link the two libraries: CSS for the form to be displayed correctly and JavaScript for the form to open.This is done via adding the links to the libraries in the header of the web service HTML page.

```language-xml
<head>
...
// linking the CSS library
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> 

// linking the JavaScript library
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js">
</script>
...
</head>
```

For opening the payment form with the help of the JavaScript library, the signed set of parameters in the form of the JavaScript object should be used. The set can be formed by way of parsing the link received when the data was signed\(in the PHP language, you can use the `parse_url` and `parse_str` functions for this\) or using the server code for generating the signature \(without generating the link\)and adding the signature to other parameters.

After linking the libraries and dealing with the parameters, you can try opening the form.

For Payment Page to open in a modal window, the `run` method of the JavaScript `EPayWidget` object can be used. When calling this method, you should specify the object with the parameters for opening Payment Page \(`configObj`\) and the HTTP method for sending requests \(`method`\):

```language-json
EPayWidget.run(
             { payment_id: 'payment_443',            // payment identifier
               payment_amount: 1815,                 // payment amount
               payment_currency: 'EUR',              // payment currency code
               project_id: 57123,                    // project identifier
               customer_id: 'customer_112',          // customer identifier
               signature: 'YWb6Z20ByxpQ30hfTI' },    // signature
             'post') // HTTP method
```

For Payment Page to open in the iframe element with a button click on the web service page, as with the modal window, the `run` method of the JavaScript `EPayWidget` object can be used. When calling this method, you should specify the object with the parameters for opening Payment Page \(`configObj`\) which also contains the identifier of the element in which the payment form should be displayed \(`target_element`\), and the HTTP method for sending requests \(`method`\):

```language-json
EPayWidget.run(
             { payment_id: 'payment_443',            // payment identifier
               payment_amount: 1815,                 // payment amount
               payment_currency: 'EUR',              // payment currency code
               project_id: 57123,                    // project identifier
               customer_id: 'customer_112',          // customer identifier
               signature: 'YWb6Z20ByxpQ30hfTI',      // signature
               target_element: 'widget-container' }, // element identifer
             'post') // HTTP-method 
```

For the primary introduction, these opening options can suffice. If you need a more tailored approach, refer to [the documentation](en_PP_Integration.md) and contact our specialists.

## Testing {#en_pp_quickstart_testing}

When the payment form is opened in the production mode, it is intended to be used by the customer. In the test mode, you can put yourself in the customer's shoes and test various purchase scenarios as if you were paying for something. The key question here—what credentials should be specified?

In the test project, there are two available types of payment credentials: *special* test credentials, which allow you to test predefined payment scenarios, and *random* realistic credentials, which allow you to additionally test the payment form operation in various cases.

For bare minimum testing\(to process payments according to the shortest scenarios, without the emulation of the 3‑D Secure authentication\), use the following numbers of test cards:

-   `4000 0000 0000 0077`—for a purchase to be processed;
-   `4111 1111 1111 1111`—for a purchase to be declined.

![](images/ecommpay/en_pp_quickstart_2.svg)

For the purposes of the more comprehensive testing, it is possible to use extended test data for [card](en_test_cards.md) payments\(including scenarios with the 3‑D Secure authentication\)and various [alternative](en_pm_testing.md) payments, as well as random data including the credentials of cards, wallets, and other payment instruments. This is safe since all data in the test and the production environment is protected equally, although in the test environment there are no actual payments taking place.

After testing and ensuring the correct work with the form, the basic functions for purchase processing can be considered implemented, and when desired, you can move on to various additional aspects, which can be helpful at the initial stages of working with the payment platform, and to launching the solution operation.

## Additional aspects {#en_pp_quickstart_additional_aspects}

### Monitoring of payment processing {#section_p3x_dzf_4tb .section}

After processing several testpayments, you can explore how to monitor the overall payment situation. For this, use the register and the payment information tabs in Dashboard.

![](images/ecommpay/dbl/en_quickstart_dbl_overview.svg "Payments register")

![](images/ecommpay/dbl/en_quickstart_dbl_payment_details.svg "Payment information tab")

With questions about working with this interface, and about other issues, refer to [the documentation](en_dbl_payments.md) and contact our specialists.

### Refunds {#section_rdk_3zf_4tb .section}

When you need to refund a purchase, Dashboard can be used as well. When testing the work with the payment form, you can try to make full and partial refunds via the payment information tabs.

To delve into the topic about working with refunds, including mass refunds, you can use [the separate article](en_dbl_payments.md).Besides, knowing about refunds [via Gate](en_Gate_Refund.md) can be useful.

### UX capabilities of the form {#section_omd_pzf_4tb .section}

The work with Payment Page can be supplemented by various capabilities that include managing the form’s look and behavior—for example, setting the relevant language, filtering payment methods, or managing the ways of returning the customer to the web service. Some of such capabilities can be set up only via the Ecommpay specialists, others can be applied without the anyone’s involvement, just via Dashboard or by sending additional parameters in the requests for opening Payment Page.

For testing the Payment Page operation, we recommend that you try the following:

-   *Customise the payment form with the help of the Payment Page Designer*.

    For this, in the **Projects** section of the Dashboard interface, use the tools of the **Payment Page Designer** tab \(for more information, see [Customisation](en_PP__design_customisation.md)\).

-   *Try opening the payment form in different languages*.

    For opening Payment Page in a specific language, this language code \(in the two-letter ISO 639-1 alpha-2 format\) should be sent as the value of the corresponding parameter—`language_code`. The list of the languages supported by Ecommpay is provided [here](en_PP_WigetLanguages.md).

-   *Return the customer to the web service after payment processing*.

    After the payment processing and depending on the payment result, the customer can be returned to different pages of the web service. The URLs of such pages can be specified in the **Projects** section of the Dashboard interface \(in the **Redirect URLs** tab\) or sent in certain requests as the values of the parameters `merchant_success_url` and `merchant_fail_url`.

-   *Apply the capabilities to suit your needs*.

    The information about different capabilities is provided [in the overview](en_PP_general.md) and [in the specialised section](en_PP_Additional.md), and the list of the parameters for opening the form is provided [in the separate article](en_PP_Parameters.md). All questions, as usual, can be forwarded to our specialists.


## Launch {#en_pp_quickstart_launch_project}

After implementing the basic functions, testing various capabilities, and defining the scenarios of the work with Payment Page relevant for you, you can start launching the production project. It is important that by this time all organisational issues have been resolved—in this case, the technical issues come down to configuring the project settings on the payment platform side and beginning to use the identifier and the key of the production project.

Good luck!



---

# Interaction concepts {#en_pp_interaction_organisation}

An article about organising the work with Payment Page on the web service side based on the principles of the payment platform operation.

**Parent topic:**[Payment Page](en_PP_about.md)

## Overview {#en_pp_interaction_organisation_overview}

The Payment Page payment form supports multiple usage scenarios to processpurchases and payoutsand to perform other actions. For instance, you can call Payment Page API, use an Ecommpay library, or open the form either in a new browser tab or inside the web service page. Different Payment Page usage scenarios are covered in the [Overview](en_PP_general.md) section while the current section describes the order and technical aspects of integration by using Payment Page.

Disregarding any technical solution you may use, the basic requirements for using Payment Page include the following:

-   The payment form can be invoked by using HTTP version 1.1 or higher and TLS version 1.2 or higher.
-   All the request and callback data must use UTF-8 encoding.
-   The requests should be sent to the following basic address: https://paymentpage.ecommpay.com.
-   The following browsers are supported: Google Chrome, Safari, Opera, Mozilla Firefox, Microsoft Edge, QQ Browser, Mi Browser, Samsung Internet, 360 Secure Browser and some others.

This section describes integration options, operation workflows, and request formats. For more information regarding Payment Page operation in various environments, refer to Ecommpay support service.

## Integration steps {#en_pp_integration_step}

To integrate with the Ecommpay payment platform by using Payment Page, merchants should do the following:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained the project identifier or a secret key from Ecommpay,submit [the application](https://ecommpay.com/apply-now/) for connecting to the Ecommpay payment platform.
    2.  For processing payments made with the Visa and Mastercard cards, provide the Ecommpay key account manager with the documents of compliance with [the PCI DSS requirements](en_faq_integration.md#fig_fgk_rgs_4nb). The following documents are required:
        -   From all merchants—[the ASV scan](en_glossary.md) report.

            ASV scanning must be performed by the authorised scanning service providers \(PCI SSC Approved Scanning Vendor, ASV\) quarterly and after every significant change in the network infrastructure.The Ecommpay merchants can select these providers on their own and, if relevant, involve a provider that is in partnership with Ecommpay. To have the scanning services via the partner organised, contact the key account manager.

        -   From the merchants processing over 6 million operations annually \(Level 1\)—the Attestation of Compliance, AOC.
        -   From the merchants processing to 6 million operations annually \(Levels 2, 3, and 4\)—[the Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment), SAQ.

            With questions on completing the questionnaire, contact the Ecommpay key account manager.

    3.  If the payment form customisation is needed, contact the Ecommpay key account manager to discuss the usage of [the design builder](en_PP__design_customisation.md) or other customisation means.
    4.  Coordinate the procedures of integrating with the payment platform, testing\(including testing various payment methods\), and launching the functionality with the Ecommpay technical support specialists.
2.  Complete preliminary technical tasks by using either your in-house resources or the specialised components offered by Ecommpay:
    1.  If customising the payment form with the use of [the design builder](en_PP__design_customisation.md) is relevant, get the access to the Dashboard user account with the corresponding rights via the technical support specialists and configure the payment form design. If another customisation means has been discussed and accepted, address the corresponding issues in cooperation with the key account manager and the technical support specialists.
    2.  Install and link all the necessary librariesand/or plugins.
    3.  On the client side of the web service, implement collecting the parametersnecessary for performing the required actions; also implement forming and sending requests for opening Payment Page.
    4.  On the server side of the web service, implement signature generation and callback response processing.
3.  Test the required actions and launch the integration solution in coordination with the Ecommpay technical support specialists.

    Upon testing and monitoring, when the required actions are performed correctly, the Ecommpay technical support specialists interact with the web service in the full-time support mode.


With any questions about working via Payment Page, contact the Ecommpay key account manager and the technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

## Interaction models {#en_pp_interaction_scheme}

Every target activity on Payment Page requires interaction of three sides: the customer, your web service, and Payment Page. The interactiongenerally proceeds as follows:

-   Interaction between the web service and Payment Page uses HTTP messages and follows the “request-response” model in which the client part of the web service issues requests while Payment Page synchronously responds to the web service front end and sends asynchronous responses to the web service back end. As a rule, Payment Page responds with callbacks that contain processing results, although in some cases, Payment Page may respond with intermediate callbacks, for example, when customer attempts to enter data more than once.Also, your web service may listen to events fired by Payment Page.
-   Interaction between the customer and Payment Page is based on payment form GUI and under the hood, it is implemented as “request-response” exchange of HTTP messages between customer's browser and Payment Page.

Overall interaction model is shown on the following figure.

![Interaction model](images/en_pp_interaction_concept_uml.svg)

1.  The customer uses the web service front end to initiate target activity.
2.  On the web service front end, the parameters required for the request to open Payment Page are collected and passed to the web service back end.
3.  The back end processed the request by doing the following:
    -   Parameters check
    -   Extending the parameters with the information available on the back end, if necessary
    -   Signature generation for the parameters set
4.  The back end sends response to the request to the front end.
5.  The front end receives the response, and then generates and submits request to open Payment Page to specific Ecommpay URL.
6.  The request to open Payment Page enters the payment platform.
7.  The payment platform performs initial request processing which includes inspection whether all the required parameters are available and the signature is correct.
8.  Payment Page is prepared in according with project settings and request parameters.
9.  The complete payment form is displayed to the customer.
10. The customer completes all required steps.
11. The payment request enters the payment platform.
12. The payment platform processes the request and forwards it to the payment environment.
13. The payment environment processes the payment.
14. The payment environment sends the payment processing result notification to the payment platform.
15. The payment platform sends the payment processing result to the web service.
16. The payment platform sends the payment processing result to Payment Page.
17. The payment processing result is displayed to the customer on Payment Page.

## Web service setup {#en_pp_interaction_preparing_webservice_page}

### Overview {#section_lkl_dlz_1mb .section}

Before you start using Payment Page, you need to implement the following functionality in your web service:

-   Collection of payment parameters
-   Signature generation
-   Submission of Payment Page invocation requests
-   Processing callbacks
-   Acknowledgement of callbacks reception

You can either develop your own custom solution or use the components Ecommpay offer which include: JavaScript library, specialised SDK for numerous languages, and plug-ins for most popular CMS. The Ecommpay components make integration much easier and allow you to minimise or even eliminate the need for custom development.

The following table describes functionality supported by different components offered by Ecommpay.

| |JavaScript library|SDKs for web services|Mobile SDKs|CMS Plug-ins|
|--|------------------|---------------------|-----------|------------|
|Parameter collection|–|–|+|+|
|Signature generation|–|+|–|+|
|Submitting request|+|–|+|+|
|Processing callbacks|–|+|–|+|
|Callback acknowledgement|–|–|–|+|

The following section covers various aspects of setting up your web service by using custom solution or specialised components offered by Ecommpay.

### Using custom solutions {#section_rcw_r43_jlb .section}

If you choose to set up your web service interaction with Payment Page by using your own custom solution, you need to implement all the functionality both on the front end and back end of your web service.

1.  On the web service front end:
    -   Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.
    -   If you intend to open Payment Page in modal window or in an iframe, you need to add link to CSS stylesheet \([https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css)\) to your HTML page.

        **Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS library via the CDN \(Content Delivery Network\). Storing this library locally is not allowed.

        ```language-xml
        <head>
        ...
        <!-- Linking CSS stylesheet -->
        <link rel="stylesheet" href="[https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css)" />
        ...
        </head>
        ```

        This stylesheet is required for correct rendering of the payment form. If you choose to open Payment Page in a separate tab, you will not need to link this stylesheet.

    -   If you choose to open Payment Page in a modal window, you can define CSS styles to customise look and feel of your modal window to comply with your corporate design. If you choose to open Payment Page in an iframe or in a separate tab, you cannot customise design by using the CSS styles.

    -   Implement submission of collected data to the back end and implement accepting and processing responses from the back end.
    -   Implement invoking Payment Page by using the selected method: in a separate tab, in a modal window, or in an iframe.
    -   If you open Payment Page in a modal window or in an iframe, you can handle some events in by implementing the corresponding event handler functions. For more information, see [Handling events in Payment Page](en_pp_ui_monitoring.md).
2.  On the web service back end:
    -   Implement accepting and processing responses from the front end.
    -   Implement request signature generation.
    -   Implement submission of signed parameters set to the front end.
    -   Implement accepting—including signature verification and submission of acknowledgements—and processing callbacks from Payment Page.

### Configuring the Content Security Policy {#section_jth_vnh_qjc .section}

When working with the payment form, you are recommended to use available content security tools to mitigate the risk of Cross-Site Scripting \(XSS\) attacks and other cybersecurity threats. First and foremost, you need to configure Content Security Policy directives. A CSP allows you to restrict the origins of content such as scripts, frames, images and stylesheets that can be loaded on HTML pages of your website by specifying the domains that are permitted to provide those resources.

Content Security Policy directives are not relevant when the payment form is opened as a separate HTML page. However, they become an important security mechanism when the payment form is displayed in a modal window or an iframe element, or when specialised versions of Payment Page are used for Apple Pay, Google Pay, and card payments. Furthermore, if the Content Security Policy directives do not permit access to the required sources \(including, at least, the base URL for opening Payment Page\), the payment form may function incorrectly.

To configure Content Security Policy directives on the side of the web service, add the required directives to the `Content-Security-Policy` HTTP header.

``` {#codeblock_ejr_n4k_mjc}
Content-Security-Policy:
script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com;
style-src https://paymentpage.ecommpay.com;
img-src https://applepay.cdn-apple.com;
frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com
```

After configuring or modifying Content Security Policy directives, you should check that Payment Page functions correctly \(in the test environment, using a test project\). You are recommended to make sure that, at least, the following is true:

1.  No Content Security Policy related errors are reported in the browser console.
2.  The payment form functions correctly in all relevant web service integration scenarios.
3.  In case of Apple Pay payments, the processing scenario of a payment with this method is executed correctly \(which also means that all interface elements are displayed correctly\).

For assistance with Content Security Policy directives or other content security measures, contact the Ecommpay technical support.

### Using the JavaScript library {#section_wvv_kvj_jlb .section}

The JavaScript library is linked to your web service front end and allows you to open Payment Page in a modal window or in an iframe.The library also allows you to handle customer behaviour events on Payment Page. For more information, see [Handling events in Payment Page](en_pp_ui_monitoring.md).

When using the JavaScript library, you can develop your own custom solution or use web service SDK.You are required to make the following on the web service front end:

-   Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.
-   Add link to CSS stylesheet \([https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css)\) and the JavaScript library \([https://paymentpage.ecommpay.com/shared/merchant.js](https://paymentpage.ecommpay.com/shared/merchant.js)\) to your HTML page.

    **Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS and Javascript libraries via the CDN \(Content Delivery Network\). Storing these libraries locally is not allowed.

    ```language-xml
    <head>
    ...
    <!-- Linking CSS stylesheet -->
    <link rel="stylesheet" href="[https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css)" /> 
    <!-- Linking JavaScript library -->
    <script type="text/javascript" src="[https://paymentpage.ecommpay.com/shared/merchant.js](https://paymentpage.ecommpay.com/shared/merchant.js)">
    </script>
    ...
    </head>
    ```

-   If you choose to open Payment Page in a modal window, you can define CSS styles to customise look and feel of your modal window to comply with your corporate design. If you choose to open Payment Page in an iframe or in a separate tab, you cannot customise design by using the CSS styles.

-   Implement submission of collected data to the back end and implement accepting and processing responses from the back end.
-   Implement invoking Payment Page by clicking a button or command using the selected method: in a modal window and/or in an iframe. In this case, invocation is implemented through the EPayWidget JavaScript object.
-   If you open Payment Page in a modal window or in an iframe, you can handle some events in by implementing the corresponding event handler functions. For more information, see [Handling events in Payment Page](en_pp_ui_monitoring.md).

### Using web service SDKs {#section_jw3_lvj_jlb .section}

After you build these SDKs in your web service back end, you will be able to generate signatures for requests and process callbacks. When using web service SDK, you can develop your own custom solution and use mobile SDK andthe JavaScript library. You are required to make the following on the web service back end:

-   Implement accepting and processing responses from the front end.
-   Implement request signature generation by using the SDK libraries.
-   Implement submission of signed parameters set to the front end.
-   Implement accepting—including signature verification and submission of acknowledgements—and processing callbacks from Payment Page by using web service SDK.

For more information about linking and using this component in all available SDKs, see [Integration using SDK](en_sdk_overview.md).

### Using mobile SDKs {#section_osm_lvj_jlb .section}

The mobile SDK are build in mobile client apps and allow them to interact with the payment form adapted for mobile interfaces. When using mobile SDK, you can develop your own custom solution and use web service SDK. You are required to make the following on the web service front end:

-   Implement a web page for collecting data required to invoke the payment form. The minimum required data set includes project ID, payment ID, customer ID, and payment amount and currency.
-   Implement other functionality by using the SDK libraries.

For more information about linking and using all available SDKs, see [Integration using SDK](en_sdk_overview.md).

### Using CMS plug-ins {#section_ekc_lvj_jlb .section}

CMS plug-ins are linked by using administration interface of the corresponding CMS and provide the complete functionality for using Payment Page. If you choose to use a CMS plug-in, custom development is not required.

For information on how to use CMS plug-insfor web services for different CMS, see [Integration using plug-ins](en_CMS.md).

## Data formats {#en_PP_Formats}

### Overview {#section_hgq_qwb_wvb .section}

When working with Payment Page, as well as other interfaces of the Ecommpay payment platform, you should use only the permitted data encoding methods and formats.General information about them can be found in this article and [the Payment Page API specification](en_PP_Parameters.md). In addition, you can use the specialised [references](en_directory.md), descriptions of specific payment methods in the [corresponding section](en_pm_about.md), and articles about additional capabilities. Besides, you can contact the Ecommpay support specialists with any questions about data formats that arise.

### Data encoding {#section_kkg_kjl_bbb .section}

The generation of requests sent to the platform and the processing of responses and callbacks received from the platform must be carried out with the use of the UTF-8 encoding. In addition, in some cases you have to use other encoding methods, for example, Base64.Such cases are stipulated in this documentation, including [the specification](en_PP_Parameters.md) with parameters for opening the payment form.

### Dates and times {#section_db4_ckl_bbb .section}

In the scope of interaction with the platform, dates and times are usually represented in the `YYYY-MM-DDThh:mm:ss±hh:mm` format \(according to the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) requirements\), where `YYYY-MM-DD` is a date, `T` is a separating character, `hh:mm:ss` is time, `hh:mm` is a UTC \(Coordinated Universal Time\) offset. For example, `2025-05-25T15:30:25+00:00`.

Along with that, in some cases the date and time format can differ from the described one.Such cases are stipulated in this documentation, including [the specification](en_PP_Parameters.md) with parameters for opening the payment form.

### Amounts {#section_okf_xjl_bbb .section}

In the scope of interaction with the platform, payment and operation amounts are specified, as a rule, in the smallest units of currency and with no decimal separator. For example, 100 US dollars are represented in cents and specified as 10000 \(not as 100 or as 100.00\).The examples of other currencies representation are provided in the table.

|Currency|Amount|Representation|
|--------|------|--------------|
|EUR|39.95|`3995`|
|GBP|450.66|`45066`|
|JPY|200|`200`|
|KWD|150.155|`150155`|

The number of decimal digits for different currencies is defined according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard and provided [in the reference with currency codes](en_currency_codes.md).

### Currency, country, and language codes {#section_iq3_dkl_bbb .section}

In the scope of interaction with the Ecommpay payment platform, the following codes can be used:

-   three-letter *currency codes*—according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard
-   two-letter *country codes*—according to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) standard
-   single-, two-, and three-character *territory codes* \(such as states, provinces, and regions\)—according to the [ISO 3166-2](https://www.iso.org/iso-3166-country-codes.html) standard
-   *language codes*—containing two letters according to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard or another number of letters, which can be coordinated with the Ecommpay specialistsand used, for example, for opening the payment form with texts in a certain dialect of a language

These codes, except for territory codes and language codes which should be defined individually, can be found [in the references](en_directory.md).

## Request handling {#en_pp_interaction_requests_processing_scheme}

The interaction between your web service and Payment Page begins with issuing a request to open Payment Page to perform specific target action. After the payment platform receives a request, it does the following:

-   After the payment platform receives a request, it checks whether all the necessary parameters are available in the request and the signature is correct.
    -   If the request is correct, the request processing starts and the corresponding acknowledgement is sent out.
    -   If the payment platform encounters errors, the request handling is stopped and the corresponding error message is displayed to the customer. In this situation, no callback is submitted to the web service.
-   On the request processing stage, the payment platform prepares Payment Page in accordance with project settings and request parameters. Then, the Payment Page interacts with the customer through the payment form.
    -   If the customer confirms the target activity, the request moves to the processing stage. On this stage, the payment platform registers a paymentfor all target activities \(except for token generation\) by creating a `payment` object.
    -   If the customer does not confirm the target activity, the request is cancelled. No payment is registered and no callback is sent to the web service.
-   The request processing stage involves performing all the actions to obtain the target result.
    -   If the payment platform has successfully processed the request, it returns the result to the web service.
    -   If the payment platform has failed to process the request, it stops request handling and returns error result to the web service.

## Request format {#en_pp_interaction_request_format}

### Overview {#section_ivx_zr1_dmb .section}

When using Payment Page, you pass all data from web service in *requests* which are HTTP-messages with special structure. The data format and addressing differ depends on how you want to open the payment form.

This section describes supported methods for submitting requests to open Payment Page, data formats, and addressing.

### Submission methods {#section_ntk_zvx_jlb .section}

Both POST and GET methods are supported for all Payment Page invocation method. The payment in no way restricts invocation method and it is up to the web service to choose Payment Page invocation method. If an HTTP request does not specify request method it defaults to GET. Though, it is recommended to use POST method because of limitations imposed by some browsers on length of address string.

The main properties of POST and GET methods are presented in the following table.

| |POST|GET|
|--|----|---|
|Security|More secure because parameters are contained in request body|Less secure because parameters are included in URL string|
|Submission of all possible parameters supported by the Payment Page API|+|\*|
|Submission as a link|–|+|
|Request parameters modification in address string|–|+|

\*Data size is limited by URL length.

```
GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1
Host: https://paymentpage.ecommpay.com
```

```
POST /payment HTTP/1.1
Host: https://paymentpage.ecommpay.com

{
  "payment_currency": EUR,
  "project_id": 42,
  "payment_amount": 1000,
  "customer_id": 123,
  "payment_id": "4438",
  "signature": "AE5hmtzdP0Dt7qGTg..."
}  
```

### Addressing parameters {#section_jl5_zq1_dmb .section}

When you plan to open Payment Page in a new tab, the Payment Page URL is created as follows:

-   If you use the GET method, use Payment Page base URL as the domain name \(https://paymentpage.ecommpay.com\) while the relative URL consists the target URL, question sign \(?\) and parameter “name-value” pairs delimited by ampersand sign \(&\). Name and value in each “name-value” pair are separated by an equal sign \(=\).

    ```
    // Target URL for Payment Page
    /payment
    
    // Data string
    payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D
    
    // Complete URL
    https://paymentpage.ecommpay.com/payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D
    ```

-   If you use the POST method, use Payment Page base URL as the domain name \(https://paymentpage.ecommpay.com\) while the relative URL consists of the target URL used to initiate target activities in Payment Page. The parameters are located in request body.


You do not need to specify any URL when you open Payment Page in an iframe element or in a modal window.

## Response format {#en_pp_interaction_response_format}

Payment Page acknowledges receiving request by synchronously responding with appropriately structured HTTP response. The response may contain the following data:

-   The information that request is accepted for processing. The response is sent out only if the payment platform successfully accepts the request for processing.
-   An extended error description. The response is sent out, if the payment platform cannot handle the request.

The following table lists status codes along with their descriptions.

|Status code|Description|
|-----------|-----------|
|200 OK|The request has been successfully accepted. The response body has the requested result. You can expect callbacks with intermediate or final results.

 Payment form is displayed for the customer.

|
|400 Bad Request|The request cannot be accepted because one or more required parameters are missing from the request, for example project identifier, or signature is incorrect.

 Error message is displayed for the customer.

|
|404 Not Found|Cannot process request because of incorrect value of `project_id` or `urlBase`.

 Error message is displayed for the customer.

|
|500 Internal Error|Cannot process request because of payment platform failure.

 Error message is displayed for the customer.

|

## Callback format {#en_pp_interaction_callback_format}

In asynchronous interaction model, the Ecommpay payment platform returns callbacks with intermediate and final request processing results. From the technical point of view, callbacks are HTTP requests the payment platform sends by using POST method to the merchant web address. This section covers the structure of callbacks; for detailed information about using callbacks, see [Handling callbacks](en_platform_callbacks.md).

Each callback from the payment platform includes the following elements \(in this order\):

-   The start line which contains the following: the HTTP method which always is `POST`, the web service URL for callbacks with results \(for instance, `/notify/success`\), and the protocol and its version \(`HTTP/1.1`\).
-   The header fields including `Host` field that contains the domain name of the web service \(for instance, `webservice.com`\).
-   An empty separator line between the message header and the body.
-   The message body with JSON string in the UTF-8 format with result data and the signature.

Below you will find a sample callback with payment result. JSON string is formatted for better readability.

```language-json
POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "account":{
    "number":"431422******0056 ",
    "token":"1234567890",
    "type":"visa",
    "card_holder":"TEST TEST",
    "id":1234,
    "expiry_month":"**",
    "expiry_year":"****"
  },
  "customer":{
    "id":"12345",
    "phone":"***********"
  },
  "payment":{
    "date":"2019-06-07T11:38:31+0000",
    "id":"1234567890",
    "method":"card",
    "status":"success",
    "sum":{
      "amount":17500,
      "currency":"EUR"
    },
    "type":"purchase",
    "description":"Deposit to 1234567890"
  },
  "project_id":25,
  "processingDateTime":"2019-06-07T11:38:30+0000",
  "country":"GB",
  "product_name":"Visa",
  "issuer_name":"",
  "operation":{
    "id":1234567890,
    "type":"sale",
    "status":"success",
    "date":"2019-06-07T11:38:32+0000",
    "created_date":"2019-06-07T11:37:56+0000",
    "request_id":"1234567890-1234567890",
    "sum_initial":{
      "amount":17500,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":17500,
      "currency":"EUR"
    },
    "provider":{
      "id":11,
      "payment_id":"098765432",
      "date":"2019-06-07T11:38:30+0000",
      "auth_code":"",
      "endpoint_id":1
    },
    "code":"0",
    "message":"Success",
    "eci":"05"
  },
  "signature":"qwertyuioiuytrewqwertyuu123434"
}
```



---

# Integration using SDK {#en_sdk_overview}

Articles about using SDKs for integrating Payment Page in mobile applications and for data signing.

## SDKs for mobile applications {#section_okr_hxv_tvb .section}

You can use specialised software development kits \(SDKs\) to accept in-app payments for processing via the Ecommpay payment platformwithout redirection to mobile browsers to open the payment form. These SDKs provide you with the functionality that allows exchanging all necessary data between the application client and the payment platform. They also allow you to utilise different user interfaces: SDK UI & Core includes interface components developed by Ecommpay while SDK Core allows you to use your in-house interface components.

At present, the following versions of the mobile SDKs are available:

| |![](images/universal/pr_lang_logos/android.svg)|![](images/universal/pr_lang_logos/apple.svg)|
|--|-----------------------------------------------|---------------------------------------------|
|**UI & Core**  
 with the user interface by Ecommpay

|  
 for Android 5.0 and later

 -   [native SDK](en_sdk_ui_and_core_android.md)
-   [SDK for Flutter 3.3.0 and later](en_sdk_flutter.md)
-   [SDK for React Native 0.75.3 and later](en_sdk_react_native.md)

|  
 for iOS 15.6 and later  


 -   [native SDK](en_sdk_ui_and_core_ios.md)
-   [SDK for Flutter 3.3.0 and later](en_sdk_flutter.md)
-   [SDK for React Native 0.75.3 and later](en_sdk_react_native.md)

|
|**Core**  
 when you use your in-house user interface

|  
 [for Android 5.0 and later](en_sdk_core_android.md)

|  
 [for iOS 11.0 and later](en_sdk_core_ios.md)

|

If you have any questions regarding the specifics of working with the mobile SDKs or suggestions as to how their functionality can be expanded and enhanced, contact your Ecommpay account manager. With questions about the integration, testing, and use of these SDKs, contact the technical support.

## SDKs for data signing {#section_vcj_5zv_tvb .section}

You can use specialised software development kits \(SDKs\) to work with digital signatures essential for program interaction with the Ecommpay payment platform. These SDKs allow you to sign data sets included in requests and verify the correctness of signatures in responses and callbacks sent by the platform \(to learn more about these algorithms, see [Signature generation and verification](en_platform_signature.md)\). Implementing such SDKs implies using the secret signing keys provided by Ecommpay specifically for each project. Therefore, SDKs for data signing should be used on the server side of web services with proper security measures taken.

At present, the following language-specific SDKs are available for data signing:

-   [C\#](en_sdk_net.md) using .NET 6.0 and later
-   [Go](en_sdk_go.md) 1.8 and later
-   [Java](en_sdk_java.md) using JDK 8 and later
-   [JavaScript](en_sdk_javascript.md) using Node.js 4.x
-   [PHP](en_sdk_php.md) 7.0 and later
-   [Python](en_sdk_python.md) 3.5 and later

If you have any questions regarding the specifics of working with the SDKs for data signing or suggestions as to how their functionality can be expanded and enhanced, contact your Ecommpay account manager. With questions about the integration, testing, and use of these SDKs, contact the technical support.

-   **[SDK UI & Core for Android](en_sdk_ui_and_core_android.md)**  
An article about using SDK UI & Core for integrating a payment form with the interface from Ecommpay in Android mobile applications.
-   **[SDK UI & Core for iOS](en_sdk_ui_and_core_ios.md)**  
An article about using SDK UI & Core for integrating a payment form with the interface from Ecommpay in iOS mobile applications.
-   **[SDK Flutter for Android and iOS](en_sdk_flutter.md)**  
An article about using SDK Flutter for integrating a payment form in Android and iOS mobile applications.
-   **[SDK React Native for Android and iOS](en_sdk_react_native.md)**  
An article about using SDK React for integrating a payment form in Android and iOS mobile applications.
-   **[SDK Core for Android](en_sdk_core_android.md)**  
An article about using SDK Core for integrating a payment form with the option to use the in-house interface in Android mobile applications.
-   **[SDK Core for iOS](en_sdk_core_ios.md)**  
An article about using SDK Core for integrating a payment form with the option to use the in-house interface in iOS mobile applications.
-   **[SDK for C\# on the .NET platform](en_sdk_net.md)**  
An article about using data signing SDKs for web services developed in C\# for .NET.
-   **[SDK for Go](en_sdk_go.md)**  
An article about using data signing SDKs for web services developed in Go.
-   **[SDK for Java](en_sdk_java.md)**  
An article about using data signing SDKs for web services developed in Java.
-   **[SDK for JavaScript](en_sdk_javascript.md)**  
An article about using data signing SDKs for web services developed in JavaScript.
-   **[SDK for PHP](en_sdk_php.md)**  
An article about using data signing SDKs for web services developed in PHP.
-   **[SDK for Python](en_sdk_python.md)**  
An article about using data signing SDKs for web services developed in Python.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# SDK UI & Core for Android {#en_sdk_ui_and_core_android}

An article about using SDK UI & Core for integrating a payment form with the interface from Ecommpay in Android mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_ui_and_core_android_overview}

### Introduction {#section_v2d_jwf_jvb .section}

Mobile SDK UI & Core for Android is a software development kit with open-source code that can be used to integrate Android applications with the Ecommpay payment platform.

SDK UI & Core for Android provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the payment platform which allows sending and receiving necessary information during payment processing. Additionally, the open-source code available with SDK UI & Core for Android provides flexibility for configuring the user interface in accordance with the aspects of the application.

SDK UI & Core for Android can be embedded in mobile applications developed for Android version 5.0 or later. The libraries and code examples are available on GitHub. To access, use the following URLs:

-   List of SDK UI & Core for Android releases: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases)
-   Code examples: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example)

### Capabilities {#section_llb_nwf_jvb .section}

The following functional capabilities are supported by SDK UI & Core for Android:

-   Processing different types of paymentsmade with cards and Google Pay as well as other payment methods available for the merchant's project. Supported payment types include:

    -   One-time one-step purchases.
    -   One-time two-step purchases \(an authorisation hold can be placed via the SDK and subsequent debiting of the authorised amount is carried out via Gate or Dashboard\).
    -   COF purchases \(they can be registered via the SDK and then managed via Gate or Dashboard\).
    **Note:** In case of card and Google Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

-   Performing payment card verification \(it involves debiting a zero amount from the customer's card\).
-   Checking current payment information.
-   Auxiliary procedures and additional capabilities to boost payment acceptance rates:
    -   Submission of additional payment information.
    -   Payment retries.
    -   Cascade payment processing.
    -   Collecting customer data.
-   Additional capabilities to improve user experience:
    -   Saving customer payment data.
    -   Payment interface language support.
    -   Sending email notifications with the list of purchased items to customers.
-   Customising the appearance of the payment interface including the colour scheme settings and the option to add the logo.

### Workflow {#section_p4h_qwf_jvb .section}

Generally, the following workflow is relevant when one-step purchases are processed with the use of SDK UI & Core for Android.

![](images/sdk/android/en_sdk_ui_core_functional.svg)

1.  In the user interface of a mobile application, the customer initiates a purchase by clicking the payment button or in a different fashion set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK UI & Core for Android, this set is converted into a string for signing, and the string is sent to the server side of the merchant web service.
3.  On the server side of the merchant web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK UI & Core for Android.
4.  With the help of SDK UI & Core for Android, a payment session is initiated in the payment platform.
5.  On the payment platform side, the payment interface is prepared in accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
6.  In the mobile application, the payment form is displayed to the customer.
7.  The customerselects a payment method \(if no method was selected when the payment session was initiated\), specifies the necessary information, and confirms the purchase.
8.  SDK UI & Core for Android sends a purchase request to the payment platform.
9.  On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to theproviders and payment systems.
10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
12. The information about the purchase result is sent from the payment platform to SDK UI & Core for Android.
13. The notification with the result information is displayed to the customer in the user interface.

### Interface {#section_t4h_qwf_jvb .section}

Whencardand Google Pay payments are processed, the customer interacts with the user interface designed by the Ecommpay specialists. This user interface can be customised: you can change its colour and add your company's logo.

![](images/sdk/android/all_sdk_ui_core_design_color.svg "Customisation options")

![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Page to enter payment details")

![](images/sdk/android/all_sdk_ui_core_design_result.png "Payment result page")

## Setup {#en_sdk_ui_and_core_android_setup}

### Integration steps {#section_v5c_zwf_jvb .section}

To integrate the web service with the Ecommpay payment platform by using SDK UI & Core for Android:

1.  Address the following organisational issues of interaction with Ecommpay:
    1.  If your company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If your company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK UI & Core for Android and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical steps:
    1.  Download and link the SDK UI & Core for Android libraries.
    2.  Ensure the collection of data necessary for opening the payment form. The minimum data set needed in order to open the payment form consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notifications from SDK UI & Core for Android as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  With the technical support specialists, coordinate the timeline and the main steps of integrating, testing\(including testing available payment methods\), and launching the solution.
    1.  For testing, use the test project identifier and the details of [test cards](en_test_cards.md).
    2.  For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from Ecommpay.

If you have any questions about working with SDK UI & Core for Android, contact the Ecommpay technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Libraries installation {#section_sx3_fxf_jvb .section}

For the mobile applications developed for Android version 5.0 or later, linking the SDK UI & Core for Android libraries via MavenCentral is supported. To link the libraries:

1.  Open the `build.gradle.kts` module in the application.
2.  Specify the `mavenCentral` repository in the `repositories` section:

    ```language-json
    allprojects {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```

3.  Add the following code in the `dependencies` section:

    ```language-json
    implementation "com.ecommpay:msdk-ui:LATEST\_VERSION"
    ```


### Signature generation {#section_odg_jxf_jvb .section}

Make sure that the data is signed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services \([details](en_sdk_overview.md)\), or your own in-house solutions. The procedure of working with the signature is described in [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_ui_and_core_android_testing}

Before you start processing real payments via SDK UI & Core for Android, it is recommended that you test payment processing in the test project. You can obtain the identifier and the secret key of the test project when accessing the Ecommpay test environment\(this can be done via [an application](https://ecommpay.com/sign-up/) on the company's main site\). Along with that, upon the coordination with the Ecommpay specialists, it is possible to test the use of the Google Pay method andadditional capabilities, such as cascade payment processing and collection of customer data.

To test payment processing:

1.  Open the `build.gradle.kts` module in the application.
2.  Specify the test project identifier \(`projectId`\) and the secret key of the given project \(`projectSecretKey`\).
3.  Run the `gradle` synchronisation process.

To switch to the production mode, change the test values \(the identifier and the secret key of the test project\) to the production ones.

## Use {#en_sdk_ui_and_core_android_use}

### Opening payment form {#en_sdk_ui_and_core_android_openingpf}

SDK UI & Core for Android supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the `EcmpPaymentInfo` object while other parameters can be passed in the `EcmpPaymentOptions` object, requested from the customer, or received from the payment platform.

To open the payment form:

1.  Create the `EcmpPaymentInfo` object.

    -   This object must contain the following required parameters:
        -   `projectId` \(integer\)—a project identifier assigned by Ecommpay
        -   `paymentId` \(string\)—a payment identifier unique within the project
        -   `paymentCurrency` \(string\)—the payment currency code in the ISO 4217 alpha-3 format
        -   `paymentAmount` \(integer\)—the payment amount in the smallest currency unit
        -   `customerId` \(string\)—a customer's identifier within the project
        -   `signature` \(string\)—a request signature generated after all required parameters have been specified
    -   You can also add any other parameters listed [in the following table](en_sdk_ui_and_core_android.md#table_dvh_ngf_jvb).
    ```language-json
    val ecmpPaymentInfo = EcmpPaymentInfo(
            projectId = 77655,
            paymentId = payment_322,
            paymentAmount = 100,
            paymentCurrency = "USD",
            paymentDescription = "Cosmoshop payment", 
            customerId = "customer_003",
            regionCode = "DE",           //Code of the customer's country
            token = "o8i7u65y4t3rkjhgfdw3456789oikjhgfdfghjkl...", //Token associated with certain payment data
            languageCode = "de",         //Payment interface language code
            receiptData = "eyAKICAicG9zaXRpb25zIjpbIAogICAgIIjoxLAogICAgICAgICJhbW91bnQiOjU5OTAsCiAgQ==",
            //Data to be included in the notification with the list of the purchased items
            hideSavedWallets = false,    //Parameter to enable hiding or displaying saved payment instruments
            forcePaymentMethod = card    //Identifier of the preselected payment method
       )
    ```

2.  Sign the parameters contained in the `EcmpPaymentInfo` object.

    ```language-json
    ecmpPaymentInfo.signature = SignatureGenerator.generateSignature(
            paramsToSign = ecmpPaymentInfo.getParamsForSignature(),
            secret = SECRET_KEY
       )
    ```

3.  Create the `EcmpPaymentOptions` object.

    -   This object must contain the following parameters:
        -   For all payments—the `actionType` parameter with the value specifying the required operation type: `Sale`, `Auth`, or `Verify`.
        -   For card payments—the `CUSTOMER_EMAIL` or the `CUSTOMER_PHONE` parameter embedded in the `additionalFields` object \(at least one of the two\) to display the corresponding fields to the customer on the payment form.
    -   For 3‑D Secure it is recommended that you specify the customer's billing address information:

        -   `BILLING_COUNTRY`—the country of the customer's billing address in the ISO 3166-1 alpha-2 format \([details](en_country_codes.md)\)
        -   `BILLING_POSTAL`—the postal code of the customer's billing address
        -   `BILLING_CITY`—the city of the customer's billing address
        -   `BILLING_ADDRESS`—the street of the customer's billing address
        These parameters are passed in the `additionalFields` object and the corresponding fields are displayed to the customer on the payment form.

        **Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

    -   You can also add any other objects and parameters listed [in the following table](en_sdk_ui_and_core_android.md#table_lgv_bmf_jvb).
    In addition to the required `EcmpPaymentInfo` object and the `actionType` parameter, the following example contains the `CUSTOMER_EMAIL` parameter required for card payments and several additional parameters including the ones listed in the `additionalFields` object.

    ```language-json
    val paymentOptions = paymentOptions {
            paymentInfo = ecmpPaymentInfo
            actionType = EcmpActionType.Sale
            brandColor = "#800008"
            isDarkTheme = false
            logoImage = BitmapFactory.decodeResource(resources, R.drawable.example_logo)
            hideScanningCards = false 
            isTestEnvironment = true
            merchantId = BuildConfig.GPAY_MERCHANT_ID
            merchantName = "Example Merchant Name"
            screenDisplayModes {
              mode(EcmpScreenDisplayMode.HIDE_DECLINE_FINAL_SCREEN)
              mode(EcmpScreenDisplayMode.HIDE_SUCCESS_FINAL_SCREEN)
            }
            additionalFields {
              field {
                type = EcmpAdditionalFieldType.CUSTOMER_EMAIL
                value = "mail@mail.com"
              }
              field {
                type = EcmpAdditionalFieldType.CUSTOMER_FIRST_NAME
                value = "firstName"
              }
            }
    }
    ```

4.  Create the `EcmpPaymentSDK` object.

    ```language-json
    val sdk = EcmpPaymentSDK(
            context = applicationContext,
            paymentOptions = paymentOptions,
            )
    ```

    If necessary, you can open the payment form in the test mode in order to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. In the `EcmpPaymentSDK` object, specify the `EcmpPaymentSDK.EcmpMockModeType.SUCCESS` value for the `mockModeType` parameter \(if you need to receive `Success` payment result\). You can also pass values `EcmpPaymentSDK.EcmpMockModeType.DECLINE` \(if you need to receive `Decline` payment result\) and `EcmpPaymentSDK.EcmpMockModeType.DISABLED` \(if you need to switch to the production mode\).

5.  Open the payment form.

    ```language-json
    sdk.openPaymentScreen(this, 1234)
    ```


### Processing payments {#en_sdk_ui_and_core_android_payments}

By default, SDK UI and Core for Android allows processing one-step purchases \(action type `Sale`\). This type of checkout works right out-of-the-box and requires no additional setup.

In addition, SDK UI and Core for Android supports processing two-step purchases \(which involves placing an authorisation hold via the SDK and subsequent debiting of the authorised amount\). To perform a two-step purchase:

1.  Open the payment form with `EcmpActionType.Auth` specified as a value for the action type parameter in the `paymentOptions` object:

    ```language-java
    (EcmpPaymentOptions.EcmpActionType.Auth);
    ```

2.  When needed, initiate debiting of the authorised amount via Dashboard \([details](en_dbl_payments.md)\) or Gate \(by sending the request to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint\).

### Payment card verification {#en_sdk_ui_and_core_android_verify}

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly \(for example, before performing a payout\) or when you need to save card details for subsequent use. It is essentially a payment that involves debiting a dummy \(zero\) amount from the customer's card.

To perform verification, open the payment form with `EcmpActionType.Verify` specified as a value for the action type parameter in the `paymentOptions` object:

```language-java
(EcmpPaymentOptions.EcmpActionType.Verify);
```

### Payment status information {#en_sdk_ui_and_core_android_status}

To receive payment result notifications, use the `onActivityResult` method.

```language-json
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
 
        when (resultCode) {
            EcmpPaymentSDK.RESULT_SUCCESS -> {
                Toast.makeText(this, "Payment was finished successfully", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was finished successfully")
            }
            EcmpPaymentSDK.RESULT_CANCELLED -> {
                Toast.makeText(this, "Payment was cancelled", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was cancelled")
            }
            EcmpPaymentSDK.RESULT_DECLINE -> {
                Toast.makeText(this, "Payment was declined", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was declined")
            }
            EcmpPaymentSDK.RESULT_ERROR -> {
                val errorCode = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_CODE)
                val message = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_MESSAGE)
                Toast.makeText(this, "Payment was interrupted. See logs", Toast.LENGTH_SHORT).show()
                Log.d(
                    "PaymentSDK",
                    "Payment was interrupted. Error code: $errorCode. Message: $message"
                )
            }
        }
    }
```

Possible payment result codes:

-   `RESULT_SUCCESS`—payment has been completed.
-   `RESULT_CANCELLED`—payment has been cancelled.
-   `RESULT_DECLINE`—payment has been denied.
-   `RESULT_ERROR`—error occurred when the payment was being processed.

### Additional capabilities {#en_sdk_ui_and_core_android_additional_capabilities}

#### Submitting additional payment information {#section_s5t_2yf_jvb .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, in some cases, a payment system or a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided in [the following article](en_pp_clarification.md).

The final set of required parameters can vary depending on a specificprovider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form. The customer fills in the required data, confirms the payment, and receives the payment result information.

#### Cascade payment processing {#section_gq3_cyf_jvb .section}

In case of a payment attempt failure, the capability of cascade payment processing can be used \([details](en_pp_cascading.md)\). This capabilityimplies executing a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the Ecommpay specialists.

If this capability is set up for the project in use, then after the first unsuccessful attempt, a notification is received from SDK UI & Core for Android. This notification contains the `cascading_with_redirect = true` attribute-value pair. Along with that, the error page with the button to retry making the payment is shown to the customer. If the 3‑D Secure authentication is not required as part of the additional attempt, then the attempt is executed without any further interaction with the customer. Otherwise, a separate page opens for repeating the authentication process.

#### Collecting customer data {#section_mc3_gyf_jvb .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones \(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant should decide which data has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see [the separate article](en_PP_Gathering_customer_data.md).

#### Payment interface language support {#section_uhh_k3t_xyb .section}

By default, during the work with SDK UI & Core, the payment interface is localised according either to the language of the customer's device—if this language is supported for the project in use—or to a language set as default for other cases \(generally, English\). Along with that, if relevant, you can localise the payment interface for particular sessions. For this, every request for opening the payment form must contain a corresponding language code in the `languageCode` \([details](en_sdk_ui_and_core_android.md)\).

**Warning:** If the language is not supported for the project, the payment form is not opened and the error information is displayed to the customer.

The following languages are supported for the SDK interface and can be promptly set up in the projects of the payment platform.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

#### Saving payment data {#section_cch_1yf_jvb .section}

SDK UI & Core for Android allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project. The merchant has to let the technical support know which of the two options is preferable: *always save payment data* or *ask the customer to select the option*. For more information about this capability, refer to article [Saving customer payment data](en_PP_saved_data.md).

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer \(`customerId`\). To display saved payment data to the customer, pass `false` in the `hideSavedWallets` parameter of the `EcmpPaymentOptions` object.

## Payment form opening parameters {#en_sdk_ui_and_core_android_parameters}

When working with SDK UI & Core for Android, you can pass the following optional parameters in the `EcmpPaymentInfo` object.

|Parameter|Description|
|:--------|:----------|
|`paymentDescription`  
 string

|Description of the payment. A string that contains between 1 and 255 characters.

 Example: `Cosmoshop purchase`

|
|`receiptData`  
 string

|Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

 Example: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`

|
|`token`  
 string

|Token associated with certain payment data. A string that contains between 1 and 255 characters.

 Example: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c`

|
|`hideSavedWallets`  
 boolean

|Parameter to enable hiding or displaying saved payment instruments in the payment form.

 Possible values:

 -   `true`—saved payment data is hidden
-   `false`—saved payment data is displayed.

|
|`forcePaymentMethod`  
 string

|The identifier of the preselected payment method according to [the table](en_pm_codes.md).

 Example: `card`

|
|`ecmpThreeDSecureInfo`  
 object

|Object that contains additional objects and parameters necessary for the 3‑D Secure 2 authentication.|
|`languageCode`  
 string

|Payment interface language code in the ISO 639-1 alpha-2 format. Must match one of the languages supported for the given project.

 Example: `EN`

|
|`regionCode`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|

You can pass the following optional parameters in the `EcmpPaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`merchantID`  
 string

|The Google Pay identifier of the merchant.|
|`merchantName`  
 string

|The Google Pay name of the merchant.|
|`logoImage`  
 bitmap

|A bitmap file that contains the logo of the merchant.|
|`brandColor`  
 string

|Payment interface colour in hexadecimal format.

 Example: `#800080`

|
|`isTestEnvironment`  
 boolean

|Parameter to indicate a test payment.

 Possible values:

 -   `true`
-   `false`

|
|`additionalFields`  
 list

|Additional fields that contain information about the customer.

 Example: `EcmpAdditionalField(EcmpAdditionalFieldType.CUSTOMER_EMAIL,"mail@mail.com")`

|
|`recipientInfo`  
 object—object with information about the recipient of the payment.

|
|`pan`  
 string

|Card number.

 Example: `5413330000000019`

|
|`card_holder`  
 string

|First and last name \(as specified on the card\).

 Example: `Arthur Eddington`

|
|`wallet_id`  
 string

|Number of the wallet.

 Example: `WID2812188222111944`

|
|`wallet_owner`  
 string

|First and last name of the recipient.

 Example: `Arthur Eddington`

|
|`country`  
 string

|Code of the recipient's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|
|`address`  
 string

|Recipient's address.

 Example: `42 Walliscote Road`

|
|`city`  
 string

|Recipient's city of residence.

 Example: `Weston-super-Mare`

|
|`state`  
 string

|Recipient's state.

 Example: `GB`

|

To work with COF purchases, you should pass relevant parameters in the `recurrentData` object of the `EcmpPaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`type`  
 string

|Type of the COF purchase to register.Possible values:

-   `C`—OneClick
-   `U`—autopurchase
-   `R`—regular purchase

|
|`period`  
 string

|Frequency of debits \(for a regular COF purchase\).

 Possible values:

 -   `D`—daily
-   `W`—weekly
-   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
-   `Q`—quarterly
-   `Y`—yearly

|
|`expiry_day`  
 string

|Calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiry_month`  
 string

|Month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiry_year`  
 integer

|Year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).|
|`scheduled_payment_id`  
 string

|Identifier assigned to the payment within which scheduled debits are performed \(for automatic debiting\). It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

 Parameter must be passed together with the `start_date` parameter.

|
|`start_date`  
 string

|Date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.|
|`time`  
 string

|Time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.|
|`schedule`  
 object—schedule of debits performed as part of the COF purchase \(can be specified by the merchant\). Should contain parameters `amount` and `date`.

|
|`amount`  
 integer

|The amount to debit in the smallest currency unit.|
|`date`  
 string

|Date to perform the debit in the `DD-MM-YYYY` format.|

**Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

-   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
-   For other available methods—the corresponding parameter value is determined as follows:
    -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
    -   Month—the month in which the COF purchase was registered.
    -   Year—the year that is 10 years after the year in which the COF purchase was registered.

Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

You can pass the following optional parameters in the `ecmpThreeDSecureInfo` object. Including these parameters increases the possibility of frictionless flow selection.

|Parameter|Description|
|:--------|:----------|
|`threeDSecureInfo`—object of the `ECMPThreeDSecureInfo` class containing additional objects and parameters used during the 3‑D Secure 2 authentication|
|`threeDSecurePaymentInfo`—object of the `ECMPThreeDSecurePaymentInfo` class with information about the purchase details and indication of the preferable authentication flow|
|`challengeIndicator`  
 string

|This parameter indicates whether challenge flow is requested for this payment.

 Possible values:

-   `01`—no preferences
-   `02`—it is preferable not to use challenge flow
-   `03`—challenge flow preferred
-   `04`—always use challenge flow

|
|`challengeWindow`  
 string

|The dimensions of a window in which authentication page opens.

 Possible values:

-   `01`—250 x 400 px
-   `02`—390 x 400 px
-   `03`—500 x 600 px
-   `04`—600 x 400 px
-   `05`—full screen

|
|`preorderDate`  
 string

|The date the preordered merchandise will be available.

 Format: *dd-mm-yyyy*.

|
|`preorderPurchase`  
 string

|This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date.

 Possible values:

-   `01`—merchandise available in stock
-   `02`—future merchandise availability

|
|`reorder`  
 string

|This parameter indicates whether the cardholder is reordering previously purchased merchandise.

 Possible values:

-   `01`—first time order
-   `02`—reorder

|
|`threeDSecureGiftCardInfo`—object of the `ECMPThreeDSecureGiftCardInfo` class with information about payment with prepaid card or gift card.|
|`amount`  
 integer

|Amount of the payment with prepaid or gift card denominated in the smallest currency unit.|
|`currency`  
 string

|Currency code of the payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example [GBP](references/en/currencies/GBP.md).|
|`count`  
 integer

|Total number of individual prepaid or gift cards/codes used in purchase.|
|`threeDSecureCustomerInfo`—object of the `ECMPThreeDSecureCustomerInfo` class with information about the customer.|
|`addressMatch`  
 string

|The parameter indicates whether the customer billing address matches the address specified in the `threeDSecureShippingInfo` object.

 Possible values:

-   `Y`—Shipping Address matches Billing Address
-   `N`—Shipping Address does not match Billing Address

|
|`billingRegionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.|
|`homePhone`  
 string

|Customer home phone number.

 Numeric, from 4 to 24 characters. Example: `44991234567`.

|
|`workPhone`  
 string

|Customer work phone number.

 Numeric, from 4 to 24 characters. Example `44997654321`.

|
|`threeDSecureAccountInfo`—object of the `ECMPThreeDSecureAccountInfo` class with information about customer account details on record with the web service|
|`additional`  
 string

|Additional customer account information, for instance arbitrary customer ID.

 Maximum 64 characters.

|
|`activityDay`  
 integer

|Number of card payment attempts in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`activityYear`  
 integer

|Number of card payment attempts in the last 365 days.Maximum 3 characters \(`999`\).

|
|`ageIndicator`  
 string

|Number of days since the customer account was created.

 Possible values:

-   `01`—guest check-out
-   `02`—customer account was created in this transaction
-   `03`—customer account was created less than 30 days ago
-   `04`—customer account was created 30 to 60 days ago
-   `05`—customer account was created over 60 days ago

|
|`authData`  
 string

|Any additional log in information in free text.

 Maximum 255 characters.

|
|`authMethod`  
 string

|Authentication type the customer used to log on to the account when placing the order.

 Possible values:

-   `01`—no authentication
-   `02`—log on by using authentication data on file with merchant
-   `03`—log on by using federated ID \(for example, Google Account or Facebook\)
-   `04`—log on by using a FIDO authenticator \(Fast IDentity Online\)

|
|`authTime`  
 string

|Account log on date and time.

 Format: *dd-mm-yyyyhh:mm*.

|
|`date`  
 string

|Account creation date.

 Format: *dd-mm-yyyy*.

|
|`changeDate`  
 string

|Last account change date except for password change or password reset.

 Format: *dd-mm-yyyy*.

|
|`changeIndicator`  
 string

|Number of days since last customer account update, not including password change or reset.

 Possible values:

-   `01`—updated in this transaction
-   `02`—updated less than 30 days ago
-   `03`—updated 30−60 days ago
-   `04`—updated over 60 days ago

|
|`passChangeDate`  
 string

|Last password change or password reset date.

 Format: *dd-mm-yyyy*.

|
|`passChangeIndicator`  
 string

|Number of days since the last password change or reset.

Possible values:-   `01`—password never changed
-   `02`—changed in this transaction
-   `03`—changed less than 30 days ago
-   `04`—changed 30−60 days ago
-   `05`—changed over 60 days ago

|
|`paymentAge`  
 string

|Card record creation date.

 Format: *dd-mm-yyyy*.

|
|`paymentAgeIndicator`  
 string

|Number of days since the payment card details were saved in a customer account.

 Possible values:

-   `01`—current payment uses no customer account \(guest checkout\)
-   `02`—card details were saved today
-   `03`—card details were saved less than 30 days ago
-   `04`—card details were saved 30 to 60 days ago
-   `05`—card details were saved more than 60 days ago

|
|`provisionAttempts`  
 integer

|Number of attempts to add card details in customer account in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`purchaseNumber`  
 integer

|Number of purchases with this cardholder account in the previous six months.Maximum 4 characters \(`9999`\).

|
|`suspiciousActivity`  
 string

|Suspicious activity detection result.

 Possible values:

-   `01`—no suspicious activity detected
-   `02`—suspicious activity detected

|
|`threeDSecureShippingInfo`—object of the `ECMPThreeDSecureShippingInfo` class with shipping details.|
|`address`  
 string

|Shipping address.

 Maximum 150 characters.

|
|`addressUsage`  
 string

|First shipping address usage date.Format: *dd-mm-yyyy*.

|
|`addressUsageIndicator`  
 string

|Number of days since the first time usage of the shipping address.

 Possible values:

-   `01`—this transaction
-   `02`—less than 30 days ago
-   `03`—30−60 days ago
-   `04`—more than 60 days ago

|
|`city`  
 string

|Shipping city.

 Maximum 50 characters.

|
|`country`  
 string

|Shipping country in the ISO 3166-1 alpha-2 format, for example [GB](references/en/countries/GB.md).|
|`deliveryEmail`  
 string

|The email for the digital content delivery.

 Maximum 255 characters.

|
|`deliveryTime`  
 string

|Shipment terms.

Possible values:-   `01`—digital delivery
-   `02`—same-day delivery
-   `03`—overnight delivery
-   `04`—longer than overnight delivery

|
|`nameIndicator`  
 string

|Shipment recipient flag.

 Possible values:

-   `01`—customer and shipment recipient are the same person
-   `02`—customer and shipment recipient are different persons

|
|`postal`  
 string

|Shipping postbox number.

 Maximum 16 characters.

|
|`regionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.

 If you specify this parameter, you need also to specify and populate the `country` parameter in the `threeDSecureShippingInfo` object.

|
|`type`  
 string

|Shipment indicator.

 Possible values:

-   `01`—ship to cardholder billing address
-   `02`—ship to another verified address on file with merchant
-   `03`—ship to address that is different from the cardholder billing address or any verified address on file with merchant
-   `04`—ship to local store
-   `05`—digital goods shipment
-   `06`—no shipment, for instance for travel or event tickets
-   `07`—other, for example gaming or subscriptions

|
|`threeDSecureMpiResultInfo`—object of the `ECMPThreeDSecureMpiResultInfo` class with information about previous customer authentication|
|`acsOperationId`  
 string

|The ID the issuer assigned to the previous customer operation. Maximum 36 characters.|
|`authenticationFlow`  
 string

|The flow the issuer used to authenticate the cardholder in the previous operation.

 Possible values:

-   `01`—frictionless flow
-   `02`—challenge flow

|
|`authenticationTimestamp`  
 string

|Date and time of the previous successful customer authentication|



---

# SDK UI & Core for iOS {#en_sdk_ui_and_core_ios}

An article about using SDK UI & Core for integrating a payment form with the interface from Ecommpay in iOS mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_ui_and_core_ios_overview}

### Introduction {#section_lvb_4bk_lvb .section}

Mobile SDK UI & Core for iOS is a software development kit with open-source code that can be used to integrate iOS applications with the Ecommpay payment platform.

SDK UI & Core for iOS provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the payment platform which allows sending and receiving necessary information during payment processing. Additionally, the open-source code available with SDK UI & Core for iOS provides flexibility for configuring the user interface in accordance with the aspects of the application.

SDK UI & Core for iOS can be embedded in mobile applications developed for iOS version 15.6 or later. The libraries and code examples are available on GitHub. To access, use the following URLs:

-   List of SDK UI & Core for iOS releases: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases)
-   Code examples: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples)

This article describes how to work with SDK UI & Core for iOS and provides code examples in Swift and Objective-C.

### Capabilities {#section_gmj_bw1_nvb .section}

The following functional capabilities are supported by SDK UI & Core for iOS:

-   Processing different types of paymentsmade with cards and Apple Pay as well as other payment methods available for the merchant's project. Supported payment types include:

    -   One-time one-step purchases.
    -   One-time two-step purchases \(an authorisation hold can be placed via the SDK and subsequent debiting of the authorised amount is carried out via Gate or Dashboard\).
    -   COF purchases \(they can be registered via the SDK and then managed via Gate or Dashboard\).
    **Note:** In case of card and Apple Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

-   Performing payment card verification \(it involves debiting a zero amount from the customer's card\).
-   Checking current payment information.
-   Auxiliary procedures and additional capabilities to boost payment acceptance rates:
    -   Submission of additional payment information.
    -   Payment retries.
    -   Cascade payment processing.
    -   Collecting customer data.
-   Additional capabilities to improve user experience:
    -   Saving customer payment data.
    -   Payment interface language support.
    -   Sending email notifications with the list of purchased items to customers.
-   Customising the appearance of the payment interface including the colour scheme settings and the option to add the logo.

### Workflow {#section_fzd_1dk_lvb .section}

Generally, the following workflow is relevant when purchases are processed with the use of SDK UI & Core for iOS.

![](images/sdk/ios/en_sdk_ui_core_functional_ios.svg)

1.  In the user interface of a mobile application, the customer initiates a purchase by clicking the payment button or in a different fashion set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK UI & Core for iOS, this set is converted into a string for signing, and the string is sent to the server side of the merchant web service.
3.  On the server side of the merchant web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK UI & Core for iOS.
4.  With the help of SDK UI & Core for iOS, a payment session is initiated in the payment platform.
5.  On the payment platform side, the payment interface is prepared in accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
6.  In the mobile application, the payment form is displayed to the customer.
7.  The customerselects a payment method \(if no method was selected when the payment session was initiated\), specifies the necessary information, and confirms the purchase.
8.  SDK UI & Core for iOS sends a purchase request to the payment platform.
9.  On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to theproviders and payment systems.
10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
12. The information about the purchase result is sent from the payment platform to SDK UI & Core for iOS.
13. The notification with the result information is displayed to the customer in the user interface.

### Interface {#section_aqm_ldk_lvb .section}

Whencard and Apple Pay payments are processed, the customer interacts with the user interface designed by the Ecommpay specialists. This user interface can be customised: you can change its colour and add your company's logo.

![](images/sdk/ios/all_sdk_ui_core_ios_design_color.svg "Customisation options")

![](images/sdk/ios/all_sdk_ui_core_ios_design_card_details.svg "Page to enter payment details")

![](images/sdk/ios/all_sdk_ui_core_ios_design_result.png "Payment result page")

## Setup {#en_sdk_ui_and_core_ios_setup}

### Integration steps {#section_sfv_cnk_lvb .section}

To integrate the web service with the Ecommpay payment platform by using SDK UI & Core for iOS:

1.  Address the following organisational issues of interaction with Ecommpay:
    1.  If your company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If your company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK UI & Core for iOS and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical steps:
    1.  Download and link the SDK UI & Core for iOS libraries.
    2.  Ensure the collection of data necessary for opening the payment form. The minimum data set needed in order to open the payment form consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notifications from SDK UI & Core for iOS as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  With the technical support specialists, coordinate the timeline and the main steps of integrating, testing\(including testing available payment methods\), and launching the solution.
    1.  For testing, use the test project identifier and the details of [test cards](en_test_cards.md).
    2.  For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from Ecommpay.

If you have any questions about working with SDK UI & Core for iOS, contact the Ecommpay technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Importing libraries in Swift {#section_cjg_3nk_lvb .section}

To add a library into your iOS app:

1.  Copy the `ecommpaySDK.xcframework` file in the project folder of you iOS app.
2.  Add the library into your project. When using Xcode 12, you need to do the following:
    1.  Open the target of your project.
    2.  Select **General** \> **Embedded Binaries**.
    3.  Click **+**.
    4.  Click **Add Other**.
    5.  Select the `ecommpaySDK.xcframework` file and click **Add**.
3.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
4.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

5.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Importing libraries in Objective-C {#section_elw_bpk_lvb .section}

To add a library into your iOS app:

1.  Copy the `ecommpaySDK.xcframework` file in the project folder of you iOS app.
2.  Add the library into your project. When using Xcode 12, you need to do the following:
    1.  Open the target of your project.
    2.  Select **General** \> **Embedded Binaries**.
    3.  Click **+**.
    4.  Click **Add Other**.
    5.  Select the `ecommpaySDK.xcframework` file and click **Add**.
    6.  Select **Build Settings**.
    7.  Set **Always embed swift embedded libraries** to **Yes**.
3.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
4.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

5.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Importing libraries via Cocoapods {#section_bgb_cpk_lvb .section}

To add a library into your iOS app:

1.  Open the **Podfile** file and add the following strings:

    ``` {#codeblock_qgf_1hp_4fc}
    target 'App' do
      # Pods for App
      pod 'EcommpaySDK_UI'
    end
    ```

2.  Add key **NSCameraUsageDescription** with value `permission is needed in order to scan card` to the **Info.plist** file.
3.  If your iOS app does not use user location information, add the **NSLocationWhenInUseUsageDescription** key with the `fraud prevention` value in the **Info.plist** file.

    The Ecommpay libraries code does not request user location if the request is not initiated by the host app, but the App Store requires that the **NSLocationWhenInUseUsageDescription** key value is not empty.

    If your iOS app requests user location information, you can skip this step.

4.  If the iOS app does not have permission to save data on the mobile device, add **Privacy - Photo Library Usage Description** and **Privacy - Photo Library Additions Usage Description** keys with values to the **Info.plist** file. The values specified are shown to the customer in the permission request message.

### Signature generation {#section_cjs_1pk_lvb .section}

Make sure that the data is signed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services \([details](en_sdk_overview.md)\), or your own in-house solutions. The procedure of working with the signature is described in [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_ui_and_core_ios_testing}

If necessary, you can open the payment form in the test mode in order to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. When creating the request to open the payment form, in the `PaymentOptions` object specify the following values for the `mockModeType` parameter \(the values are listed for Swift and Objective-C respectively\):

-   `MockModeType.success` / `MockModeTypeSuccess`—if you need to receive `Success` payment result.
-   `MockModeType.decline` / `MockModeTypeDecline`—if you need to receive `Decline` payment result.

If you need to switch to the production mode, pass `MockModeType.disabled` / `MockModeTypeDisabled` as a value for the `mockModeType` parameter.

You can also test payment processing in the test environment of the Ecommpay payment platform. In this case, you should get access to the Ecommpay test environment\(it can be done via [an application](https://ecommpay.com/sign-up/) on the company's main site\) and use the identifier and the secret key of the test project as values of the required parameters passed in the request to open the payment form.

The code samples that are provided on Github contain constants for these parameters

```language-c
 let secret = "your_secret" // secret key of the test project
    let project_id: Int32 = 10 // identifier of the test project
```

```language-c

#define SECRET @"your_secret" // secret key of the test project
#define PROJECT_ID 10 // identifier of the test project
```

To switch to the production mode, change the test values \(the identifier and the secret key of the test project\) to the production ones.

**Warning:** Do not test Apple Pay payments via SDK UI & Core for iOS on simulated iOS devices. Testing the flow of Apple Pay requires a physical device, as the simulator cannot generate a valid Apple Pay token, which results in payment failures. Any errors observed in a simulation environment are expected and do not reflect the behaviour of a production integration.

## Use {#en_sdk_ui_and_core_ios_use}

### Opening payment form {#en_sdk_ui_and_core_ios_openingpf}

SDK UI & Core for iOS supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the `PaymentOptions` object. Optional parameters can be passed in the same object. In addition, they can also be requested from the customer or received from the payment platform.

#### Opening the payment form in Swift {#section_if5_vxy_lvb .section}

To open the payment form:

1.  Import the library:

    ```language-c
    import ecommpaySDK
    ```

2.  Declare the EcommpaySDK library in you app \(for example, inside the `viewDidLoad` method\):

    ```language-c
    let ecommpaySDK = EcommpaySDK()
    ```

3.  Create an object named `PaymentOptions`. This object must contain the following required parameters:

    -   `projectId` \(integer\)—a project identifier assigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifier unique within the project
    -   `paymentCurrency` \(string\)—the payment currency code in the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amount in the smallest currency unit
    -   `customerId` \(string\)—a customer's identifier within the project
    For card payments, also pass the `additionalFields` parameter with at least one of the following parameters: `customer_email` or `customer_phone`.

    To specify the action you need, indicate the required operation type: `Sale`, `Auth`, or `Verify` in the `action` parameter. You can also add any other parameters listed in [the following section](en_sdk_ui_and_core_ios.md).

    The following is an example of the `PaymentOptions` object that includes optional parameters \(description of the payment and the customer's country\)

    ```language-c
    let paymentOptions = PaymentOptions(projectID: 10,
                                paymentID: "internal_payment_id_1",
                                paymentAmount: 1999,
                                paymentCurrency: "USD",
                                paymentDescription: "T-shirt with dog print",
                                customerID: "10",
                                regionCode: "US")
    ```

4.  Pack all payment parameters into a string for signing:

    ```language-c
    paymentOptions.paramsForSignature();
    ```

5.  Send the string to the server side of your web service.
6.  Have your web service generate the signature on the basis of the string and your secret key.
7.  Add signature in your `PaymentOptions` object:

    ```language-c
    paymentOptions.signature = signature;
    ```

8.  Open the payment form by using the following code:

    ```language-c
    ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
             print("ecommpaySDK finished with status \(result.status.rawValue)")
       ...
     }
    ```

    Before opening the payment form, the library checks for any errors and opens the payment form only if no errors occur. Otherwise, the payment form is not opened and the `presentPayment` method returns the error code.


#### Opening the payment form in Objective-C {#section_zqz_vxy_lvb .section}

To open the payment form:

1.  Import the library:

    ```language-c
    #import <EcommpaySDK/EcommpaySDK.h>
    ```

2.  Declare the EcommpaySDK library in you app \(for example, inside the `viewDidLoad` method\):

    ```language-c
    EcommpaySDK *self.EcommpaySDK = [[EcommpaySDK alloc] init];
    ```

3.  Create an object named `PaymentOptions`. This object must contain the following required parameters:

    -   `projectId` \(integer\)—a project identifier assigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifier unique within the project
    -   `paymentCurrency` \(string\)—the payment currency code in the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amount in the smallest currency unit
    -   `customerId` \(string\)—a customer's identifier within the project
    For card payments, also pass the `additionalFields` parameter with at least one of the following parameters: `customer_email` or `customer_phone`.

    To specify the action you need, indicate the required operation type: `Sale`, `Auth`, or `Verify` in the `action` parameter. You can also add any other parameters listed in [the following section](en_sdk_ui_and_core_ios.md).

    The following is an example of the `PaymentOptions` object that includes optional parameters \(description of the payment and the customer's country\)

    ```language-c
    PaymentOptions *paymentOptions = [[PaymentOptions alloc] initWithProjectID:10
                                paymentID:@"internal_payment_id_1"
                            paymentAmount:1999
                          paymentCurrency:@"USD"
                       paymentDescription:@"T-shirt with dog print"
                               customerID:@"10"
                               regionCode:@"US"];
    ```

4.  Pack all payment parameters into a string for signing:

    ```language-c
    paymentOptions.paramsForSignature();
    ```

5.  Send the string to the server side of your web service.
6.  Have your web service generate the signature on the basis of the string and your secret key.
7.  Add signature in your `PaymentOptions` object:

    ```language-c
    [paymentOptions setSignature:signature]
    ```

8.  Open the payment form by using the following code:

    ```language-c
    [self.EcommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
         completionHandler:^(PaymentResult *result) {
         NSLog(@"EcommpaySDK finished with status %ld", (long)result.status);
         ...
     }];
    ```

    Before opening the payment form, the library checks for any errors and opens the payment form only if no errors occur. Otherwise, the payment form is not opened and the `presentPayment` method returns the error code.


### Processing payments {#en_sdk_ui_and_core_ios_payments}

By default, SDK UI & Core for iOS allows processing one-step purchases \(action type `Sale`\). This type of checkout works right out-of-the-box and requires no additional setup.

In addition, SDK UI & Core for iOS supports processing two-step purchases \(which involves placing an authorisation hold via the SDK and subsequent debiting of the authorised amount\). To perform a two-step purchase:

1.  Open the payment form with `Auth` specified as a value for the action type parameter in the `paymentOptions` object:

    ```language-c
    paymentOptions.action = .Auth
    ```

    ```language-c
    [paymentOptions setAction: ActionTypeAuth];
    ```

2.  When needed, initiate debiting of the authorised amount via Dashboard \([details](en_dbl_payments.md)\) or Gate \(by sending the request to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint\).

### Payment card verification {#en_sdk_ui_and_core_ios_verify}

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly \(for example, before performing a payout\) or when you need to save card details for subsequent use. It is essentially a payment that involves debiting a dummy \(zero\) amount from the customer's card.

To perform verification, open the payment form with `Verify` specified as a value for the action type parameter in the `paymentOptions` object:

```language-c
paymentOptions.action = .Verify
```

```language-c
[paymentOptions setAction: ActionTypeVerify];
```

### Payment status information {#en_sdk_ui_and_core_ios_status}

To receive payment result notifications, use requests with the following code included:

```language-c
ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("ecommpaySDK finished with status \(result.status.rawValue)")
   if let error = result.error {      // if an error occurred
      print("ErrorCode: \(error.code) message: \(error.message)")
   }
 }
```

```language-c
[self.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"EcommpaySDK finished with status %ld", (long)result.status);
        if(result.error != NULL) {    // if an error occurred
            NSLog(@"Error code: %@ with message: %@", error.codeString, error.message);
        }
 }];
```

Possible payment result codes passed in the `PaymentResult.status` parameter:

|Result code|Message|Description|
|-----------|-------|-----------|
|`0`|Success|Payment has been completed|
|`100`|Decline|Payment has been declined|
|`200`|Cancelled|Payment has been cancelled by the customer|
|`500`|Error|An error occurred when the payment was being processed|

### Processing payments made with Apple Pay {#en_sdk_ui_and_core_ios_applepay}

In order to implement payment processing which involves the Apple Pay payment method, it is necessary to do the following:

1.  Register the merchant's identifier \(Merchant ID\) with Apple. Merchant ID allows the merchant to accept payments made with the Apple Pay method. This identifier never expires and can be used in multiple websites and iOS applications. For more information see Apple documentation: [Create a merchant identifier](https://help.apple.com/developer-account/#/devb2e62b839?sub=dev103e030bb).
2.  Create Payment Processing Certificate. This certificate is associated with the Merchant ID and is used to secure transaction data when processing Apple Pay payments. For more information see Apple documentation: [Create a payment processing certificate](https://help.apple.com/developer-account/#/devb2e62b839?sub=devf31990e3f).
3.  Send Payment Processing Certificate to the Ecommpay technical support. Use the agreed upon security methods.
4.  Enable the Apple Pay capability for the mobile application in the programming environment. For information about enabling Apple Pay capability in Xcode environment, see Apple documentation: [Enable Apple Pay](https://help.apple.com/xcode/mac/9.3/#/deva43983eb7?sub=dev44ce8ef13)

Once these steps are completed, you can process Apple Pay payments. The main steps such as opening the payment form and processing the responses are performed according to the general procedure, which is the same for all payment methods. In addition, you need to pass the following data in the `applePayOptions` object

```language-c
setupApplePayparams(paymentOptions: PaymentOptions) {
        let applePayOptions = PaymentOptions.ApplePayOptions(applePayMerchantID: "merchant.example.com",
                                                             applePayDescription: "Shop",
                                                             countryCode: "US")
        paymentOptions.applePayOptions = applePayOptions
}
```

```language-c
setApplePaySettings:(PaymentOptions *)paymentOptions {
    PaymentOptionsForApplePay *applePayOptions = [[PaymentOptionsForApplePay alloc]
                                                  initWithApplePayMerchantID:@"merchant.example.com"
                                                  applePayDescription:@"Shop"
                                                  countryCode:@"US"];
}
```

All parameters passed in the `applePayOptions` object are mandatory and are necessary for the Apple Pay session to start correctly.

### Additional capabilities {#en_sdk_ui_and_core_ios_additional_capabilities}

#### Submitting additional payment information {#section_kq4_vcz_lvb .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, in some cases, a payment system or a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided in [the following article](en_pp_clarification.md).

The final set of required parameters can vary depending on a specificprovider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form. The customer fills in the required data, confirms the payment, and receives the payment result information.

#### Cascade payment processing {#section_hrz_5cz_lvb .section}

In case of a payment attempt failure, the capability of cascade payment processing can be used \([details](en_pp_cascading.md)\). This capabilityimplies executing a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the Ecommpay specialists.

If this capability is set up for the project in use, then after the first unsuccessful attempt, a notification is received from SDK UI & Core for iOS. This notification contains the `cascading_with_redirect = true` attribute-value pair. Along with that, the error page with the button to retry making the payment is shown to the customer. If the 3‑D Secure authentication is not required as part of the additional attempt, then the attempt is executed without any further interaction with the customer. Otherwise, a separate page opens for repeating the authentication process.

#### Collecting customer data {#section_pm5_vcz_lvb .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones \(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant should decide which data has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see [the separate article](en_PP_Gathering_customer_data.md).

#### Payment interface language support {#section_uhh_k3t_xyb .section}

By default, during the work with SDK UI & Core, the payment interface is localised according either to the language of the customer's device—if this language is supported for the project in use—or to a language set as default for other cases \(generally, English\). Along with that, if relevant, you can localise the payment interface for particular sessions. For this, every request for opening the payment form must contain a corresponding language code in the `languageCode` \([details](en_sdk_ui_and_core_ios.md)\).

**Warning:** If the language is not supported for the project, the payment form is not opened and the error information is displayed to the customer.

The following languages are supported for the SDK interface and can be promptly set up in the projects of the payment platform.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

#### Saving payment data {#section_ufq_5cz_lvb .section}

SDK UI & Core for iOS allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project. The merchant has to let the technical support know which of the two options is preferable: *always save payment data* or *ask the customer to select the option*. For more information about this capability, refer to article [Saving customer payment data](en_PP_saved_data.md).

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer \(`customerId`\). To display saved payment data to the customer, pass `false` in the `hideSavedWallets` parameter of the `PaymentOptions` object.

## Payment form opening parameters {#en_sdk_ui_and_core_ios_parameters}

When processing card payments, pass the `additionalFields` parameter in the `PaymentOptions` object with at least one of the following fields.

|Parameter|Description|
|:--------|:----------|
|`customer_email`  
 list

|Customer's email.

 Example: `AdditionalField(type: .customer_email, value: "Customer email")`

|
|`customer_phone`  
 list

|Customer's phone number.

 Example: `AdditionalField(type: .customer_phone, value: "Customer phone")`

|

In addition, when processing card payments, you are recommended to specify the customer's billing address information in the `additionalFields` parameter.

**Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

|Parameter|Description|
|:--------|:----------|
|`billing_country`  
 string

|Country of the customer's billing address in the ISO 3166-1 alpha-2 format \([learn more](en_country_codes.md)\).

 Example: `AdditionalField(type: .customer_billing_country, value: "SE")`

|
|`billing_city`  
 string

|City of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_city, value: "Stockholm")`

|
|`billing_postal`  
 string

|Postal code of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_postal, value: "10691")`

|
|`billing_address`  
 string

|Street of the customer's billing address.

 Example: `AdditionalField(type: .customer_billing_address, value: "Albanovaegen 28")`

|

When working with SDK UI & Core for iOS, you can pass the following optional parameters in the `PaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`paymentDescription`  
 string

|Description of the payment. A string that contains between 1 and 255 characters.

 Example: `Cosmoshop purchase`

|
|`receiptData`  
 string

|Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

 Example: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`

|
|`hideSavedWallets`  
 boolean

|Parameter to enable hiding or displaying saved payment instruments in the payment form.

 Possible values:

 -   `true`—saved payment data is hidden
-   `false`—saved payment data is displayed.

|
|`forcePaymentMethod`  
 string

|The identifier of the preselected payment method according to [the table](en_pm_codes.md).

 Example: `card`

|
|`threeDSecureInfo`  
 object

|Object that contains additional objects and parameters necessary for the 3‑D Secure 2 authentication.|
|`languageCode`  
 string

|Payment interface language code in the ISO 639-1 alpha-2 format. Must match one of the languages supported for the given project.

 Example: `IT`

|
|`regionCode  
`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|
|`applePayMerchantID`  
 string

|The Apple Pay identifier of the merchant.|
|`applePayDescription`  
 string

|The description of the merchant in the Apple Pay service.|
|`countryCode`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format. Passed when Apple Pay payments are processed.

 Example: `GB`

|
|`logoImage`  
 object

|A PNG or SVG file that contains the logo of the merchant.|
|`brandColor`  
 string

|Payment interface colour passed as a `UIColor` object.

 Example: `UIColor.green`

|
|`additionalFields`  
 list

|Additional fields that contain information about the customer. Includes a list of parameters with specified values.

 Example: `AdditionalField(type: .customer_first_name, value: "Arthur")`

|

To work with COF purchases, you should pass relevant parameters in the `recurrentInfo` object of the `PaymentOptions` object.

|Parameter|Description|
|:--------|:----------|
|`type`  
 string

|Type of the COF purchase to register.

 Possible values:

 -   `.OneClick`
-   `.Autopayment`
-   `.Regular`

|
|`period`  
 string

|Frequency of debits \(for a regular COF purchase\).

 Possible values:

 -   `.Day`— daily
-   `.Week`—weekly
-   `.Month`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
-   `.Quarter`— quarterly
-   `.Year`—yearly

|
|`expiryDay`  
 string

|Calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiryMonth`  
 string

|Month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).|
|`expiryYear`  
 integer

|Year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).|
|`scheduledPaymentID`  
 string

|Identifier assigned to the payment within which scheduled debits are performed \(for automatic debiting\). It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

 Parameter must be passed together with the `startDate` parameter.

|
|`startDate`  
 string

|Date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.|
|`time`  
 string

|Time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.|
|`schedule`  
 object—schedule of debits performed as part of the COF purchase \(can be specified by the merchant\). Should contain parameters `amount` and `date`.

|
|`amount`  
 integer

|The amount to debit in the smallest currency unit.|
|`date`  
 string

|Date to perform the debit in the `DD-MM-YYYY` format.|

**Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

-   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
-   For other available methods—the corresponding parameter value is determined as follows:
    -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
    -   Month—the month in which the COF purchase was registered.
    -   Year—the year that is 10 years after the year in which the COF purchase was registered.

Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

You can pass the following optional parameters in the `threeDSecureInfo` object. Including these parameters increases the possibility of frictionless flow selection.

|Parameter|Description|
|:--------|:----------|
|`threeDSecureInfo`—object of the `ThreeDSecureInfo` class containing additional objects and parameters used during the 3‑D Secure 2 authentication|
|`threeDSecurePaymentInfo`—object of the `ThreeDSecurePaymentInfo` class with information about the purchase details and indication of the preferable authentication flow|
|`challengeIndicator`  
 string

|This parameter indicates whether challenge flow is requested for this payment.

 Possible values:

-   `01`—no preferences
-   `02`—it is preferable not to use challenge flow
-   `03`—challenge flow preferred
-   `04`—always use challenge flow

|
|`challengeWindow`  
 string

|The dimensions of a window in which authentication page opens.

 Possible values:

-   `01`—250 x 400 px
-   `02`—390 x 400 px
-   `03`—500 x 600 px
-   `04`—600 x 400 px
-   `05`—full screen

|
|`preorderDate`  
 string

|The date the preordered merchandise will be available.

 Format: *dd-mm-yyyy*.

|
|`preorderPurchase`  
 string

|This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date.

 Possible values:

-   `01`—merchandise available in stock
-   `02`—future merchandise availability

|
|`reorder`  
 string

|This parameter indicates whether the cardholder is reordering previously purchased merchandise.

 Possible values:

-   `01`—first time order
-   `02`—reorder

|
|`threeDSecureGiftCardInfo`—object of the `ThreeDSecureGiftCardInfo` class with information about payment with prepaid card or gift card.|
|`amount`  
 integer

|Amount of payment with prepaid or gift card denominated in the smallest currency unit.|
|`currency`  
 string

|Currency of payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example [GBP](references/en/currencies/GBP.md).|
|`count`  
 integer

|Total number of individual prepaid or gift cards/codes used in purchase.|
|`threeDSecureCustomerInfo`—object of the `ThreeDSecureCustomerInfo` class with information about the customer.|
|`addressMatch`  
 string

|The parameter indicates whether the customer billing address matches the address specified in the `threeDSecureShippingInfo` object.

 Possible values:

-   `Y`—Shipping Address matches Billing Address
-   `N`—Shipping Address does not match Billing Address

|
|`billingRegionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.|
|`homePhone`  
 string

|Customer home phone number.

 Numeric, from 4 to 24 characters. Example: `44991234567`.

|
|`workPhone`  
 string

|Customer work phone number.

 Numeric, from 4 to 24 characters. Example `44997654321`.

|
|`threeDSecureAccountInfo`—object of the `ThreeDSecureAccountInfo` class with information about customer account details on record with the web service|
|`additional`  
 string

|Additional customer account information, for instance arbitrary customer ID.

 Maximum 64 characters.

|
|`activityDay`  
 integer

|Number of card payment attempts in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`activityYear`  
 integer

|Number of card payment attempts in the last 365 days.Maximum 3 characters \(`999`\).

|
|`ageIndicator`  
 string

|Number of days since the customer account was created.

 Possible values:

-   `01`—guest check-out
-   `02`—customer account was created in this transaction
-   `03`—customer account was created less than 30 days ago
-   `04`—customer account was created 30 to 60 days ago
-   `05`—customer account was created over 60 days ago

|
|`authData`  
 string

|Any additional log in information in free text.

 Maximum 255 characters.

|
|`authMethod`  
 string

|Authentication type the customer used to log on to the account when placing the order.

 Possible values:

-   `01`—no authentication
-   `02`—log on by using authentication data on file with merchant
-   `03`—log on by using federated ID \(for example, Google Account or Facebook\)
-   `04`—log on by using a FIDO authenticator \(Fast IDentity Online\)

|
|`authTime`  
 string

|Account log on date and time.

 Format: *dd-mm-yyyyhh:mm*.

|
|`date`  
 string

|Account creation date.

 Format: *dd-mm-yyyy*.

|
|`changeDate`  
 string

|Last account change date except for password change or password reset.

 Format: *dd-mm-yyyy*.

|
|`changeIndicator`  
 string

|Number of days since last customer account update, not including password change or reset.

 Possible values:

-   `01`—updated in this transaction
-   `02`—updated less than 30 days ago
-   `03`—updated 30−60 days ago
-   `04`—updated over 60 days ago

|
|`passChangeDate`  
 string

|Last password change or password reset date.

 Format: *dd-mm-yyyy*.

|
|`passChangeIndicator`  
 string

|Number of days since the last password change or reset.

Possible values:-   `01`—password never changed
-   `02`—changed in this transaction
-   `03`—changed less than 30 days ago
-   `04`—changed 30−60 days ago
-   `05`—changed over 60 days ago

|
|`paymentAge`  
 string

|Card record creation date.

 Format: *dd-mm-yyyy*.

|
|`paymentAgeIndicator`  
 string

|Number of days since the payment card details were saved in a customer account.

 Possible values:

-   `01`—current payment uses no customer account \(guest checkout\)
-   `02`—card details were saved today
-   `03`—card details were saved less than 30 days ago
-   `04`—card details were saved 30 to 60 days ago
-   `05`—card details were saved more than 60 days ago

|
|`provisionAttempts`  
 integer

|Number of attempts to add card details in customer account in the last 24 hours.Maximum 3 characters \(`999`\).

|
|`purchaseNumber`  
 integer

|Number of purchases with this cardholder account in the previous six months.Maximum 4 characters \(`9999`\).

|
|`suspiciousActivity`  
 string

|Suspicious activity detection result.

 Possible values:

-   `01`—no suspicious activity detected
-   `02`—suspicious activity detected

|
|`threeDSecureShippingInfo`—object of the `ThreeDSecureShippingInfo` class with shipping details.|
|`address`  
 string

|Shipping address.

 Maximum 150 characters.

|
|`addressUsage`  
 string

|First shipping address usage date.Format: *dd-mm-yyyy*.

|
|`addressUsageIndicator`  
 string

|Number of days since the first time usage of the shipping address.

 Possible values:

-   `01`—this transaction
-   `02`—less than 30 days ago
-   `03`—30−60 days ago
-   `04`—more than 60 days ago

|
|`city`  
 string

|Shipping city.

 Maximum 50 characters.

|
|`country`  
 string

|Shipping country in the ISO 3166-1 alpha-2 format, for example [GB](references/en/countries/GB.md).|
|`deliveryEmail`  
 string

|The email for the digital content delivery.

 Maximum 255 characters.

|
|`deliveryTime`  
 string

|Shipment terms.

Possible values:-   `01`—digital delivery
-   `02`—same-day delivery
-   `03`—overnight delivery
-   `04`—longer than overnight delivery

|
|`nameIndicator`  
 string

|Shipment recipient flag.

 Possible values:

-   `01`—customer and shipment recipient are the same person
-   `02`—customer and shipment recipient are different persons

|
|`postal`  
 string

|Shipping postbox number.

 Maximum 16 characters.

|
|`regionCode`  
 string

|State, province, or region code in the ISO 3166-2 format. Example: `DOR` for Dorset.

 If you specify this parameter, you need also to specify and populate the `country` parameter in the `threeDSecureShippingInfo` object.

|
|`type`  
 string

|Shipment indicator.

 Possible values:

-   `01`—ship to cardholder billing address
-   `02`—ship to another verified address on file with merchant
-   `03`—ship to address that is different from the cardholder billing address or any verified address on file with merchant
-   `04`—ship to local store
-   `05`—digital goods shipment
-   `06`—no shipment, for instance for travel or event tickets
-   `07`—other, for example gaming or subscriptions

|
|`threeDSecureMpiResultInfo`—object of the `threeDSecureMpiResultInfo` class with information about previous customer authentication|
|`acsOperationId`  
 string

|The ID the issuer assigned to the previous customer operation. Maximum 36 characters.|
|`authenticationFlow`  
 string

|The flow the issuer used to authenticate the cardholder in the previous operation.

 Possible values:

-   `01`—frictionless flow
-   `02`—challenge flow

|
|`authenticationTimestamp`  
 string

|Date and time of the previous successful customer authentication|



---

# SDK Flutter for Android and iOS {#en_sdk_flutter}

An article about using SDK Flutter for integrating a payment form in Android and iOS mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_flutter_overview}

### Introduction {#section_eyg_rmf_5bc .section}

Mobile SDK Flutter for Android and iOS\(referred to as SDK Flutter further in this article\) is a software development kit with open-source code that can be used to integrate Flutter mobile applicationswith the Ecommpay payment platform.

SDK Flutterwas developed as a plugin within the Flutter framework. It provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the Ecommpay payment platformwhich allows sending and receiving necessary information during payment processing.

SDK Flutter can be embedded in mobile applications built using Flutter \(version 3.3.0 or later\) and developed for Android \(version 5.0 or later\) or iOS \(version 15.6 or later\).The SDK Flutter libraries and code examples are available on GitHub and pub.dev.To access, use the following URLs:

-   [https://github.com/ITECOMMPAY/msdk-flutter-plugin](https://github.com/ITECOMMPAY/msdk-flutter-plugin)
-   [https://pub.dev/packages/ecommpay\_flutter\_plugin](https://pub.dev/packages/ecommpay_flutter_plugin)

### Capabilities {#section_dnn_rmf_5bc .section}

The following functional capabilities are supported by SDK Flutter:

-   Processing different types of payments made with cards, Apple Pay, and Google Pay as well as other payment methodsavailable for the merchant's project. Supported payment types include:

    -   One-time one-step purchases.
    -   One-time two-step purchases\(an authorisation hold can be placed via the SDK and subsequent debiting of the authorised amount is carried out via Gate or Dashboard\).
    -   COF purchases\(they can be registered via the SDK and then managed via Gate or Dashboard\).
    **Note:** In case of card, Apple Pay, and Google Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

-   Performing payment card verification\(it involves debiting a zero amount from the customer's card\).
-   Checking current payment information.
-   Auxiliary procedures and additional capabilities to boost payment acceptance rates:
    -   Submission of additional payment information.
    -   Payment retries.
    -   Collecting customer data.
-   Additional capabilities to improve user experience:
    -   Saving customer payment data.
    -   Payment interface language support.
    -   Sending email notifications with the list of purchased items to customers.
-   Customising the appearance of the payment interfaceincluding the colour scheme settings.

### Workflow {#section_qcs_rmf_5bc .section}

Generally, the following workflow is relevant when purchases are processed with the use of SDK Flutter.

![](images/sdk/flutter/en_sdk_flutter_functional.svg)

1.  In the user interface of a mobile application, the customer initiates a purchaseby clicking the payment button or in a different fashion set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK Flutter, this set is converted into a string for signing, and the string is sent to the server side of the merchantweb service.
3.  On the server side of the merchantweb service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK Flutter.
4.  With the help of SDK Flutter, a payment session is initiated in the payment platform.
5.  On the payment platform side, the payment interface is preparedin accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
6.  In the mobile application, the payment interface is displayed to the customer.
7.  The customer selects a payment method\(if no method was selected when the payment session was initiated\),specifies the necessary information, and confirms the purchase.
8.  SDK Flutter sends a purchase request to the payment platform.
9.  On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to the providers and payment systems.
10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
12. The information about the purchase result is sent from the payment platform to SDK Flutter.
13. The notification with the result information is displayed to the customer in the user interface.

### Interface {#section_q2y_rmf_5bc .section}

When card, Apple Pay, and Google Paypayments are processed, the customer interacts with the user interface designed by the Ecommpay specialists. This user interface can be customised: you can change its colour.

![](images/sdk/android/all_sdk_ui_core_design_color.svg "Customisation options")

![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Page to enter payment details")

![](images/sdk/android/all_sdk_ui_core_design_result.png "Payment result page")

## Setup {#en_sdk_flutter_setup}

### Integration steps {#section_um4_rpf_5bc .section}

To integrate the web service with the Ecommpay payment platform by using SDK Flutter:

1.  Address the following organisational issues of interaction with Ecommpay:
    1.  If your company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If your company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK Flutter and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical steps:
    1.  Download and install SDK Flutter.
    2.  Ensure the collection of data necessary for the payment interface invocation.The minimum data set needed in order to invoke the payment interface consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notifications from SDK Flutter as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  With the technical support specialists, coordinate the timeline and the main steps of integrating, testing\(including testing available payment methods\), and launching the solution.
    1.  For testing, use the test project identifier and the details of [test cards](en_test_cards.md).
    2.  For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from Ecommpay.

If you have any questions about working with SDK Flutter, contact the Ecommpay technical support specialists\([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Installation {#section_sw5_rpf_5bc .section}

To install SDK Flutterusing the tools of the Flutter framework, follow these steps:

1.  Add the name of the plugin to the `pubspec.yaml` file of the project in useby issuing the following command.

    ```
     $ flutter pub add ecommpay\_flutter\_plugin
    ```

    As a result, the `pubspec.yaml` file should contain the line with the name of the added plugin and its version.

    ```
    dependencies:
      ecommpay\_flutter\_plugin: ^1.0.4
    ```

2.  Open the `lib/main.dart` file and import the functionalities contained in the package

    ```
    import 'package:ecommpay\_flutter\_plugin/ecmpplugin.dart';
    import 'package:ecommpay\_flutter\_plugin/ecmpplugin_method_channel.dart';
    import 'package:ecommpay\_flutter\_plugin/ecmpplugin_platform_interface.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_additional_field.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_additional_field.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_info.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_info.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_options.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_options.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_plugin_result.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_plugin_result.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_recipient_info.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_recipient_info.g.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_recurrent_data.dart';
    import 'package:ecommpay\_flutter\_plugin/models/ecmp_recurrent_data.g.dart';
    ```


You can also install SDK Flutter differently as described in the Flutter documentation \([learn more](https://docs.flutter.dev/packages-and-plugins/using-packages)\).

### Signature generation {#section_emz_rpf_5bc .section}

Make sure that the data is signed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services \([details](en_sdk_overview.md)\), or your own in-house solutions.The procedure of working with the signature is described in [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_flutter_testing}

If necessary, the payment interface can be invoked in test modein order to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. When creating the request to open the payment interface, in the `EcmpPaymentOptions` object specify the following values for the `mockModeType` parameter:

-   `EcmpMockModeType.success`—if you need to receive a `Success` payment result.
-   `EcmpMockModeType.decline`—if you need to receive a `Decline` payment result.

You can also test payment processing in the test environment of the Ecommpay payment platform. In this case, you should get access to the Ecommpay test environment\(you can do it via [an application](https://ecommpay.com/sign-up/) on the company's main site and use the identifier and the secret key of the test project\).

If you need to switch to the production mode, pass `EcmpMockModeType.disabled` as a value for the `mockModeType` parameter and use the production identifier and secret key.

**Warning:** Do not test Apple Pay payments via SDK Flutter on simulated iOS devices. Testing the flow of Apple Pay requires a physical device, as the simulator cannot generate a valid Apple Pay token, which results in payment failures. Any errors observed in a simulation environment are expected and do not reflect the behaviour of a production integration.

## Use {#en_sdk_flutter_use}

### Payment interface invocation {#en_sdk_flutter_openingpf}

SDK Flutter supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the `EcmpPaymentInfo` object while other parameters can be passed in the `EcmpPaymentOptions` object, requested from the customer, or received from the payment platform.

To invoke the payment interface:

1.  Create the `EcmpPaymentInfo` object containing the following required parameters.

    -   `projectId` \(integer\)—a project identifierassigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifierunique within the project
    -   `paymentCurrency` \(string\)—the payment currency codein the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amountin the smallest currency unit
    -   `customerId` \(string\)—a customer's identifierwithin the project
    -   `signature` \(string\)—a request signaturegenerated after all required parameters have been specified
    ```language-json
    final paymentInfo = EcmpPaymentInfo(
                projectId: 77655,
                paymentId: "payment_322",
                paymentAmount: 100,
                paymentCurrency: "USD",
                customerId: "customer007"
              );
    ```

    You can also add any other parameters listed [in the separate table](en_sdk_flutter.md#section_bqz_pcj_wbc).

2.  Receive the string for signing the parameters.

    ```
    final paramsForSignature =
       await ecmpPlugin.getParamsForSignature(paymentInfo);
    debugPrint(paramsForSignature);
    ```

3.  Send this string to the server side of the application.
4.  On the server side of the application, sign the final set of parameters and send it to the client side.
5.  Add the signature to the `EcmpPaymentInfo` object.

    ```language-json
    paymentInfo.signature = "CALCULATED_SIGNATURE_FROM_BACKEND";
    ```

6.  Create the `EcmpPaymentOptions` object that contains the required parameter `actionType` \(string\) with the value specifying the target operation type: `sale`, `auth`, or `verify`. For card payments, specify at least one of the following fields: `email` or `phone` in the `additionalFields` list.

    If necessary, you can also specify additional information about the payment or the list of custom fields that will be displayed to the customer for collecting additional information \(in the `additionalFields` list\), including prepopulated fields. For example, for 3‑D Secure it is recommended that you pass the customer's billing address information \(country code, postal code, city, and street address\). Parameters that can be specified in the `EcmpPaymentOptions` object are listed [in the following table](en_sdk_flutter.md#section_y1v_qcj_wbc).

    **Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

    The following example contains the required `actionType` parameter and the `email` parameter required for card payments as well as several additional parameters passed in the `additionalFields` list to collect customer information.These additional fields include the parameters that are required for 3‑D Secure.

    ```language-json
    final paymentOptions = EcmpPaymentOptions(
      actionType: EcmpActionType.sale,
      paymentInfo: paymentInfo,
      isDarkTheme: false,
      //if need use real service- set EcmpMockModeType.disabled
      mockModeType: EcmpMockModeType.success,
      //set display mode if need
      screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalScreen],
      //set additional fields if need
      additionalFields: [
        EcmpAdditionalField(type: "email", value: "mail@mail.com"),
        EcmpAdditionalField(type: "first_name", value: "firstName"),
      ],
      //set recipient info if need
      recipientInfo: EcmpRecipientInfo(),
      //set recurrent info if need
      recurrentData: EcmpRecurrentData(),
    );
    ```

7.  Create the `EcmpPlugin` object.

    ```language-json
    final ecmpPlugin = EcmpPlugin();
    ```

8.  Send the request to invoke the payment interface and receive result information.

    ```language-json
    final response = await ecmpPlugin.sdkRun(paymentOptions);
    ```


The following is the example of the code that can be used to invoke the payment interface.

```
final ecmpPlugin = EcmpPlugin();
//create payment info
final paymentInfo = EcmpPaymentInfo(
  projectId: 12312,
  paymentId: "paymentId",
  paymentAmount: 100,
  paymentCurrency: "USD",
  customerId: "customer007"
);

//get params for signature
final paramsForSignature =
   await ecmpPlugin.getParamsForSignature(paymentInfo);
debugPrint(paramsForSignature);
//calculate and set signature and set it into payment info
paymentInfo.signature = "signature";

final paymentOptions = EcmpPaymentOptions(
  actionType: EcmpActionType.sale,
  paymentInfo: paymentInfo,
  isDarkTheme: false,
  //if need use real service- set EcmpMockModeType.disabled
  mockModeType: EcmpMockModeType.success,
  //set display mode if need
  screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalScreen],
  //set additional fields if need
  additionalFields: [
    EcmpAdditionalField(type: "email", value: "mail@mail.com"),
    EcmpAdditionalField(type: "first_name", value: "firstName"),
  ],
  //set recipient info if need
  recipientInfo: EcmpRecipientInfo(),
  //set recurrent info if need
  recurrentData: EcmpRecurrentData(),
);

try {
  final response = await ecmpPlugin.sdkRun(paymentOptions);
  debugPrint(response.toString());
} on PlatformException {
  debugPrint("PlatformException");
}
```

### Payment processing {#en_sdk_flutter_payments}

SDK Flutter allows processing one-step and two-step purchases\(with the placing of authorisation hold via the SDK and subsequent debiting\). To process a one-step purchase, pass `sale` in the `actionType` parameter in the request to invoke the payment interface. To process a two-step purchase:

1.  Send the request to invoke the payment interface with `auth` specified as a value for the `actionType` parameterin the `EcmpPaymentOptions` object:

    ```language-java
    actionType: EcmpActionType.auth
    ```

2.  When needed, initiate debiting of the authorised amount via Dashboard \([details](en_dbl_payments.md)\) or Gate\(by sending the request to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint\).

### Payment card verification {#en_sdk_flutter_verify}

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly\(for example, before performing a payout\) or when you need to save card details for subsequent use.

To perform verification, send the request to invoke the payment interface with `verify` specified as a value for the `actionType` parameterin the `EcmpPaymentOptions` object:

```language-java
actionType: EcmpActionType.verify
```

### Payment status information {#en_sdk_flutter_status}

To receive payment result notifications, use the `EcmpPluginResult` object.

```language-json
import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.dart';
import 'package:json_annotation/json_annotation.dart';

part 'ecmp_plugin_result.g.dart';

@JsonSerializable()
class EcmpPluginResult {
  final int resultCode;
  final EcmpPayment? payment;
  final String? errorCode;
  final String? errorMessage;

  EcmpPluginResult(
      this.resultCode, this.payment, this.errorCode, this.errorMessage);

  Map<String, dynamic> toJson() => _$EcmpPluginResultToJson(this);

  factory EcmpPluginResult.fromJson(Map<String, dynamic> data) =>
      _$EcmpPluginResultFromJson(data);
}
```

### Additional capabilities {#en_sdk_flutter_additional_capabilities}

#### Submitting additional payment information {#section_yhs_g5f_5bc .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, in some cases, a payment system or a provider can require additional data necessary for processing a particular payment.This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors.

The final set of required parameters can vary depending on a specific provider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form.The customer fills in the required data, confirms the payment, and receives the payment result information.

For more information about using the capability, see [this article](en_pp_clarification.md).

#### Collecting customer data {#section_a3y_g5f_5bc .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones\(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant shoulddecide which data has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see [this article](en_PP_Gathering_customer_data.md).

#### Payment interface language support {#section_znc_h5f_5bc .section}

By default, the payment interface is localised according to either the language of the customer's device—if this language is supported for the project in use—or a language set as default for other cases\(as a general rule, it is English\). Along with that, if relevant, you can localise the payment interface for particular sessions. For this, every request for invoking the payment interface must contain a corresponding language code in the `languageCode` parameter of the `EcmpPaymentInfo` object.

**Warning:** If the language is not supported for the project, the payment interface is not opened and the error information is displayed to the customer.

The following languages are supported for the SDK Flutter interface and can be promptly set up in the projects of the payment platform.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

#### Saving payment data {#section_j3z_l5f_5bc .section}

SDK Flutter allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project.The merchant has to let the technical support know which of the two options is preferable: *always save payment data* or *ask the customer to select the option*.

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer \(`customerId`\). To display saved payment data to the customer, pass `false` in the `hideSavedWallets` parameter of the `EcmpPaymentInfo` object.

For more information about using the capability, see [this article](en_PP_saved_data.md).

## Additional parameters for invocation requests {#en_sdk_flutter_parameters}

### Parameters of the EcmpPaymentInfo object {#section_bqz_pcj_wbc .section}

When working with SDK Flutter, you can use the following additional parameters in the `EcmpPaymentInfo` object.

|Parameter|Description|
|:--------|:----------|
|`paymentDescription`  
 string

|Description of the payment. A string that contains between 1 and 255 characters.

 Example: `Cosmoshop purchase`

|
|`receiptData`  
 string

|Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

 Example: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`

|
|`token`  
 string

|Token associated with certain payment data. A string that contains between 1 and 255 characters.

 Example: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c`

|
|`hideSavedWallets`  
 boolean

|Parameter that allows you to enable hiding or displaying previously saved payment instruments.

 Possible values:

 -   `true`—hide
-   `false`—display

|
|`forcePaymentMethod`  
 string

|The identifier of the preselected payment methodaccording to [the table](en_pm_codes.md).

 Example: `card`

|
|`languageCode`  
 string

|Payment interface language code in the ISO 639-1 alpha-2 format.Must match one of the languages supported for the given project.

 Example: `EN`

|
|`regionCode  
`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|

### Parameters of the EcmpPaymentOptions object {#section_y1v_qcj_wbc .section}

You can use the following additional parameters in the `EcmpPaymentOptions` object.

|Parameter|Description| |
|---------|-----------|--|
|`googleMerchantId`  
 string

|The Google Pay identifier of the merchant.|1|
|`googleMerchantName`  
 string

|The Google Pay name of the merchant.|2|
|`googleIsTestEnvironment`  
 boolean

|Parameter that indicates a test payment.Passed when processing Google Pay payments.

 Possible values:

 -   `true`—test payment
-   `false`—real payment

|3|
|`applePayMerchantId`  
 string

|The Apple Pay identifier of the merchant.|4|
|`applePayDescription`  
 string

|The description of the merchant in the Apple Pay service.|5|
|`applePayCountryCode`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format. Passed when Apple Pay payments are processed.

 Example: `GB`

|6|
|`isDarkTheme`  
 boolean

|Parameter that indicates the use of the payment interface's dark mode.

 Possible values:

 -   `true`—use the dark mode
-   `false`—do not use the dark mode

|7|
|`brandColor`  
 string

|The colour of the payment interface's main elements in hexadecimal format.

 Example: `#800080`

|8|
|`screenDisplayModes`  
 list

|Parameter indicating that the payment result does not need to be shown in the payment interface.

 Possible values:

 -   `hideSuccessFinalScreen`—do not show payment completion information
-   `hideDeclineFinalScreen`—do not show payment decline information

|10|
|`additionalFields`  
 list

|Additional fields that contain information about the customer. Contains the list of parameters and can include their values.

 Example:

```
additionalFields: [
  EcmpAdditionalField(type: "email", value: "mail@mail.com"),
  EcmpAdditionalField(type: "first_name", value: "firstName"),
],
```

|11|
|`storedCardType`  
 integer

|Indicator of a COF purchase type.

 Possible values:

 -   `3`—autopurchase
-   `5`— regular purchase

|12|
|`recipientInfo`  
 object

|Object with information about the recipient of the payment.|13|
|`pan`  
 string

|Card number.

 Example: `5413330000000019`

|13-113|
|`cardHolder`  
 string

|First and last name \(as specified on the card\).

 Example: `Arthur Eddington`

|13-213|
|`walletId`  
 string

|Number of the wallet.

 Example: `WID2812188222111944`

|13-313|
|`walletOwner`  
 string

|First and last name of the recipient.

 Example: `Arthur Eddington`

|13-413|
|`country`  
 string

|Code of the recipient's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|13-513|
|`address`  
 string

|Recipient's address.

 Example: `42 Walliscote Road`

|13-613|
|`city`  
 string

|Recipient's city of residence.

 Example: `Weston-super-Mare`

|13-713|
|`stateCode`  
 string

|Recipient's state.

 Example: `GB`

|13-813|
|`recurrentData`  
 object

|Object that contains information about a COF purchase that is being registered|14|
|`register`  
 boolean

|Indicator that specifies whether a COF purchase should be registered.

 Possible values:

 -   `true`—payment that registers a COF purchase
-   `false`—payment that does not register a COF purchase

|14-114|
|`type`  
 string

|Type of the COF purchase to register.

 Possible values:

 -   `C`—OneClick
-   `U`—autopurchase
-   `R`—regular purchase

|14-214|
|`expiryDay`  
 string

|Calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).|14-314|
|`expiryMonth`  
 string

|Month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).|14-414|
|`expiryYear`  
 string

|Year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).|14-514|
|`period`  
 string

|Frequency of debits \(for a regular COF purchase\).

 Possible values:

 -   `D`—daily
-   `W`—weekly
-   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
-   `Q`—quarterly
-   `Y`—yearly

|14-614|
|`interval`  
 integer

|Multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter.

 Possible values: from `1` to `100`

|14-714|
|`time`  
 string

|Time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.|14-814|
|`startDate`  
 string

|Date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.|14-914|
|`scheduledPaymentID`  
 string

|Identifier assigned to the payment within which scheduled debits are performed \(for automatic debiting\), it must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

 Parameter must be passed together with the `start_date` parameter.

|14-1014|
|`amount`  
 integer

|The amount to debit in the smallest currency unit.|14-1114|

**Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

-   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
-   For other available methods—the corresponding parameter value is determined as follows:
    -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
    -   Month—the month in which the COF purchase was registered.
    -   Year—the year that is 10 years after the year in which the COF purchase was registered.

Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.



---

# SDK React Native for Android and iOS {#en_sdk_react_native}

An article about using SDK React for integrating a payment form in Android and iOS mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_react_native_overview}

### Introduction {#section_eyg_rmf_5bc .section}

Mobile SDK React Native for Android and iOS\(referred to as SDK React Native further in this article\) is a software development kit with open-source code that can be used to integrate React Native mobile applicationswith the Ecommpay payment platform.

SDK React Nativewas developed as a plugin within the React Native framework. It provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the Ecommpay payment platformwhich allows sending and receiving necessary information during payment processing.

SDK React Native can be embedded in mobile applications built using React Native \(version 0.75.3 or later\) and developed for Android \(version 5.0 or later\) or iOS \(version 15.6 or later\).The SDK React Native libraries and code examples are available on GitHub and NPM.To access, use the following URLs:

-   [https://github.com/ITECOMMPAY/msdk-react-native](https://github.com/ITECOMMPAY/msdk-react-native)
-   [https://www.npmjs.com/package/msdk-react-native](https://www.npmjs.com/package/msdk-react-native)

### Capabilities {#section_dnn_rmf_5bc .section}

The following functional capabilities are supported by SDK React Native:

-   Processing different types of payments made with cards, Apple Pay, and Google Pay as well as other payment methodsavailable for the merchant's project. Supported payment types include:

    -   One-time one-step purchases.
    -   One-time two-step purchases\(an authorisation hold can be placed via the SDK and subsequent debiting of the authorised amount is carried out via Gate or Dashboard\).
    -   COF purchases\(they can be registered via the SDK and then managed via Gate or Dashboard\).
    **Note:** In case of card, Apple Pay, and Google Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

-   Performing payment card verification\(it involves debiting a zero amount from the customer's card\).
-   Checking current payment information.
-   Auxiliary procedures and additional capabilities to boost payment acceptance rates:
    -   Submission of additional payment information.
    -   Payment retries.
    -   Collecting customer data.
-   Additional capabilities to improve user experience:
    -   Saving customer payment data.
    -   Payment interface language support.
    -   Sending email notifications with the list of purchased items to customers.
-   Customising the appearance of the payment interfaceincluding the colour scheme settings.

### Workflow {#section_qcs_rmf_5bc .section}

Generally, the following workflow is relevant when purchases are processed with the use of SDK React Native.

![](images/sdk/reactnative/en_sdk_reactnative_functional.svg)

1.  In the user interface of a mobile application, the customer initiates a purchaseby clicking the payment button or in a different fashion set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK React Native, this set is converted into a string for signing, and the string is sent to the server side of the merchantweb service.
3.  On the server side of the merchantweb service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK React Native.
4.  With the help of SDK React Native, a payment session is initiated in the payment platform.
5.  On the payment platform side, the payment interface is preparedin accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
6.  In the mobile application, the payment interface is displayed to the customer.
7.  The customer selects a payment method\(if no method was selected when the payment session was initiated\),specifies the necessary information, and confirms the purchase.
8.  SDK React Native sends a purchase request to the payment platform.
9.  On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to the providers and payment systems.
10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
12. The information about the purchase result is sent from the payment platform to SDK React Native.
13. The notification with the result information is displayed to the customer in the user interface.

### Interface {#section_q2y_rmf_5bc .section}

When card, Apple Pay, and Google Paypayments are processed, the customer interacts with the user interface designed by the Ecommpay specialists. This user interface can be customised: you can change its colour.

![](images/sdk/android/all_sdk_ui_core_design_color.svg "Customisation options")

![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Page to enter payment details")

![](images/sdk/android/all_sdk_ui_core_design_result.png "Payment result page")

## Setup {#en_sdk_react_native_setup}

### Integration steps {#section_um4_rpf_5bc .section}

To integrate the web service with the Ecommpay payment platform by using SDK React Native:

1.  Address the following organisational issues of interaction with Ecommpay:
    1.  If your company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If your company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK React Native and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical steps:
    1.  Download and install SDK React Native.
    2.  Ensure the collection of data necessary for the payment interface invocation.The minimum data set needed in order to invoke the payment interface consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notifications from SDK React Native as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  With the technical support specialists, coordinate the timeline and the main steps of integrating, testing\(including testing available payment methods\), and launching the solution.
    1.  For testing, use the test project identifier and the details of [test cards](en_test_cards.md).
    2.  For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from Ecommpay.

If you have any questions about working with SDK React Native, contact the Ecommpay technical support specialists\([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Installation {#section_sw5_rpf_5bc .section}

To install SDK React Nativeusing the tools of the React Native framework, follow these steps:

1.  In the command line, go to the web service source code directory and run one of the following commands.

    ``` {#codeblock_e4b_wxd_ddc}
     npm install msdk-react-native
    // or
    yarn install msdk-react-native
    ```

2.  Import the modules into your web service project.

    ``` {#codeblock_wd3_yxd_ddc}
    import {initializePayment, getParamsForSignature} from 'msdk-react-native';
    ```


You can also install SDK React Native differently as described in the React Native documentation \([learn more](https://reactnative.dev/docs/integration-with-existing-apps)\).

### Signature generation {#section_emz_rpf_5bc .section}

Make sure that the data is signed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services \([details](en_sdk_overview.md)\), or your own in-house solutions.The procedure of working with the signature is described in [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_react_native_testing}

If necessary, the payment interface can be invoked in test mode. It allows you to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. When creating the request to open the payment interface, in the `EcmpPaymentOptions` object specify the following values for the `mockModeType` parameter:

-   `EcmpMockModeType.success`—if you need to receive a `Success` payment result.
-   `EcmpMockModeType.decline`—if you need to receive a `Decline` payment result.

You can also test payment processing in the test environment of the Ecommpay payment platform. In this case, you should get access to the Ecommpay test environment\(you can do it via [an application](https://ecommpay.com/sign-up/) on the company's main site and use the identifier and the secret key of the test project\).

If you need to switch to the production mode, pass `EcmpMockModeType.disabled` as a value for the `mockModeType` parameter and use the production identifier and secret key.

**Warning:** Do not test Apple Pay payments via SDK React Native on simulated iOS devices. Testing the flow of Apple Pay requires a physical device, as the simulator cannot generate a valid Apple Pay token, which results in payment failures. Any errors observed in a simulation environment are expected and do not reflect the behaviour of a production integration.

## Use {#en_sdk_react_native_use}

### Payment interface invocation {#en_sdk_react_native_openingpf}

SDK React Native supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the `EcmpPaymentInfo` object while other parameters can be passed in the `EcmpPaymentOptions` object, requested from the customer, or received from the payment platform.

To invoke the payment interface:

1.  Create the `EcmpPaymentInfo` object containing the following required parameters.

    -   `projectId` \(integer\)—a project identifierassigned by Ecommpay
    -   `paymentId` \(string\)—a payment identifierunique within the project
    -   `paymentCurrency` \(string\)—the payment currency codein the ISO 4217 alpha-3 format
    -   `paymentAmount` \(integer\)—the payment amountin the smallest currency unit
    -   `customerId` \(string\)—a customer's identifierwithin the project
    -   `signature` \(string\)—a request signaturegenerated after all required parameters have been specified
    ``` {#codeblock_trg_5yd_ddc .language-javascript}
    let paymentInfo: EcmpPaymentInfo = {
        projectID: 12123123,
        paymentID: "paymentId11",
        paymentCurrency: "USD",
        paymentAmount: 22200,
        customerId: "customer34"
    };
    ```

    You can also add any other parameters listed [in the separate table](en_sdk_react_native.md#section_bqz_pcj_wbc).

2.  Receive the string for signing the parameters.

    ``` {#codeblock_wdd_mzj_ddc .language-javascript}
    let paramsForSignature = getParamsForSignature(paymentInfo);
    console.log(paramsForSignature);
    
    ```

3.  Send this string to the server side of the application.
4.  On the server side of the application, sign the final set of parameters and send it to the client side.
5.  Add the signature to the `EcmpPaymentInfo` object.

    ``` {#codeblock_ef2_vyd_ddc .language-javascript}
    paymentInfo.signature = "CALCULATED_SIGNATURE_FROM_YOUR_BACKEND"
    ```

6.  Create the `EcmpPaymentOptions` object that contains the required parameter `actionType` \(string\) with the value specifying the target operation type: `sale`, `auth`, `verify`, or `tokenize`. For card payments, specify at least one of the following fields: `email` or `phone` in the `additionalFields` list.

    If necessary, you can also specify additional information about the payment or the list of custom fields that will be displayed to the customer for collecting additional information \(in the `additionalFields` list\), including prepopulated fields. For example, for 3‑D Secure it is recommended that you pass the customer's billing address information \(country code, postal code, city, and street address\). Parameters that can be specified in the `EcmpPaymentOptions` object are listed [in the following table](en_sdk_react_native.md#section_y1v_qcj_wbc).

    **Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

    The following example contains the required `actionType` parameter and the `email` parameter required for card payments as well as several additional parameters passed in the `additionalFields` list to collect customer information.These additional fields include the parameters that are required for 3‑D Secure.

    ``` {#codeblock_ynl_xyd_ddc .language-javascript}
    let paymentOptions: EcmpPaymentOptions = {
        actionType: EcmpActionType.sale,
        paymentInfo: paymentInfo,
        isDarkTheme: true,
    
        //For switching to the production mode, set EcmpMockModeType.disabled
        mockModeType: EcmpMockModeType.success,
    
        //If needed, set display mode 
        screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalPage],
    
         //If needed, set additional fields 
        additionalFields: [ {
          type: 'email',
          value: 'mail@mail.com'
        }]
    }
    ```

7.  Send the request to invoke the payment interface and receive result information.

    ``` {#codeblock_eh4_yzj_ddc .language-javascript}
    initializePayment(paymentOptions);
    ```


The following is the example of the code that can be used to invoke the payment interface.

``` {#codeblock_snq_hzd_ddc .language-javascript}
let paymentInfo: EcmpPaymentInfo = {
    projectID: 12123123,
    paymentID: "paymentId11",
    paymentCurrency: "USD",
    paymentAmount: 22200,
    customerId: "customer34"
};

//Get params for signature
let paramsForSignature = getParamsForSignature(paymentInfo);
console.log(paramsForSignature);

//Generate signature and add it to the paymentInfo object
paymentInfo.signature = "signature";

let paymentOptions: EcmpPaymentOptions = {
    actionType: EcmpActionType.sale,
    paymentInfo: paymentInfo,
    isDarkTheme: true,

    //For switching to the production mode, set EcmpMockModeType.disabled
    mockModeType: EcmpMockModeType.success,

    //If needed, set display mode
    screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalPage],

     //If needed, set additional fields 
    additionalFields: [ {
      type: 'email',
      value: 'mail@mail.com'
    }]
}

initializePayment(paymentOptions)
```

### Payment processing {#en_sdk_react_native_payments}

SDK React Native allows processing one-step and two-step purchases\(with the placing of authorisation hold via the SDK and subsequent debiting\). To process a one-step purchase, pass `sale` in the `actionType` parameter in the request to invoke the payment interface. To process a two-step purchase:

1.  Send the request to invoke the payment interface with `auth` specified as a value for the `actionType` parameterin the `EcmpPaymentOptions` object:

    ```language-javascript
    actionType: EcmpActionType.auth
    ```

2.  When needed, initiate debiting of the authorised amount via Dashboard \([details](en_dbl_payments.md)\) or Gate\(by sending the request to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint\).

### Payment card verification {#en_sdk_react_native_verify}

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly\(for example, before performing a payout\) or when you need to save card details for subsequent use.

To perform verification, send the request to invoke the payment interface with `verify` specified as a value for the `actionType` parameterin the `EcmpPaymentOptions` object:

```language-javascript
actionType: EcmpActionType.verify
```

### Payment status information {#en_sdk_react_native_status}

In case of payment processing via the Ecommpay payment platform, callbacks are sent to the merchant's web service to communicate different kinds of information: for example, to notify where to redirect customers or to deliver results of performing an operation. The description of the callback structure and the information on how to work with callbacks can be found in [Handling callbacks](en_platform_callbacks.md).

### Additional capabilities {#en_sdk_react_native_additional_capabilities}

#### Submitting additional payment information {#section_yhs_g5f_5bc .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, in some cases, a payment system or a provider can require additional data necessary for processing a particular payment.This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors.

The final set of required parameters can vary depending on a specific provider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form.The customer fills in the required data, confirms the payment, and receives the payment result information.

For more information about using the capability, see [this article](en_pp_clarification.md).

#### Collecting customer data {#section_a3y_g5f_5bc .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones\(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant shoulddecide which data has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see [this article](en_PP_Gathering_customer_data.md).

#### Payment interface language support {#section_znc_h5f_5bc .section}

By default, the payment interface is localised according to either the language of the customer's device—if this language is supported for the project in use—or a language set as default for other cases\(as a general rule, it is English\). Along with that, if relevant, you can localise the payment interface for particular sessions. For this, every request for invoking the payment interface must contain a corresponding language code in the `languageCode` parameter of the `EcmpPaymentInfo` object.

**Warning:** If the language is not supported for the project, the payment interface is not opened and the error information is displayed to the customer.

The following languages are supported for the SDK React Native interface and can be promptly set up in the projects of the payment platform.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

#### Saving payment data {#section_j3z_l5f_5bc .section}

SDK React Native allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project.The merchant has to let the technical support know which of the two options is preferable: *always save payment data* or *ask the customer to select the option*.

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer \(`customerId`\). To display saved payment data to the customer, pass `false` in the `hideSavedWallets` parameter of the `EcmpPaymentInfo` object.

For more information about using the capability, see [this article](en_PP_saved_data.md).

## Additional parameters for invocation requests {#en_sdk_react_native_parameters}

### Parameters of the EcmpPaymentInfo object {#section_bqz_pcj_wbc .section}

When working with SDK React Native, you can use the following additional parameters in the `EcmpPaymentInfo` object.

|Parameter|Description|
|:--------|:----------|
|`paymentDescription`  
 string

|Description of the payment. A string that contains between 1 and 255 characters.

 Example: `Cosmoshop purchase`

|
|`receiptData`  
 string

|Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

 Example: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`

|
|`token`  
 string

|Token associated with certain payment data. A string that contains between 1 and 255 characters.

 Example: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c`

|
|`hideSavedWallets`  
 boolean

|Parameter that allows you to enable hiding or displaying previously saved payment instruments.

 Possible values:

 -   `true`—hide
-   `false`—display

|
|`languageCode`  
 string

|Payment interface language code in the ISO 639-1 alpha-2 format.Must match one of the languages supported for the given project.

 Example: `EN`

|
|`regionCode  
`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|

### Parameters of the EcmpPaymentOptions object {#section_y1v_qcj_wbc .section}

You can use the following additional parameters in the `EcmpPaymentOptions` object.

|Parameter|Description| |
|---------|-----------|--|
|`googleMerchantId`  
 string

|The Google Pay identifier of the merchant.|1|
|`googleMerchantName`  
 string

|The Google Pay name of the merchant.|2|
|`googleIsTestEnvironment`  
 boolean

|Parameter that indicates a test payment.Passed when processing Google Pay payments.

 Possible values:

 -   `true`—test payment
-   `false`—real payment

|3|
|`applePayMerchantId`  
 string

|The Apple Pay identifier of the merchant.|4|
|`applePayDescription`  
 string

|The description of the merchant in the Apple Pay service.|5|
|`applePayCountryCode`  
 string

|Code of the customer's country in the ISO 3166-1 alpha-2 format. Passed when Apple Pay payments are processed.

 Example: `GB`

|6|
|`isDarkTheme`  
 boolean

|Parameter that indicates the use of the payment interface's dark mode.

 Possible values:

 -   `true`—use the dark mode
-   `false`—do not use the dark mode

|7|
|`brandColor`  
 string

|The colour of the payment interface's main elements in hexadecimal format.

 Example: `#800080`

|8|
|`screenDisplayModes`  
 list

|Parameter indicating that the payment result does not need to be shown in the payment interface.

 Possible values:

 -   `hideSuccessFinalPage`—do not show payment completion information
-   `hideDeclineFinalPage`—do not show payment decline information

|10|
|`additionalFields`  
 list

|Additional fields that contain information about the customer. Contains the list of parameters and can include their values.

 Example:

```
additionalFields: [
  EcmpAdditionalField(type: "email", value: "mail@mail.com"),
  EcmpAdditionalField(type: "first_name", value: "firstName"),
],
```

|11|
|`storedCardType`  
 integer

|Indicator of a COF purchase type.

 Possible values:

 -   `3`—autopurchase
-   `5`— regular purchase

|12|
|`recipientInfo`  
 object

|Object with information about the recipient of the payment.|13|
|`pan`  
 string

|Card number.

 Example: `5413330000000019`

|13-113|
|`cardHolder`  
 string

|First and last name \(as specified on the card\).

 Example: `Arthur Eddington`

|13-213|
|`walletId`  
 string

|Number of the wallet.

 Example: `WID2812188222111944`

|13-313|
|`walletOwner`  
 string

|First and last name of the recipient.

 Example: `Arthur Eddington`

|13-413|
|`country`  
 string

|Code of the recipient's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|13-513|
|`address`  
 string

|Recipient's address.

 Example: `42 Walliscote Road`

|13-613|
|`city`  
 string

|Recipient's city of residence.

 Example: `Weston-super-Mare`

|13-713|
|`stateCode`  
 string

|Recipient's state.

 Example: `GB`

|13-813|
|`recurrentData`  
 object

|Object that contains information about a COF purchase that is being registered|14|
|`register`  
 boolean

|Indicator that specifies whether a COF purchase should be registered.

 Possible values:

 -   `true`—payment that registers a COF purchase
-   `false`—payment that does not register a COF purchase

|14-114|
|`type`  
 string

|Type of the COF purchase to register.

 Possible values:

 -   `C`—OneClick
-   `U`—autopurchase
-   `R`—regular purchase

|14-214|
|`expiryDay`  
 string

|Calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).|14-314|
|`expiryMonth`  
 string

|Month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).|14-414|
|`expiryYear`  
 string

|Year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).|14-514|
|`period`  
 string

|Frequency of debits \(for a regular COF purchase\).

 Possible values:

 -   `D`—daily
-   `W`—weekly
-   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
-   `Q`—quarterly
-   `Y`—yearly

|14-614|
|`interval`  
 integer

|Multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter.

 Possible values: from `1` to `100`

|14-714|
|`time`  
 string

|Time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.|14-814|
|`startDate`  
 string

|Date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.|14-914|
|`scheduledPaymentID`  
 string

|Identifier assigned to the payment within which scheduled debits are performed. It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

 Parameter must be passed together with the `start_date` parameter.

|14-1014|
|`amount`  
 integer

|The amount to debit in the smallest currency unit.|14-1114|

**Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

-   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
-   For other available methods—the corresponding parameter value is determined as follows:
    -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
    -   Month—the month in which the COF purchase was registered.
    -   Year—the year that is 10 years after the year in which the COF purchase was registered.

Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.



---

# SDK Core for Android {#en_sdk_core_android}

An article about using SDK Core for integrating a payment form with the option to use the in-house interface in Android mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_core_android_overview}

### Introduction {#section_kj3_5mp_k5b .section}

Mobile SDK Core for Android is a software development kit that can be used to integrate Android applications with the Ecommpay payment platform.

SDK Core for Android ensures the interaction of a mobile application with the payment platform for sending and receiving necessary information during payment processing. That said, SDK Core for Android does not ensure customer interaction with the user interface—this allows the merchant to use their in-house payment interface during the work with this development kit.

This article provides the information about working with SDK Core for Android. This information includes the description of the interaction workflow, payment processing scenarios, and additional capabilities with code examples in the Kotlin language.

SDK Core for Android can be embedded in mobile applications developed for Android version 5.0 or later. The libraries of SDK Core for Android and code examples are provided on GitHub at the following URLs:

-   Libraries for Android: [https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/releases](https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/releases)
-   Code examples: [https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/](https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/)

### Capabilities {#section_ebc_tyt_k5b .section}

SDK Core for Android supports the work with payment cards and the Google Pay alternative payment method.The following functional capabilities are supported by SDK Core for Android:

-   Processing purchases with immediate debiting of funds.
-   Placing an authorisation hold on funds for subsequent debiting of the funds after a certain period expiration or based on the corresponding request from the merchant \(sent via [Gate](en_Gate__cof_merchant_side.md) or [Dashboard](en_dbl_payments.md)\).
-   Verifying payment cards for their subsequent use.
-   Registering COF purchases.
-   Saving payment data for subsequent processing of purchases.

During payment processing, additional actions can be required from customers, for example, for performing 3‑D Secure authentication and specifying the details about the owner of the payment instrument. The applicability of these actions usually depends on the protocols and rules of the providers andpayment systems, however, in some cases, it can depend on the merchant's preferences as well. The following procedures and additional capabilities are supported by SDK Core for Android:

-   3‑D Secure authentication—the procedure of customer authentication with the use of the 3‑D Secure protocols.
-   Cascade payment processing—additional payment processing attempts \(used when necessary\) without changing the payment method.
-   Submission of additional payment information—the procedure of specifying additional data that can be required by payment systems in certain cases.
-   Collection of customer data—getting and providing additional customer information that can be relevant for processing subsequent payments.

Setting up the capabilities of cascade payment processing and customer data collection should be coordinated with the Ecommpay specialists.

### Workflow {#section_vyw_215_k5b .section}

Generally, purchases with the use of SDK Core for Android are processed according to the following workflow.

![](images/ecommpay/sdk/android/en_msdk_core_android_functional.svg)

1.  The customer initiates a purchase in the user interface of a mobile application by clicking the payment button or by another method set up on the merchant side.
2.  In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK Core for Android, this set is converted into a string for signing the parameters and the string is sent to the server side of the merchant web service.
3.  On the server side of the merchant web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, after that, the prepared data is sent back to SDK Core for Android.
4.  With the help of SDK Core for Android, creation of the payment session is initiated in the payment platform.
5.  On the payment platform side, based on the project and customer identifiers, the lists of theavailable payment methods and saved payment data are sent to SDK Core for Android.
6.  In the mobile application, the information received from SDK Core for Android is processed and prepared to be further displayed to the customer.
7.  The customerchooses a payment method \(if no method has been set during the payment session opening\), specifies the necessary information, and confirms the purchase.
8.  In the mobile application, a certain scenario of work with SDK Core for Android is called—with regard to all actions performed by the customer.
9.  The request for processing the purchase according to the called scenario is sent from SDK Core for Android to the payment platform.
10. On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to theproviders and payment systems.
11. The payment is processed in the payment environment; then the payment result information is received in the payment platform.
12. In the payment platform, the information about the payment result is processed and sent to the server side of the web service.
13. The information about the purchase result is sent from the payment platform to SDK Core for Android.
14. The notification with the result information is sent from SDK Core for Android to the mobile application and then displayed to the customer.

## Setup {#en_sdk_core_android_setup}

### Integration steps {#section_o5p_jg5_k5b .section}

To integrate the web service with the Ecommpay payment platform by using SDK Core for Android, proceed as follows:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If the company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK Core for Android and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical tasks:

    1.  Download and link SDK Core for Android.
    2.  Prepare the user interface and ensure the collection of data necessary for initiating a payment session. The minimum data set needed for the payment session creation consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notification from SDK Core for Android as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  Coordinate the procedures and dates of integrating, testing\(including testing available payment methods\), and launching the solution.

    1.  For testing, the test project identifier and the [test cards](en_test_cards.md) details should be used.
    2.  For switching to the production mode, the value of the test project identifier should be changed to the value of the production project identifier received from Ecommpay.

The questions about working with SDK Core for Android, if any, should be directed to the Ecommpay technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Libraries installation {#section_ivs_n35_k5b .section}

For the mobile applications developed for Android version 5.0 or later linking the SDK Core for Android libraries via MavenCentral is supported. To link the libraries, proceed as follows:

1.  Open the module `build.gradle.kts` in the application.
2.  Specify the `mavenCentral` repository in the `repositories` section:

    ```language-json
    
    allprojects {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```

3.  Add the following code in the `dependencies` section:

    ```language-json
    implementation "com.ecommpay:msdk-core-android:LATEST\_VERSION"
    ```


### Signature generation {#section_ffg_qj5_k5b .section}

Data signing should be performed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, the merchant can use ready-to-use components, such as SDKs for web services in different programming languages \([details](en_sdk_overview.md)\) or the merchant's in-house solutions. The procedure of working with the signature is provided in the section [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_core_android_testing}

Before processing real payments via SDK Core for Android, it is recommended to test payment processing in the test project. The merchant can obtain the identifier and the secret key of the test project when accessing the Ecommpay test environment\(this can be done via [an application](https://ecommpay.com/sign-up/)\). Along with that, upon the coordination with the Ecommpay specialists, it is possible to test the usage of the Google Pay method and additional capabilities, such as cascade payment processing and collection of customer data.

To switch to the test mode, proceed as follows:

1.  Open the module `build.gradle.kts` in the application.
2.  Specify the identifier \(`projectId`\) and the secret key \(`projectSecretKey`\) of the test project.
3.  Launch the synchronisation process `gradle`.

To switch to the production mode, change the test values \(the identifier and the secret key of the test project\) to the production ones.

## Usage {#en_sdk_core_android_usage}

SDK Core for Android supports various targeted actions and, for each of these actions, a certain parameter set is required. The required minimum of parameters is sent in the initial request for creating a payment session; the rest of the parameters can be requested from the customer and received from the payment platform. Based on the received parameters, the request for creating a payment according to one of the available scenarios is generated.

The scenarios, procedures of performing targeted actions, and the set of the parameters available during the work with SDK Core for Android are provided in the following sections of this article.

### Procedure of performing targeted actions {#en_sdk_core_android_payment_processing}

SDK Core for Android supports targeted actions with the direct use of cardsand with the use of the Google Pay alternative method \([details](pm_googlepay.md)\). To work with the Google Pay payment method, the merchant should first contact the Ecommpay technical support specialists to coordinate the method setup.

Generally, to process purchases via SDK Core for Android, proceed as follows:

1.  Create the `MSDKCoreSession` object.

    ```language-json
    val config = MSDKCoreSessionConfig.debug("API HOST", "WS API HOST")
    val msdkSession = MSDKCoreSession(config)
    ```

2.  Create the `PaymentInfo` object with the parameters of payment processing. This object should contain the required minimum of parameters \(the project identifier, the payment identifier, the payment amount, and the payment currency\), additionally, other parameters can be submitted \([details](en_sdk_core_android.md#section_ihx_qyv_k5b)\).

    ```language-json
    val paymentInfo = PaymentInfo(  // payment information
        projectId = 553,   // project identifier
        paymentId = "payment_21",   // payment identifier
        paymentAmount = 400,        // payment amount
        paymentCurrency = "EUR",    // payment currency code
        customerId = "12"           // customer identifier
    )
    ```

3.  Receive the string for signing the parameters and send it to the server side of the application.

    ```language-json
    paymentInfo.getParamsForSignature(),
    ```

4.  On the server side of the application, sign the final set of parameters and send it to the client side.
5.  Add the signature to the `PaymentInfo` object.
6.  Send the request for creating the payment session. For this, call the `getInitInteractor` method. For card payments, specifyat least one of the following parameters: the customer's email \(`customerEmail`\) or phone number \(`customerPhone`\).

    At this point, it is also recommended that for 3‑D Secure you should pass the customer's billing address information:

    -   `billingCountry`—the country of the customer's billing address in the ISO 3166-1 alpha-2 format \([details](en_country_codes.md)\)
    -   `billingPostal`—the postal code of the customer's billing address
    -   `billingCity`—the city of the customer's billing address
    -   `billingAddress`—the street of the customer's billing address
    **Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

    ```language-json
    val request = InitRequest(
         paymentInfo = paymentInfo,
         recurrentInfo = null,      
         additionalFields = ( //list of fields for collecting additional information
            customerEmail = customerEmail,
            customerPhone = customerPhone
         )
    )
    msdkSession.getInitInteractor().execute(request, this)
    ```

7.  Receive the notification with the information about the payment session creation and the lists of theavailable payment methods and saved payment data that are relevant for the project in use and a particular customer.

    ```language-json
    fun onInitReceived(
    paymentMethods: List<PaymentMethod\>,
    savedAccounts: List<SavedAccount>
    ) {
    val stringResourceManager = msdkSession.getStringResourceManager()
    val title = stringResourceManager.payment.methodsTitle
     
    val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
    val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
     
    val paymentMethods = msdkSession.getPaymentMethods()  // receiving payment method list
    val savedAccounts = msdkSession.getSavedAccounts()   // receiving payment data list
    }
    ```

8.  Process the received data and display the payment form to the customer.
9.  To process a purchase via Google Pay, proceed as follows:
    -   Receive a token from Google Pay, for this, the `GooglePayHelper` class can be used. Detailed information about setting up the application for the work with Google Pay is provided in the [documentation](https://developers.google.com/pay/api/android/guides/tutorial).

        ```language-json
        val googlePayHelper = GooglePayHelper("merchant Id")
        val googleJson = googlePayHelper.createPaymentDataRequest(BigDecimal.valueOf(12.34), "USD").toString()
        val gpayRequest = PaymentDataRequest.fromJson(googleJson)
         
        val client = Wallet.getPaymentsClient(
            this,
            Wallet.WalletOptions.Builder()
                .setEnvironment(WalletConstants.ENVIRONMENT_TEST)// test environment
                .setTheme(WalletConstants.THEME_LIGHT)
                .build()
        )
         
        AutoResolveHelper.resolveTask(
            client.loadPaymentData(gpayRequest),
            this,
            991
        )
        ```

    -   Receive a token from Google Pay in the `onActivityResult` notification.

        ```language-json
        override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
            super.onActivityResult(requestCode, resultCode, data)
            if (data == null) return
         
            val paymentData = PaymentData.getFromIntent(data)
            val paymentInformation = paymentData?.toJson() ?: return
            val paymentMethodData: JSONObject = JSONObject(paymentInformation).getJSONObject("paymentMethodData")
            val token = paymentMethodData.getJSONObject("tokenizationData").getString("token")
         
        }
        ```

10. Send the request for payment creation based on the data received from the customer. For this, call the `getPayInteractor` method.

    ```language-json
    // purchase with the use of a card
    interactor.execute(
                NewCardSaleRequest(          // scenario
                   cvv = "123",              // card verification value
                   pan = "5413330000000019", // card number
                   expiryDate = CardDate(month = 1, year = 2025), // card expiration month and year
                   cardHolder = "John Doe"   // cardholder first and last name
                ),
                this
            )
     
    // purchase with the use of the Google Pay method
    interactor.execute\(
                GooglePaySaleRequest\(           // scenario
                   merchantId = merchant\_321,   // merchant identifier
                   token = token,               // token received from Google Pay
                   environment = GooglePayEnvironment.TEST   // test environment
                \),
                this
            \)
    ```

11. Receive a range of notifications from SDK Core for Android—about the payment creation and the payment status change. If relevant, also accept the notifications stating that the submission of additional payment information and 3‑D Secure authentication are required and perform the needed actions.
12. Receive the notification with the payment information result and display this information to the customer.

During the processing of certain payments, the merchant and the customer are required to perform a range of actions for carrying out certain procedures. The work with such procedures is described in the following sections of this article.

### Parameters of work with SDK Core for Android {#en_sdk_core_android_scenarios}

#### Actions with payment cards {#section_a4k_rsv_k5b .section}

For performing targeted actions with the direct use of cards, such as purchase processing \(`NewCardSaleRequest`\), authorisation holds on funds \(`CardAuthRequest`\), and card verification \(`CardVerifyRequest`\), the following data sets are used.

|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units \(for card verification use the value `0`\)
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project
-   `register` \(boolean\)—indicator of the COF purchases registration for which the value `true` should be used. The information about the parameters available for registering COF purchases is provided [in the separate article](en_pp_recurring.md)

|-   `cvv` \(string\)—card verification value
-   `pan` \(string\)—card number \(without spaces\)
-   `year` \(integer\)—card expiration year
-   `month` \(integer\)—card expiration month
-   `cardHolder` \(string\)—cardholder name specified on the card
-   `saveCard` \(boolean\)—indicator showing whether the payment card data has been saved

|

#### Tokenisation {#section_ujq_ntv_k5b .section}

SDK Core for Android supports tokenisation of payment data. When the scenario of tokenisation \(`CardTokenizeRequest`\) is running, no financial operations are performed but a secure identifier associated with the data of a particular payment card is generated. The information about generating and using tokens is provided in the corresponding articles—[Tokenization](en_pp_token.md) and [Payments by using tokens](en_PP_Payment_by_token.md).

For generating tokens via SDK Core for Android, the following data sets are required.

|Payment session creation|Tokenisation|
|------------------------|------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `customer_id` \(string\)—customer identifier unique within the project

|-   `pan` \(string\)—card number \(without spaces\)
-   `year` \(integer—card expiration year
-   `month` \(integer\)—card expiration month
-   `cardHolder` \(string\)—cardholder name specified on the card

|

#### Usage of saved payment data {#section_nrw_d5v_k5b .section}

SDK Core for Android supports the capability of saving payment data on the customer's initiative and via tokenisation. It also supports using this data for payment processing. With saved payment data and tokens, it is possible to process purchases and place authorisation holds on funds via certain scenarios. In case of saved data, these scenarios are: `SavedCardSaleRequest` \(for processing purchases\) and `SavedCardAuthRequest` \(for placing holds on funds\); in case of tokens, these scenarios are `CardSaleTokenizeRequest` \(for processing purchases\) and `CardAuthTokenizeRequest` \(for placing holds on funds\).

|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project
-   `account_token` \(string\)—payment data token \(for the scenarios where a token is used\)

|-   `cvv` \(string\)—card verification value
-   `accountId` \(integer\)—saved payment data identifier received in the notification about the payment session creation

|

#### Purchases by using alternative methods {#section_bt3_pvv_k5b .section}

SDK Core for Android supports processing purchases \(`GooglePaySaleRequest`\) and placing holds on funds \(`GooglePayAuthRequest`\) by using the Google Pay method.

To process purchases with the use of the Google Pay method, proceed as follows:

1.  Register in [the Google Pay Business Console](https://pay.google.com/business/console) service and receive the merchant identifier in the Google Pay service \(Google merchant ID\).
2.  Accept and comply with [the Acceptable Use Policy](https://payments.developers.google.com/terms/aup) of Google Pay API and accept [the Terms of Service](https://payments.developers.google.com/terms/sellertos) of the Google Pay API.
3.  Embed the Google Pay button in the user interface following [the brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) and implement the process of receiving token with the customer card data from the Google Pay service.
4.  Add the following information to the `AndroidManifest.xml` file:

    ```language-json
    <meta-data
        android:name="com.google.android.gms.wallet.api.enabled"
        android:value="true" />
    ```


|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project

|-   `merchantId` \(string\)—merchant identifier in the Google Pay service \(Google merchant ID\)
-   `token`—token received from Google Pay
-   `environment`—environment \(the test or the production one\) in which the payment should be initiated \(the possible values are: `test` and `prod`; if the `test` value is specified, the identifier of the merchant's test project should be used in the request; if the `prod` value is specified, the identifier of the merchant's production project should be used in the request\)
-   `recepientInfo` \(used for the scenario `GooglePayAuthRequest`\)—object with the customer details; this object is used for purchases initiated for debt repayment

|

#### Usage of additional parameters {#section_ihx_qyv_k5b .section}

Besides the required minimum of parameters, the additional ones can be used in requests.

-   `recurrentInfo`—object with the COF purchase information \([details](en_pp_recurring.md#section_hh4_ffj_2mb)\).
-   `paymentDescription` \(string\)—payment description.
-   `regionCode` \(string\)—country code in the format of ISO 3166 alpha-2.
-   `token` \(string\)—payment data token.
-   `forcePaymentMethod` \(string\)—code of the preselected payment method. The codes of payment methods are provided in the corresponding [reference](en_pm_codes.md).
-   `hideSavedWallets` \(boolean\)—parameter that allows setting whether the payment instruments are displayed or not displayed to the customer. Possible values:
    -   `true`—saved payment instruments are not displayed to the customer.
    -   `false`—saved payment instruments are displayed to the customer.

### Additional capabilities {#en_sdk_core_android_additional_capabilities}

#### Saving payment data {#section_qrg_gzv_k5b .section}

During the work with SDK Core for Android, it is possible to save customer payment data for further processing of payments, without this data being re-entered by customers. Payment data can be saved on the customer's initiative or via the tokenisation scenario \(`CardTokenizeRequest`\). While tokenisation is the default capability within the project, the capability of saving payment data on the customer's initiative needs to be set up. To set up the capability of saving payment data, contact the Ecommpay technical support specialists and ensure that the toggle switch for saving data is displayed in the user interface.

As a result of saving payment data on the customer's initiative, a separate identifier \(`account_id`\) is generated for each payment instrument. This identifier is associated with the identifier of a particular customer \(`customer_id`\). These payment instrument identifiers can be received in the notification from SDK Core for Android about the payment session creation and used in the request for payment creation.

If the payment data was saved as a result of the `CardTokenizeRequest` scenario, a token is generated for a certain card of the customer. This token can be received in the notification stating that the token has been generated in the `Payment` object and further specified in payment requests. For executing the tokenisation scenario, the request for creating a session in SDK Core for Android \(initiated on the merchant's side\) should contain the project and customer identifiers, the rest of the details for token generation \(the number and expiration date of the payment card and cardholder name\) should be requested from the customer.

```language-json
"SavedAccounts":
{
  "number": "541333******0019",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // payment data token
  "id": 12353661,   // saved payment data identifier (`accountId`)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+440202267709",
    "country": "GB",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "GB",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },
```

#### 3‑D Secure authentication {#section_ffx_wzv_k5b .section}

When the customer 3‑D Secure authentication is required for payment processing, proceed as follows:

1.  Receive the notification `onThreeDSecure` stating that displaying the authentication page to the customer is required. This notification contains the `acsPage` object with the parameters of displaying the authentication page and the link for redirecting the customer after the authentication.
2.  Display the authentication page to the customer.
3.  Wait for the customer to be redirected from the authentication page and call the `threeDSecureHandled` method.

```language-json
func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // calling method
}
```

#### Cascade payment processing {#section_rv3_ntz_l5b .section}

In case of a payment attempt failure, the capability of cascade payment processing can be used \([details](en_pp_cascading.md)\). This capabilityimplies a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the Ecommpay specialists.

With this capability set up for the project in use and after the first unsuccessful attempt, a notification is received from SDK Core for Android. This notification contains the `isCascading` object with the value `true` which means that an additional attempt is available as part of the cascade payment processing. If the customer authentication is required for processing the payment, the merchant should display the error information to the customer, obtain the customer's confirmation to make another attempt, and retry the payment. If the authentication is not required, no additional actions are performed on the merchant's side.

```language-json
func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}
```

#### Submission of additional payment information {#section_zfq_q1w_k5b .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for initiating this payment. Still in some cases, a payment systemor a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided [in the separate article](en_pp_clarification.md).

The final set of required parameters can vary depending on a particularprovider or payment system. The list of parameters relevant for a particular payment is received in the notification from SDK Core for Android after the request for payment creation \(`GetPayInteractor`\) has been sent. The merchant should ensure that the fields to be filled with the required data are displayed to the customer and then send the obtained values to SDK Core for Android.

```language-json
override fun onClarificationFields(clarificationFields: List<ClarificationField>, payment: Payment) { // receiving the list of the required parameters
    interactor.sendClarificationFields(clarificationFields) // sending the data obtained from the customer
}
```

#### Collection of customer data {#section_cpt_2bw_k5b .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones \(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant should decide which data should be requested and mandatory to be specified by the customers, then provide this information to the technical support specialists. For more information about using the capability of collecting additional data, see [the separate article](en_PP_Gathering_customer_data.md).

After receiving the notification with the list of the required parameters from SDK Core for Android, the merchant should display the fields to be filled by the customer in the payment form, send the obtained data to SDK Core for Android, and continue payment processing.

```language-json
override fun onCustomerFields(customerFields: List<CustomerField>) {  // receiving the list of the required parameters
    interactor.sendCustomerFields(customFields) // sending the data received from the customer
}
```

### Notification receipt {#en_sdk_core_android_callback}

#### Informing about payment session {#section_uw3_zbw_k5b .section}

SDK Core for Android supports sending notifications with the payment session information. Intermediate notifications which are sent during payment session creation fall under the `InitDelegate` group and provide information about various events and possible errors that can happen before the request for payment creation is sent. Such notifications include the following ones:

-   `onInitReceived`—the payment session has been created in the Ecommpay payment platform.

    ```language-json
    override fun onInitReceived() {
        val stringResourceManager = msdkSession.getStringResourceManager()
        val title = stringResourceManager.payment.methodsTitle
      
        val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
      
        val paymentMethods = msdkSession.getPaymentMethods()
        val savedAccounts = msdkSession.getSavedAccounts()
    }
    ```

-   `onPaymentRestored`—the payment session has been created with a payment identifier used previously. If the payment has not been assigned a final status yet, you can use the `PaymentRestoreRequest` method and continue processing the previously initiated payment.

    ```language-json
    override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_payment_restore)
            progressDialog = ProgressDialog(this@PaymentRestoreActivity)
            progressDialog.setMessage("Payment restoring")
            progressDialog.setCancelable(false)
            progressDialog.show()
    
            interactor.execute(PaymentRestoreRequest(), this)
        }
    ```

-   `onError`—an error has occurred.

    ```language-json
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")
    ```


#### Informing about payment {#section_fsj_ncw_k5b .section}

Intermediate and final notifications sent during payment creation fall under the `PayDelegate` group. Such notifications can contain the information about a payment status, the requirement of performing additional actions, and arising errors.

-   `onPaymentCreated`—the payment has been created.
-   `onStatusChanged`—the payment status has been changed.
-   `onCustomerFields`—additional customer data is required.
-   `onThreeDSecure`—3-D Secure authentication is required.
-   `onClarificationFields`—additional payment information is required.
-   `onCompleteWithSuccess`—the payment has been completed.
-   `onCompleteWithFail`—the payment has been rejected.
-   `onCompleteWithDecline`—the payment has been declined.
-   `onError`—an error has occurred.

    ```language-json
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")
    ```


### Error handling {#en_sdk_core_android_error_codes}

In case of errors during request processing, the corresponding notifications are received from SDK Core for Android. Possible errors, their reasons, and actions recommended for the merchant in such cases are provided in the following table.

|Error|Possible reason|Recommended actions|
|-----|---------------|-------------------|
|`CLARIFICATION_FIELDS_ERROR`|Incorrect data was sent during the submission of additional payment information|Resubmit additional information|
|`CUSTOMER_ID_NOT_EXIST`|The required parameter `customerId` was not sent in the request for tokenisation or payment card verification|Correct the request|
|`ILLEGAL_ARGUMENTS`|Incorrect values were sent in the request|Correct the request|
|`INTERACTOR_NOT_RUNNING`|An action available within payment processing was attempted before the payment initiation \(for example, the customer additional data was submitted before the request for payment creation was sent\)|Send the request for payment creation|
|`NETWORK_ERROR`|A connection error occurred|Contact the technical support specialists|
|`NETWORK_IS_NOT_AVAILABLE`|The network is unreachable|Retry the request later|
|`NETWORK_TIMEOUT`|The request processing was declined since a timeout occurred|Retry the request later|
|`PAYMENT_ALREADY_EXIST`|The request processing was declined because the request contains the payment identifier that had been used previously|Specify the identifier that is unique within the project and retry the request|
|`PAYMENT_HAS_FINAL_STATUS`|The request processing was declined because the request contains the identifier of the payment that had been already assigned a final status|Specify the identifier that is unique within the project and retry the request|
|`PAYMENT_METHOD_NOT_AVAILABLE`|The request processing was declined because the request contains the code of a payment method unavailable within the project in use|Specify a payment method available within the project and retry the request|
|`PAYMENT_NOT_FOUND`|The `Payment` object was not found|Retry the request. In case of an error, contact the technical support specialists|
|`PAYMENT_TOKEN_NOT_EXIST`|The request for purchase processing or payment card verification with the use of a token does not contain the token of the payment data|Specify the payment data token and retry the request|
|`SERVER_API_ERROR`|An error occurred on the SDK Core for Android side|Contact the technical support specialists|
|`SESSION_NOT_INITIALIZED`|The request processing was declined due to the attempt of executing a scenario before the payment session creation|Initiate the creation of a payment session \(`InitInteractor`\)|
|`SERVER_CONTENT_PARSING_ERROR`|A server response could not be parsed|Correct the request|
|`SERVER_METHOD_NOT_FOUND`|A method unavailable for the work with SDK Core for Android was called|Correct the request|
|`SERVER_UNAUTHORIZED`|A connection error occurred|Retry the request later|



---

# SDK Core for iOS {#en_sdk_core_ios}

An article about using SDK Core for integrating a payment form with the option to use the in-house interface in iOS mobile applications.

**Parent topic:**[Integration using SDK](en_sdk_overview.md)

## Overview {#en_sdk_core_ios_overview}

### Introduction {#section_jxm_hdx_l5b .section}

Mobile SDK Core for iOS is a software development kit that can be used to integrate iOs applications with the Ecommpay payment platform.

SDK Core for iOS ensures the interaction of a mobile application with the payment platform for sending and receiving necessary information during payment processing. With that, SDK Core for iOS does not insure customer interaction with the user interface—this allows the merchant to use their in-house payment interface during the work with this development kit.

This article provides the information about working with SDK Core for iOS with the description of the interaction workflow, payment processing scenarios, and additional capabilities with code examples in the Swift language.

SDK Core for iOS can be embedded in mobile applications developed for iOS version 11 or later. The libraries of SDK Core for iOS and code examples are provided on GitHub at the following URLs:

-   Libraries for iOS: [https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core/releases](https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core/releases)
-   Code examples: [https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core](https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core)

### Capabilities {#section_ltd_wdx_l5b .section}

SDK Core for iOS supports the work with payment cards and the Apple Pay alternative payment method.The following functional capabilities are supported by SDK Core for iOS:

-   Processing purchases with immediate debiting of funds.
-   Placing an authorisation hold on funds for subsequent debiting of the funds after a certain period expiration or based on the corresponding request from the merchant \(sent via [Gate](en_Gate__cof_merchant_side.md) or [Dashboard](en_dbl_payments.md)\).
-   Verifying payment cards for their subsequent use.
-   Registering COF purchases.
-   Saving payment data for subsequent processing of purchases.

During payment processing, additional actions can be required from customers, for example, for performing 3‑D Secure authentication and specifying the details about the owner of the payment instrument. The applicability of these actions usually depends on the protocols and rules of theproviders and payment systems, however, in some cases, can depend on the merchant's preferences as well. The following procedures and additional capabilities are supported by SDK Core for iOS:

-   3‑D Secure authentication—the procedure of customer authentication with the use of the3‑D Secure protocols.
-   Cascade payment processing—additional payment processing attempts \(used when necessary\) without changing the payment method.
-   Submission of additional payment information—the procedure of specifying additional data that can be required by payment systems in certain cases.
-   Collection of customer data—getting and providing additional customer information that can be relevant for processing subsequent payments.

Setting up the capabilities of cascade payment processing and customer data collection should be coordinated with the Ecommpay specialists.

### Workflow {#section_kxg_zhx_l5b .section}

Generally, purchases with the use of SDK Core for iOS are processed according to the following workflow.

![](images/ecommpay/sdk/ios/en_msdk_core_ios_functional.svg)

1.  The customer initiates a purchase in the user interface of a mobile application by clicking the payment button or by another method set up on the merchant side.
2.  In the mobile application, a set of parameters for creating the payment session is generated. Then, with the help of SDK Core for iOS, this set is converted into a string for signing the parameters and the string is sent to the server side of the merchant's web service.
3.  On the server side of the merchant's web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, after that, the prepared data is sent back toSDK Core for iOS.
4.  With the help of SDK Core for iOS, the payment session creation is initiated in the payment platform.
5.  On the payment platform side, based on the project and customer identifiers, the lists of theavailable payment methods and saved payment data are sent to SDK Core for iOS.
6.  In the mobile application, the information received from SDK Core for iOS is processed and prepared to be further displayed to the customer.
7.  The customerchooses a payment method \(if no method has been set during the payment session opening\), specifies the necessary information, and confirms the purchase.
8.  In the mobile application, a certain scenario of work with SDK Core for iOS is called—with regard to all actions performed by the customer.
9.  The request for processing the purchase according to the called scenario is sent from SDK Core for iOS to the payment platform.
10. On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to theproviders and payment systems.
11. The payment is processed in the payment environment; then the payment result information is received in the payment platform.
12. In the payment platform, the information about the payment result is processed and sent to the server side of the web service.
13. The information about the purchase result is sent from the payment platform to SDK Core for iOS.
14. The notification with the result information is sent from SDK Core for iOS to the mobile application and then is displayed to the customer.

## Setup {#en_sdk_core_ios_setup}

### Integration steps {#section_opr_j3x_l5b .section}

To integrate the web service with the Ecommpay payment platform by using SDK Core for iOS, proceed as follows:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained a project identifier and a secret key for interacting with Ecommpay, submit the application for connecting to the Ecommpay payment platform.
    2.  If the company has obtained a project identifier and a secret key for interacting with Ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK Core for iOS and coordinate the procedure of testing and launching the functionality.
2.  Complete the following preliminary technical tasks:

    1.  Download and link SDK Core for iOS.
    2.  Prepare the user interface and ensure the collection of data necessary for initiating the payment session. The minimum data set needed for the data session creation consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3.  Ensure signature generation for the data on the server side of the mobile application.
    4.  Ensure the receipt of and the response to the notification from SDK Core for iOS as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
3.  Coordinate the procedures and dates of integrating, testing\(including testing available payment methods\), and launching the solution.

    1.  For testing, the test project identifier and the [test cards](en_test_cards.md) details should be used.
    2.  For switching to the production mode, the value of the test project identifier should be changed to the value of the production project identifier received from Ecommpay.

The questions about working with SDK Core for iOS, if any, should be directed to the Ecommpay technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

### Libraries installation {#section_tpr_j3x_l5b .section}

For the mobile applications developed for iOS version 11 or later linking the SDK Core for iOS libraries via CocoaPods is supported. To link the libraries, proceed as follows:

1.  Open the `Podfile` module and add the following code to the module:

    ```language-json
    target 'App' do
        pod 'MsdkCore'
    end
    ```

2.  Run the `pod install` command.
3.  Import the library by running the `import MsdkCore` command.

### Signature generation {#section_bnj_x3x_l5b .section}

Data signing should be performed on the server side of the web service with the use of the secret key received from Ecommpay. To work with the signature, the merchant can use ready-to-use components, such as SDKs for web services in different programming languages \([details](en_sdk_overview.md)\) or the merchant's in-house solutions. The procedure of working with the signature is provided in the section [Signature generation and verification](en_platform_signature.md).

## Testing {#en_sdk_core_ios_testing}

Before processing real payments via SDK Core for iOS, it is recommended to test payment processing in the test project. The merchant can obtain the identifier and the secret key of the test project when accessing the Ecommpay test environment\(this can be done via [an application](https://ecommpay.com/sign-up/) on the company's main site\). Along with that, upon the coordination with the Ecommpay specialists, it is possible to test the usage of the Apple Pay method and additional capabilities, such as cascade payment processing and collection of customer data.

To switch to the test mode, proceed as follows:

1.  Open the project folder and run the `pod install` command.
2.  Open the project via `iosApp.xcworkspace`.
3.  In the `Info.plist` file, specify the identifier \(`PROJECTID`\) and the secret key \(`PROJECT_SECRET_KEY`\) of the test project.

To switch to the production mode, change the test values \(the identifier and the secret key of the test project\) to the production ones.

**Warning:** Do not test Apple Pay payments via SDK Core for iOS on simulated iOS devices. Testing the flow of Apple Pay requires a physical device, as the simulator cannot generate a valid Apple Pay token, which results in payment failures. Any errors observed in a simulation environment are expected and do not reflect the behaviour of a production integration.

## Usage {#en_sdk_core_ios_usage}

SDK Core for iOS supports various targeted actions and, for each of these actions, a certain parameter set is required. The required minimum of parameters is sent in the initial request for creating a payment session; the rest of the parameters can be requested from the customer and received from the payment platform. Based on the received parameters, the request for creating the payment according to one of the available scenarios is generated.

The scenarios, procedures of performing targeted actions, and the set of the parameters available during the work with SDK Core for iOS are provided in the following sections of this article.

### Procedure of performing targeted actions {#en_sdk_core_ios_payment_processing}

SDK Core for iOS supports targeted actions with the direct use of cards and with the use of the Apple Pay alternative method \([details](pm_applepay.md)\). To work with the Apple Pay payment method, the merchant should first contact the Ecommpay technical support specialists to coordinate the method setup.

Generally, to process purchases via SDK Core for iOS, the merchant should do the following:

1.  Create the `MSDKCoreSession` object.

    ```language-json
    let msdkConfig = MSDKCoreSessionConfig.companion.debug(apiHost: "API HOST", wsApiHost: "WS API HOST")
    let msdkSession = MSDKCoreSession(config: msdkConfig)
    ```

2.  Create the `PaymentInfo` object with the parameters of payment processing. This object should contain the required minimum of parameters \(the project identifier, the payment identifier, the payment amount, and the payment currency\), additionally, other parameters can be submitted \([details](en_sdk_core_ios.md#section_kwb_ksx_l5b)\).

    ```language-json
    
    let paymentInfo = PaymentInfo.companion.create // payment information
    (
    projectId: 553,             // project identifier
    paymentId: "payment_21",    // payment identifier
    customerId: "12",           // cutomer identifier
    paymentAmount: 400,         // payment amount
    paymentCurrency: "EUR"      // payment currency code
    )
    
    ```

3.  Receive the string for signing the parameters and send it to the server side of the application.

    ```language-json
    paymentInfo.getParamsForSignature(),
    ```

4.  On the server side of the application, sign the final set of parameters and send it to the client side.
5.  Add the signature to the `PaymentInfo` object.
6.  Send the request for creating the payment session. For this, call the `getInitInteractor` method. For card payments, specifyat least one of the following parameters: the customer's email \(`customerEmail`\) or phone number \(`customerPhone`\).

    At this point, it is also recommended that for 3‑D Secure you should pass the customer's billing address information:

    -   `billingCountry`—the country of the customer's billing address in the ISO 3166-1 alpha-2 format \([details](en_country_codes.md)\)
    -   `billingPostal`—the postal code of the customer's billing address
    -   `billingCity`—the city of the customer's billing address
    -   `billingAddress`—the street of the customer's billing address
    **Note:** [According to Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf), rigorous use of these parameters can significantly increase payment acceptance rates \(up to 6 %\) and drastically decrease the number of operations flagged as fraudulent after they have been processed \(up to 65 %\).

    ```language-json
    let request = InitRequest(
         paymentInfo: paymentInfo,
         recurrentInfo: nil,      
         additionalFields: [  //list of fields for collecting additional information
            "customerEmail": customerEmail,
            "customerPhone": customerPhone
         ] as [String: Any]
    )
    msdkSession.getInitInteractor().execute(
        request: request,
        callback: self
    )
    ```

7.  Receive the notification with the information about the payment session creation and the lists of theavailable payment methods and saved payment data that are relevant for the project in use and a particular customer.

    ```language-json
    func onInitReceived(paymentMethods: \[PaymentMethod\], savedAccounts: [SavedAccount]) {
        let stringResourceManager = msdkSession.getStringResourceManager()
        let title = stringResourceManager?.payment.methodsTitle
              
        let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
              
        let paymentMethods = msdkSession.getPaymentMethods\(\)    // receiving payment method list
        let savedAccounts = msdkSession.getSavedAccounts()    // receivig saved payment data list
    }
    ```

8.  Process the received data and display the payment form to the customer.
9.  To process a purchase via Apple Pay, proceed as follows:
    -   Receive a token from Apple Pay. For this, you can use the `PKPaymentRequest` class that allows interacting with PassKit.

        ```language-json
        let supportedPaymentNetworks = [PKPaymentNetwork.visa, PKPaymentNetwork.masterCard]
        let paymentItem = PKPaymentSummaryItem(label: "MSDK Pay", amount: NSDecimalNumber(value: 1.23))
         
        if PKPaymentAuthorizationViewController.canMakePayments(usingNetworks: supportedPaymentNetworks) {
            let request = PKPaymentRequest()
            request.currencyCode = "EUR"
            request.countryCode = "GB"
            request.merchantIdentifier = "merchant_id"
            request.merchantCapabilities = PKMerchantCapability.capability3DS
            request.supportedNetworks = supportedPaymentNetworks
            request.paymentSummaryItems = [paymentItem]
             
            guard let paymentVC = PKPaymentAuthorizationViewController(paymentRequest: request) else {
                return
            }
            paymentVC.delegate = self
            self.present(paymentVC, animated: true, completion: nil)
        }
        ```

    -   Receive a token in the `PKPaymentAuthorizationViewControllerDelegate` notification.

        ```language-json
        var completion: ((PKPaymentAuthorizationResult) -> Void)?
         
        func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, 
        didAuthorizePayment payment: PKPayment, handler completion: 
        @escaping (PKPaymentAuthorizationResult) -> Void) {
            self.completion = completion
            let token = String(decoding: payment.token.paymentData, as: UTF8.self)
            }
        ```

10. Send the request for payment creation based on the data received from the customer. For this, call the `getPayInteractor` method.

    ```language-json
    // purchase with the use of a card
        override func viewDidLoad() 
    {
        super.viewDidLoad()
        // scenario of purchase processing with the use of a card
        AppDelegate.msdkSession?.getPayInteractor().execute
            (request: NewCardSaleRequest    
                (   cvv: "123",
                    pan: "5413330000000019",
                    expiryDate = CardDate(month = 1, year = 2025),
                    cardHolder: "John Doe",
                    saveCard: false
                ), 
        callback: self)
    }
         
        // purchase with the use of the Apple Pay method    
        AppDelegate.msdkSession?.getPayInteractor\(\).execute
            \(request: ApplePaySaleRequest.init
                \(    token: token    // token received from Apple Pay
                    \), 
        callback: self
    ```

11. Receive a range of notifications from SDK Core for iOS—about the payment creation and the payment status change. If relevant, also accept the notifications stating that the submission of additional payment information and 3‑D Secure authentication are required and perform the needed actions.
12. Receive the notification with the payment information result and display this information to the customer.

During the processing of certain payments, the merchant and the customer are required to perform a range of actions for carrying out certain procedures. The work with such procedures is described in the following sections of this article.

### Parameters of work with SDK Core for iOS {#en_sdk_core_ios_scenarios}

#### Actions with payment cards {#section_i5x_llx_l5b .section}

For performing targeted actions with the direct use of cards, such as purchase processing \(`NewCardSaleRequest`\), authorisation holds on funds \(`CardAuthRequest`\), and card verification \(`CardVerifyRequest`\), the following data sets are used.

|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units \(for card verification use the value `0`\)
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project
-   `register` \(boolean\)—indicator of the COF purchases registration for which the value `true` should be used. The information about the parameters available for registering COF purchases is provided [in the separate article](en_pp_recurring.md)

|-   `cvv` \(string\)—card verification value
-   `pan` \(string\)—card number \(without spaces\)
-   `year` \(integer\)—card expiration year
-   `month` \(integer\)—card expiration month
-   `cardHolder` \(string\)—cardholder name specified on the card
-   `saveCard` \(boolean\)—indicator showing whether the payment card data has been saved

|

#### Tokenisation {#section_b4j_xmx_l5b .section}

SDK Core for iOS supports tokenisation of payment data. When the scenario of tokenisation \(`CardTokenizeRequest`\) is running, no financial operations are performed but a secure identifier associated with the data of a particular payment card is generated. The information about generating and using tokens is provided in the corresponding articles—[Tokenization](en_pp_token.md) and [Payments by using tokens](en_PP_Payment_by_token.md).

For generating tokens via SDK Core for iOS, the following data sets are required.

|Payment session creation|Tokenisation|
|------------------------|------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `customer_id` \(string\)—customer identifier unique within the project

|-   `pan` \(string\)—card number \(without spaces\)
-   `year` \(integer—card expiration year
-   `month` \(integer\)—card expiration month
-   `cardHolder` \(string\)—cardholder name specified on the card

|

#### Usage of saved payment data {#section_ij1_w4x_l5b .section}

SDK Core for iOS supports the capability of saving payment data on the customer initiative and by generating tokens. It also supports using this data for payment processing. With saved payment data and tokens, it is possible to process purchases and place authorisation holds on funds via certain scenarios. In case of saved data, these scenarios are: `SavedCardSaleRequest` \(for processing purchases\) and `SavedCardAuthRequest` \(for placing holds on funds\); in case of tokens, these scenarios are `CardSaleTokenizeRequest` \(for processing purchases\) and `CardAuthTokenizeRequest` \(for placing holds on funds\).

|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project
-   `account_token` \(string\)—payment data token \(for the scenarios where a token is used\)

|-   `cvv` \(string\)—card verification value
-   `accountId` \(integer\)—saved payment data identifier received in the notification about the payment session creation

|

#### Purchases by using alternative methods {#section_i3r_fpx_l5b .section}

SDK Core for iOS supports processing purchases \(`ApplePaySaleRequest`\) and placing holds on funds \(`ApplePayAuthRequest`\) by using the Apple Pay method.

To process purchases with the use of the Apple Pay method, proceed as follows:

1.  In the Apple service, register the merchant identifier \(Merchant ID\) which allows accepting payments by using the Apple Pay method. This identifier remains valid indefinitely and can be used for various web sites and iOS applications. The information about registering this identifier is provided in the Apple documentation: [Create a merchant identifier](https://help.apple.com/developer-account/#/devb2e62b839?sub=dev103e030bb).
2.  Generate an Apple certificate for payment processing \(Payment Processing Certificate\). This certificate is used together with the merchant identifier and ensures the safety of payment data during payment processing via the Apple Pay method. The information about the certificate generation is provided in the Apple documentation: [Create a payment processing certificate](https://help.apple.com/developer-account/#/devb2e62b839?sub=devf31990e3f).
3.  Provide the Ecommpay technical support specialists with the payment processing certificate by using the coordinated methods of protection.
4.  Set up the support of Apple Pay for the mobile application project in the development environment in use.

|Payment session creation|Payment creation|
|------------------------|----------------|
|-   `project_id` \(integer\)—project identifier received from Ecommpay
-   `payment_id` \(string\)—payment identifier unique within the project
-   `payment_amount` \(integer\)—payment amount in minor currency units
-   `payment_currency` \(string\)—payment currency code in the format of ISO 4217 alpha-3
-   `customer_id` \(string\)—customer identifier unique within the project

|-   `token`—token received from Apple Pay
-   `recepientInfo` \(used for the scenario `ApplePayAuthRequest`\)—object with the customer details; this object is used for purchases initiated for debt repayment

|

#### Usage of additional parameters {#section_kwb_ksx_l5b .section}

Besides the required minimum of parameters, the additional ones can be used in requests.

-   `recurrentInfo`—object with the COF purchase information \([details](en_pp_recurring.md)\).
-   `paymentDescription` \(string\)—payment description.
-   `regionCode` \(string\)—country code in the format of ISO 3166 alpha-2.
-   `token` \(string\)—payment data token.
-   `forcePaymentMethod` \(string\)—code of the preselected payment method. The codes of payment methods are provided in the corresponding [reference](en_pm_codes.md).
-   `hideSavedWallets` \(boolean\)—parameter that allows setting whether the payment instruments are displayed or not displayed to the customer. Possible values:
    -   `true`—saved payment instruments are not displayed to the customer.
    -   `false`—saved payment instruments are displayed to the customer.

### Additional capabilities {#en_sdk_core_ios_additional_capabilities}

#### Saving payment data {#section_igj_tsx_l5b .section}

During the work with SDK Core for iOS, it is possible to save customer payment data for further processing of payments, without this data being re-entered by customers. Payment data can be saved on the customer's initiative or with the use of the tokenisation scenario \(`CardTokenizeRequest`\). While tokenisation is the default capability within the project, the capability of saving payment data on the customer's initiative needs to be set up. To set up the capability of saving payment data address the Ecommpay technical support specialists and ensure that the toggle switch for saving data is displayed in the user interface.

As a result of saving payment data on the customer's initiative, a separate identifier \(`account_id`\) is generated for each payment instrument. This identifier is associated with the identifier of a particular customer \(`customer_id`\). These payment instrument identifiers can be received in the notification from SDK Core for iOS about the payment session creation and used in the request for payment creation.

If the payment data was saved as a result of the `CardTokenizeRequest` scenario, a token is generated for a certain card of the customer. This token can be received in the notification stating that the token has been generated in the `Payment` object and further specified in payment requests. For executing the tokenisation scenario, the request for creating a session in SDK Core for iOS \(initiated on the merchant's side\) should contain the project and customer identifiers, the rest of the details for token generation \(the number and expiration date of the payment card and cardholder name\) should be requested from the customer.

```language-json
"SavedAccounts":
{
  "number": "541333******0019",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // payment data token
  "id": 12353661,   // saved payment data identifier (`accountId`)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+440202267709",
    "country": "GB",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "GB",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },
```

#### 3‑D Secure authentication {#section_ops_ztx_l5b .section}

When the customer 3‑D Secure authentication is required for payment processing, proceed as follows:

1.  Receive the notification `onThreeDSecure` stating that displaying the authentication page to the customer is required. This notification contains the `acsPage` object with the parameters of displaying the authentication page and the link for redirecting the customer after the authentication.
2.  Display the authentication page to the customer.
3.  Wait for the customer to be redirected from the authentication page and call the `threeDSecureHandled` method.

```language-json
func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // calling method
}
```

#### Cascade payment processing {#section_rv3_ntz_l5b .section}

In case of a payment attempt failure, the capability of cascade payment processing can be used \([details](en_pp_cascading.md)\). This capability implies a sequence of payment attempts via alternative providerswithout the payment method change and can be set up upon coordination with the Ecommpay specialists.

With this capability set up for the project in use and after the first unsuccessful attempt, a notification is received from SDK Core for iOS. This notification contains the `isCascading` object with the value `true` which means that an additional attempt is available as part of the cascade payment processing. If the customer authentication is required for processing the payment, the merchant should display the error information to the customer, obtain the customer's confirmation to make another attempt, and retry the payment. If the authentication is not required, no additional actions are performed on the merchant's side.

```language-json
func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}
```

#### Submission of additional payment information {#section_p1l_f5x_l5b .section}

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for initiating this payment. Still in some cases, a payment systemor a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided [in the separate article](en_pp_clarification.md).

The final set of required parameters can vary depending on a particularprovider or payment system. The list of parameters relevant for a particular payment is received in the notification from SDK Core for iOS after the request for payment creation \(`GetPayInteractor`\) has been sent. The merchant should ensure that the fields to be filled with the required data are displayed to the customer and then send the obtained values to SDK Core for iOS.

```language-json
func onClarificationFields(clarificationFields: [ClarificationField], payment: Payment) { // receiving the list of required data
    interactor.sendClarificationFields(clarificationFields) // sending the data received from the customer
}
```

#### Collection of customer data {#section_r55_p5x_l5b .section}

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones \(such as phone numbers and email addresses\) from the customers. To have this capability set up, the merchant should decide which data should be requested and mandatory to be specified by the customers, then provide this information to the technical support specialists. For more information about using the capability of collecting additional data, see [the separate article](en_PP_Gathering_customer_data.md).

After receiving the notification with the list of the required parameters from SDK Core for iOS, the merchant should display the fields to be filled by the customer in the payment form, send the obtained data to SDK Core for iOS, and continue payment processing.

```language-json
func onCustomerFields(customerFields: [CustomerField]) { // receiving the list of required data
    interactor.sendCustomerFields(customerFields) // sending the data received from the customer
}
```

### Notification receipt {#en_sdk_core_ios_callback}

#### Informing about payment session {#section_t33_yvx_l5b .section}

SDK Core for iOS supports sending notifications with the payment session information. Intermediate notifications which are sent during the payment session creation fall under the `InitDelegate` group and provide information about various events and possible errors that can happen before the request for payment creation is sent. Such notifications include the following ones:

-   `onInitReceived`—the payment session has been created in the Ecommpay payment platform.

    ```language-json
    func onInitReceived(paymentMethods: \[PaymentMethod\], savedAccounts: [SavedAccount]) {
        let stringResourceManager = msdkSession.getStringResourceManager()
        let title = stringResourceManager?.payment.methodsTitle
             
        let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
             
        let paymentMethods = msdkSession.getPaymentMethods\(\)
        let savedAccounts = msdkSession.getSavedAccounts() ?? []
    }
    ```

-   `onPaymentRestored`—the payment session has been created with the use of a payment identifier used previously. If the payment has not been assigned a final status yet, you can use the `PaymentRestoreRequest` method and continue processing the previously initiated payment.

    ```language-json
    override func viewDidLoad() {
            super.viewDidLoad()
            AppDelegate.msdkSession?.getPayInteractor().execute(request: PaymentRestoreRequest(), callback: self)
        }
    ```

-   `onError`—an error has occurred.

    ```language-json
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")
    ```


#### Informing about payment {#section_bvp_dwx_l5b .section}

Intermediate and final notifications sent during payment creation fall under the `PayDelegate` group. Such notifications can contain the information about a payment status, the requirement of performing additional actions, and arising errors.

-   `onPaymentCreated`—the payment has been created.
-   `onStatusChanged`— the payment status has been changed.
-   `onCustomerFields`—additional customer data is required.
-   `onThreeDSecure`—3‑D Secure authentication is required.
-   `onClarificationFields`—additional payment information is required.
-   `onCompleteWithSuccess`—the payment has been completed.
-   `onCompleteWithFail`—the payment has been rejected.
-   `onCompleteWithDecline`—the payment has been declined.
-   `onError`—an error has occurred.

    ```language-json
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")
    ```


### Error handling {#en_sdk_core_ios_error_codes}

In case of errors during request processing, the corresponding notifications are received from SDK Core for iOS. Possible errors, their reasons, and actions recommended for the merchant in such cases are provided in the following table.

|Error|Possible error|Recommended actions|
|-----|--------------|-------------------|
|`CLARIFICATION_FIELDS_ERROR`|Incorrect data was sent during the submission of additional payment information|Resubmit additional information|
|`CUSTOMER_ID_NOT_EXIST`|The required parameter `customerId` was not sent in the request for tokenisation or payment card verification|Correct the request|
|`ILLEGAL_ARGUMENTS`|Incorrect values were sent in the request|Correct the request|
|`INTERACTOR_NOT_RUNNING`|An action available within payment processing was attempted before the payment initiation \(for example, the customer additional data was submitted before the request for payment creation was sent\)|Send the request for payment creation|
|`NETWORK_ERROR`|A connection error occurred|Contact the technical support specialists|
|`NETWORK_IS_NOT_AVAILABLE`|The network is unreachable|Retry the request later|
|`NETWORK_TIMEOUT`|The request processing was declined since a timeout occurred|Retry the request later|
|`PAYMENT_ALREADY_EXIST`|The request processing was declined because the request contains the payment identifier that had been used previously|Specify the identifier that is unique within the project and retry the request|
|`PAYMENT_HAS_FINAL_STATUS`|The request processing was declined because the request contains the identifier of the payment that had been already assigned a final status|Specify the identifier that is unique within the project and retry the request|
|`PAYMENT_METHOD_NOT_AVAILABLE`|The request processing was declined because the request contains the code of a payment method unavailable within the project in use|Specify a payment method available within the project and retry the request|
|`PAYMENT_NOT_FOUND`|The `Payment` object was not found|Retry the request. In case of an error, contact the technical support specialists|
|`PAYMENT_TOKEN_NOT_EXIST`|The request for purchase processing or payment card verification with the use of a token does not contain the token of the payment data|Specify the payment data token and retry the request|
|`SERVER_API_ERROR`|An error occurred on the SDK Core for iOS side|Contact the technical support specialists|
|`SESSION_NOT_INITIALIZED`|The request processing was declined due to the attempt of executing a scenario before the payment session creation|Initiate the creation of a payment session \(`InitInteractor`\)|
|`SERVER_CONTENT_PARSING_ERROR`|A server response could not be parsed|Correct the request|
|`SERVER_METHOD_NOT_FOUND`|A method unavailable for the work with SDK Core for iOS was called|Correct the request|
|`SERVER_UNAUTHORIZED`|A connection error occurred|Retry the request later|



---

# SDK for C\# on the .NET platform {#en_sdk_net}

An article about using data signing SDKs for web services developed in C\# for .NET.

## Overview {#section_a2f_lpl_m5b .section}

SDK for C\# on the .NET platform is a software development kit for ensuring the interaction of the web services developed in C\# with the Ecommpay payment platform during the processing of purchases via Payment Page. SDK for C\# on the .NET platform is used for signing the parameter set, generating the request for opening Payment Page, verifying callbacks received from Ecommpay, and obtaining payment information from the callbacks.

SDK for C\# on the .NET platform from Ecommpay includes the library source code and other auxiliary files.

SDK for C\# on the .NET platform is compatible with .NET version 6.0 or later and can be downloaded at the following URL: [https://github.com/ITECOMMPAY/paymentpage-sdk-net](https://github.com/ITECOMMPAY/paymentpage-sdk-net).

## Setup {#section_rkn_gql_m5b .section}

To use SDK for C\# on the .NET platform, proceed as follows:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained a project identifier and a secret key for interacting with the Ecommpay payment platform, submit[the application](https://ecommpay.com/apply-now/) for connecting to the payment platform.
    2.  If the company has obtained a project identifier and a secret key for interacting with the Ecommpay payment platform, inform the technical support specialists about the company's intention to integrate by using SDK for C\# on the .NET platform and coordinate the procedure of launching the functionality.
2.  Install the library that is included in SDK for C\# on the .NET platform and link it into the code.

    ```language-csharp
    using ECommPay.PaymentPage.SDK;
    ```

3.  Modify the code for using the necessary functionality.
4.  Coordinate with the Ecommpay technical support specialists the procedures and dates of integrating and launching the solution.

The questions about working with SDK for C\# on the .NET platform, if any, should be directed to the Ecommpay technical support specialists.

## Payment form opening {#section_aj3_h5l_m5b .section}

To open the payment form with the help of SDK for C\# on the .NET platform, proceed as follows:

1.  Ensure that the library included in SDK for C\# on the .NET platform is linked into the web service source code.
2.  Create an object of the `Payment` class and specify the values of the payment parameters.

    ```language-csharp
    dynamic payment = new Payment(<project_id>, "<payment_id_in_your_service>");
    // Project and payment identifiers unique within the project
    payment.payment_amount = 1001;
    // Payment amount in minor currency units
    payment.payment_currency = "EUR";
    // Currency code in the format of ISO-4217 alpha-3
    payment.customer_id = "customer_112";
    // Customer identifier
    payment.payment_description = "Test payment";
    // Payment description (optional parameter)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase. You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-csharp
    payment.customer_phone = "The customer's phone number. Must have from 4 to 24 digits";
    payment.customer_email = "The customer's email";
    ```

    In addition, for card purchases you are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-csharp
    payment.billing_postal = "The postal code of the customer's billing address";
    payment.billing_country = "The country of the customer's billing address, in ISO 3166-1 alpha-2";
    payment.billing_city = "The city of the customer's billing address";
    payment.billing_address = "The street of the customer's billing address";
    ```

    You can also use any other optional parameters available for working with Payment Page \(for more information, see [Payment Page API specification](en_PP_Parameters.md)\).

3.  Create an object of the `Gate` class and specify the secret key value received from Ecommpay. This is necessary for automatic signature generation.

    ```language-csharp
    var gate = new Gate('<secret_key>');
    // Secret key received from Ecommpay
    ```

4.  Generate the URL for opening the payment form.

    ```language-csharp
    var paymentUrl = gate.GetPurchasePaymentPageUrl(payment);
    ```

    A correct URL for opening the payment form contains the signature and the payment parameters.

    ```language-xml
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM
    36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555
    943554067...
    ```

5.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

```language-csharp
namespace MyProject;
 
using ECommPay.PaymentPage.SDK;

public class Example
{
    /// <summary>
    /// Project identifier received from Ecommpay
    /// </summary>
    private const int ProjectId = 0;
 
    /// <summary>
    /// Secret key received from Ecommpay
    /// </summary>
    private const string SecretKey = "secret";
 
    /// <summary>
    /// Return of the URL for payment form opening
    /// </summary>
    /// <returns></returns>
    public static string GetUrl()
    {
        var paymentId = "test_payment"; 
        // Payment identifier unique within the project
        dynamic payment = new Payment(ProjectId, paymentId); 
        // Creation of the Payment object
        payment.payment_amount = 1001;  
        // Payment amount in minor currency units
        payment.payment_currency = "EUR"; 
        // Payment currency code in the format of ISO-4217 alpha-3
        payment.customer_id = "customer_112";
        // Customer identifier
        payment.payment_description = "Test payment"; 
        // Payment description
 
        var gate = new Gate(SecretKey); // Creation of the Gate object
 
        return gate.GetPurchasePaymentPageUrl(payment);
        // Return of the URL for payment form opening
    }
}
```

## Callback processing {#section_okm_rvl_m5b .section}

A callback is an HTTP-POST request that contains payment information in the format of a JSON string. During the work with SDK for C\# on the .NET platform, the information from the callbacks can be obtained with the help of the following methods:

-   `getPaymentId()`—returns the payment identifier.
-   `getPaymentStatus()`—returns the current payment status.
-   `getPayment()`—returns all payment information received in the callback.

To obtain payment information via these methods, proceed as follows:

1.  Ensure that the library included in SDK for C\# on the .NET platform is linked into the web service source code.
2.  If an object of the `Gate` class was not created during the generation of the request for Payment Page opening—create this object and specify the secret key value received from Ecommpay.

    ```language-csharp
    var gate = new Gate('<secret_key>');
    ```

3.  Create an object of the `Callback` class by using the JSON string that contains the payment information and was received in the callback from the Ecommpay payment platform.

    ```language-csharp
    try
    {
        var callback = gate.HandleCallback(data); // Receiving the data verification result
    }
    catch (ValidationException e) // Processing possible exceptions
    {
        Console.WriteLine(e); // Displaying the error message
    }
    ```

4.  Use the necessary method.

    ```language-csharp
    callback.get_payment_id()             // Receiving the payment identifier
    callback.get_payment_status()         // Receiving the current payment status
    callback.get_payment()                // Receiving all payment information
    ```


If SDK for C\# on the .NET platform is used, the verification of the signature from the callback is performed automatically.

```language-csharp
namespace MyProject;
 
using ECommPay.PaymentPage.SDK;
 
public class Example
{
    /// <summary>
    /// Secret key received from Ecommpay
    /// </summary>
    private const string SecretKey = "secret";
 
    /// <summary>
    /// Callback processing
    /// </summary>
    /// <param name="data">JSON string received in the notification.</param>
    /// <returns>true in case of successful callback processing and false in other cases</returns>
    public bool Handler(string data)
    {
        var gate = new Gate(SecretKey); // Creation of the Gate object
        ICallback callback;
 
        // Attempt to receive the processed data
        try
        {
            // Receiving the verification result in the form of the Callback object
            callback = gate.HandleCallback(data);
        }
        // Processing possible exceptions
        catch (SdkException e)
        {
            Console.WriteLine(e); // Displaying the error message
            return false;
        }
 
        // Receiving the Payment object using its identifier
        // var order = OrderRepository.Get(callback.GetPaymentId());
        // Changing the payment status according to the one received in the callback
        // order.SetStatus(callback.GetPaymentStatus());       
        // Saving the changes
        // order.Save();
 
        return true;
    }
}
```

## Related topics {#section_j3l_hyl_m5b .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# SDK for Go {#en_sdk_go}

An article about using data signing SDKs for web services developed in Go.

SDK for Go is a software development kit for development of web services which are capable of integrating with the Ecommpay payment solutions to perform purchases by using Payment Page. This section describes how to use SDK for Go to build purchase experience from inside of your web service.

SDK for Go is compatible with Go version 1.8 or later.You can download SDK for Go from Git: [https://github.com/ITECOMMPAY/paymentpage-sdk-go](https://github.com/ITECOMMPAY/paymentpage-sdk-go).

## What can I do with SDK for Go? {#section_mdv_1pf_nhb .section}

SDK for Go allows you to do the following:

-   Calculate signature and generate an URL for opening the Payment Page.
-   Check callback signatures and extract payment details from callbacks.

## What's inside? {#section_myx_rk2_phb .section}

SDK for Go contains the libraries for development and automated testing, as well as the service files.

## Using SDK for Go {#section_ow5_sdb_mhb .section}

To start using SDK for Go you need to complete the following tasks:

1.  Make sure you have ready your merchant ID and secret key obtained from Ecommpay.
    1.  If your company has never obtained any ID or secret key from Ecommpay, you need to submit an applicationat [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/) for connecting to the Ecommpay payment platform.
    2.  If your company already has an ID and a secret key to sign messages obtained from Ecommpay, you need to notify the Ecommpay technical support specialists that you want to use SDK for Go and consult the customer support on how to arrange a test run.
2.  Integrate the Ecommpay payment solution in your web service:
    1.  Install the SDK for Go libraries into a directory inside your web service project.
    2.  Import the libraries you need into your web service application.
3.  Test and put your web service in production mode.
    1.  Request test card numbers and test project ID from Ecommpay, debug and test your web service.
    2.  Once testing is complete, request your production project ID from Ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for Go, contact the Ecommpay technical support specialists at [support@ecommpay.com](mailto:support@ecommpay.com).

## Installing and importing libraries {#section_y13_j32_nhb .section}

You can install the SDK for Go libraries manually or by using automated procedures supported by the development environment you use.

The following steps describe how to manually install the SDK for Go libraries.

1.  If no $GOPATH environment variable is set, you need to set one. The $GOPATH is used to specify directories outside of $GOROOT that contains the source for Go projects and their binaries.
2.  Run the following command in the command line of your operating system:

    ```language-php
    go get github.com/ITECOMMPAY/paymentpage-sdk-go
    ```

    The command downloads the SDK for Go libraries in the $GOPATH directory to enable you to use all the classes provided by the libraries.

3.  Import the SDK for Go into your web service source code in `import` section by running the following command:

    ```go
    import "github.com/ITECOMMPAY/paymentpage-sdk-go"
    ```


## Opening payment form {#section_bty_ryn_lhb .section}

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Ecommpay payment platform. SDK for Go allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for Go do the following:

1.  Create an instance of the `payment` class and specify payment details.

    ```language-php
    payment := paymentpage.NewPayment(186, "TEST_1555943554067")
              // Project ID and payment ID, must be unique within your project scope
    payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
              // Currency in the ISO-4217 alpha-3 format
    payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
              // Amount in minor currency units
    payment.SetParam(paymentpage.ParamCustomerId, "customer_122")
              // Customer ID
    payment.SetParam(paymentpage.ParamPaymentDescription, "Test payment")
              // Payment description (optional)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase.You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-php
    payment.SetParam(paymentpage.ParamCustomerPhone, "The customer's phone number. Must have from 4 to 24 digits")
    payment.SetParam(paymentpage.ParamCustomerEmail, "The customer's email")
    ```

    In addition, for card purchasesyou are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-php
    payment.SetParam(paymentpage.ParamBillingPostal, "The postal code of the customer's billing address")
    payment.SetParam(paymentpage.ParamBillingCountry, "The country of the customer's billing address, in ISO 3166-1 alpha-2")
    payment.SetParam(paymentpage.ParamBillingCity, "The city of the customer's billing address")
    payment.SetParam(paymentpage.ParamBillingAddress, "The street of the customer's billing address")
    ```

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see [Payment Page API specification](en_PP_Parameters.md).

2.  Create a `gate` instance and initiate it with the secret key you obtained from the Ecommpay technical support specialists. The secret key is required to sign parameters.

    ```language-php
    gate := paymentpage.NewGate("<*secret\_key*>")
       // Secret key you obtained from the technical support service
    ```

3.  Generate the URL for opening the payment form:

    ```language-php
    paymentPageUrl := gate.GetPaymentPageUrl(*payment)
    ```

    The URL must contain payment parameters and signature \(abbreviated\):

    ```language-php
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
    ```

4.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

Here is an example of generating a URL for opening a payment form in English.The payment method selection page includes detailed payment information including amount, currency, and short payment description.

```language-php
payment := paymentpage.NewPayment(186, "test_payment_id")
    // Project ID and payment ID, must be unique within your project scope
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Amount in minor currency units
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Currency in the ISO-4217 alpha-3 format
payment.SetParam(paymentpage.ParamCustomerId, "customer_122")
          // Customer ID
payment.SetParam(paymentpage.ParamPaymentDescription, "Test payment")
    // Payment description (optional)
payment.SetParam(paymentpage.ParamLanguageCode, "en")
    // Language code to use in payment form
gate := paymentpage.NewGate("<*secret\_key*")
    // Secret key
paymentPageUrl := gate.GetPaymentPageUrl(*payment)
    // Complete request with signature
```

## Processing callbacks {#section_qxm_m24_lhb .section}

The Ecommpay payment platform sends payment results to the callback URL you specified when connecting to Ecommpay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from the response JSON string, do the following:

1.  Create an instance of `gate` and initiate it with the secret key if you did not do it earlier:

    ```language-php
    gate := paymentpage.NewGate("<*secret\_key*>")
    ```

2.  Create an instance of `callback` by using the JSON string from the callback obtained from the Ecommpay payment platform:

    ```language-php
    callback, err := gate.HandleCallback(data)
    ```

    If signature is incorrect or extracting payment details from callback results in errors, an `error` instance is returned.

3.  Use the following methods for extracting callback information. You can get either full payment information or request specific payment parameters:

    ```language-php
    callback.GetPaymentId()             // Getting payment ID
    callback.GetPaymentStatus()         // Getting payment status
    callback.GetPayment()               // Getting payment body
    ```

    By using SDK for Go, you can automatically check validity of the callback signature. Below, you can find an example of a callback that includes a signature and payment results.


```
{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }
```

## Related links {#section_skw_c12_phb .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# SDK for Java {#en_sdk_java}

An article about using data signing SDKs for web services developed in Java.

SDK for Java is a software development kit for development of web services which are capable of integrating with the Ecommpay payment solutions to perform purchases by using Payment Page. This section describes how to use SDK for Java to build purchase experience from inside of your web service.

SDK for Java is compatible with Java SE Development Kit 8 or higher.You can download SDK for Java from GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-java](https://github.com/ITECOMMPAY/paymentpage-sdk-java).

## What can I do with SDK for Java? {#section_mdv_1pf_nhb .section}

SDK for Java allows you to do the following:

-   Calculate signature and generate an URL for opening the Payment Page.
-   Check callback signatures and extract payment details from callbacks

## What's inside? {#section_myx_rk2_phb .section}

SDK for Java contains the following:

-   **Libraries**for development and automated testing
-   **Code samples** in Java

## Using SDK for Java {#section_ow5_sdb_mhb .section}

To start using SDK for Java you need to complete the following tasks:

1.  Make sure you have you have ready your merchant ID and secret key obtained from Ecommpay.
    1.  If your company has never obtained any ID or secret key from Ecommpay, you need to submit an application for connecting to the Ecommpay payment platformat [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/).
    2.  If your company already has an ID and a secret key to sign messages obtained from Ecommpay, you need to notify the Ecommpay technical support specialists that you want to use SDK for Java and consult the customer support on how to arrange a test run.
2.  Integrate the Ecommpay payment solution in your web service:
    1.  Install the SDK for Java libraries into a directory inside your web service project.
    2.  Import the libraries you need into your web service application.
3.  Test and put your web service in production mode.
    1.  Request test card numbers and test project ID from Ecommpay, debug and test your web service.
    2.  Once testing is complete, request your production project ID from Ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for Java contact the Ecommpay technical support specialists at [support@ecommpay.com](mailto:support@ecommpay.com).

## Installing and importing libraries {#section_y13_j32_nhb .section}

You can install the SDK for Java libraries manually or by using automated procedures supported by the development environment you use.

The following steps describe how to manually install the SDK for Java libraries.

1.  Download SDK for Java and pack the SDK files into a JAR file.
2.  If your project directory does not contain a **libs** directory, create one and move the JAR file into the **libs** directory.
3.  Import the file into your web service project by using the procedures pertinent to your development environment.

## Opening payment form {#section_bty_ryn_lhb .section}

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Ecommpay payment platform. SDK for Java allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for Java do the following:

1.  Create an instance of the `Payment` class and specify payment details.

    ```language-java
    Payment payment = new Payment('186', "pid_1555943554067");
                 // Project ID and payment ID
                 // Payment ID must be unique within your project scope
    payment
          .setParam(Payment.PAYMENT_AMOUNT, 1001) // Amount in minor currency units
          .setParam(Payment.PAYMENT_CURRENCY, "EUR"); // Currency as per ISO-4217 alpha-3
          .setParam(Payment.CUSTOMER_ID, "customer_112") // Customer ID
          .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment"); // Payment description (optional)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase.You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-java
    .setParam(Payment.CUSTOMER_PHONE, "The customer's phone number. Must have from 4 to 24 digits")
    .setParam(Payment.CUSTOMER_EMAIL, "The customer's email")
    ```

    In addition, for card purchasesyou are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-java
    .setParam(Payment.BILLING_POSTAL, "The postal code of the customer's billing address")
    .setParam(Payment.BILLING_COUNTRY, "The country of the customer's billing address, in ISO 3166-1 alpha-2t")
    .setParam(Payment.BILLING_CITY, "The city of the customer's billing address")
    .setParam(Payment.BILLING_ADDRESS, "The street of the customer's billing address")
    ```

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see [Payment Page API specification](en_PP_Parameters.md).

2.  Create a `gate` instance and initiate it with the secret key you obtained from the Ecommpay technical support specialists. The secret key is required to sign parameters.

    ```language-java
    Gate gate = new Gate("<*secret\_key*>");
       // Secret key you obtained from technical support service
    ```

3.  Generate the URL for opening the payment form:

    ```language-java
    String paymentUrl = gate.getPurchasePaymentPageUrl(payment);
    ```

    The URL must contain payment parameters and signature \(abbreviated\):

    ```language-java
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
    ```

4.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

Here is an example of generating a URL for opening a payment form in English.The payment method selection page includes detailed payment information including amount, currency, and short payment description.

```language-java
Payment payment = new Payment('186', "pid_1555943554067");
	 // Project ID and payment ID
	 // Payment ID must be unique within your project scope
payment
       .setParam(Payment.PAYMENT_AMOUNT, 1001)     // Amount in minor currency units
       .setParam(Payment.PAYMENT_CURRENCY, "EUR"); // Currency
       .setParam(Payment.CUSTOMER_ID, "customer_112") // Customer ID
	 .setParam(Payment.PAYMENT_DESCRIPTION, "Test payment");  // Payment description
	 .setParam(Payment.LANGUAGE_CODE, ("en");     // Language code to use in payment form
Gate gate = new Gate("<*secret\_key*>");   // Secret key
String paymentUrl = gate.getPurchasePaymentPageUrl(payment);  // Complete request with signature
```

## Using the test mode {#section_xv4_3k1_g5b .section}

When working with the SDK for Java, you can use the test mode. It allows you to check completeness and correctness of specified parameters and get information about errors if there were any.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to `sdk.ecommpay.com`. This allows you to specify various parameters to open the payment form as part of the testing activities \(you will be able to use both test and production parameters\) and to analyse error information. Use the following code:

```language-java
Payment payment = new Payment(<project_id>, "<payment_id_in_your_service>");
payment.payment_amount = 1001;
payment.payment_currency = "EUR";
payment.payment_description = "Test payment";
 
Gate gate = new Gate('<secret_key>');
 
try {
    return gate.getPurchasePaymentPageUrl(payment);  
    // Receiving the URL to open the payment form
} catch (ValidationException e) { // Validating possible exceptions
    System.out.println(e); // Error message output
}
 
return null;
```

Information about the errors that occurred in testing is provided in error messages as follows:

```language-java
One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified
```

If there are no errors, then the generated URL for opening Payment Page is correct.

## Processing callbacks {#section_qxm_m24_lhb .section}

The Ecommpay payment platform sends payment results to the callback URL you specified when connecting to Ecommpay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from JSON string do the following:

1.  Create an instance of `Gate` with the secret key if you did not do it earlier.

    ```language-java
    Gate gate = new Gate("<*secret\_key*>");
    ```

2.  Create an instance of `Callback` by using the JSON string from the callback obtained from the Ecommpay payment platform:

    ```language-java
    Callback callback = gate.handleCallback(data);
    ```

3.  Use methods for extracting callback information. You can get either full payment information or request specific payment parameters:

    ```language-java
    callback.getPaymentId();             // Getting payment ID
    callback.getPaymentStatus();         // Getting payment status
    callback.getPayment();               // Getting payment body
    ```

    By using SDK for Java, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.


```
{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1001,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1001,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1001,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }
```

## Related links {#section_skw_c12_phb .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# SDK for JavaScript {#en_sdk_javascript}

An article about using data signing SDKs for web services developed in JavaScript.

SDK for JavaScript is a software development kit for development of web services which are capable of integrating with the Ecommpay payment solutions to perform purchases by using Payment Page. This section describes how to use SDK for JavaScript to build purchase experience from inside of your web service.

SDK for JavaScript is compatible with the Node.js 4.x runtime environment for executing JavaScript code.You can download SDK for JavaScript from GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-js](https://github.com/ITECOMMPAY/paymentpage-sdk-js).

## What can I do with SDK for JavaScript? {#section_mdv_1pf_nhb .section}

SDK for JavaScript allows you to do the following:

-   Calculate signature and generate an URL for opening the Payment Page.
-   Check callback signature and extract payment details from callbacks

## What's inside? {#section_rlb_55f_nhb .section}

SDK for JavaScript contains the following:

-   **src**—a library for development
-   **\_tests\_**—a library for automatic testing

## Using SDK for JavaScript {#section_ow5_sdb_mhb .section}

To start using SDK for JavaScript you need to complete the following tasks:

1.  Make sure you have you have ready your merchant ID and secret key obtained from Ecommpay.
    1.  If your company has never obtained any ID or secret key from Ecommpay, you need to submit an application for connecting to the Ecommpay payment platformat [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/).
    2.  If your company already has an ID and a secret key to sign messages obtained from Ecommpay, you need to notify the Ecommpay technical support specialists that you want to use SDK for JavaScript and consult the customer support on how to arrange a test run.
2.  Integrate the Ecommpay payment solution in your web service:
    1.  Install the SDK for JavaScript libraries into a directory inside your web service project.
    2.  Import the libraries you need into your web service application.
3.  Test and put your web service in production mode.
    -   Use test merchant ID and test values for payment parameters from the **\_tests\_** library.
    -   Once testing is complete, request your production merchant ID from Ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for JavaScript contact the Ecommpay technical support specialists at [support@ecommpay.com](mailto:support@ecommpay.com).

## Installing and importing libraries {#section_y13_j32_nhb .section}

You can install the SDK for JavaScript libraries manually or automatically with Yarn or npm, package-management systems used to install and manage software packages written in JavaScript.

The following steps describe how to install the SDK for JavaScript libraries by using Yarn or npm:

1.  If you have not yet installed a package-management system, you need to download, install and check settings. For more information, see:
    -   Yarn: [https://yarnpkg.com/en/docs/getting-started](https://yarnpkg.com/en/docs/getting-started)
    -   npm: [https://www.npmjs.com/package/ecommpay](https://www.npmjs.com/package/ecommpay)
2.  Navigate into the web service source code directory in command line and run one of the following commands:

    ```language-javascript
    npm install ecommpay // for npm
    yarn add ecommpay    // for Yarn
    ```

    A package-management system automatically downloads the SDK for JavaScript libraries in the source code directory to enable you to use all the modules provided by the libraries.

3.  Import the modules into your web service project:

    ```language-javascript
    const { Payment } = require('ecommpay');
    const { Callback } = require('ecommpay');
    
    ```


## Opening payment form {#section_bty_ryn_lhb .section}

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Ecommpay payment platform. SDK for JavaScript allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for JavaScript do the following:

1.  Create an instance of the `Payment` class and specify payment details and the secret key you obtained from the Ecommpay technical support specialists. The secret key is required to sign parameters.

    ```language-javascript
    const e = new Payment('186', '<*secret\_key*>');
            // Project ID and Secret key
    e.paymentId = 'TEST_1555943554067';
            // Payment ID must be unique within your project scope
    e.paymentAmount = 1000;
            // Amount in minor currency units
    e.paymentCurrency = 'EUR';
            // Currency in ISO-4217 alpha-3 format
    e.customerId = 'customer_112';
            // Customer ID
    e.paymentDescription = 'Payment description';
           // Payment description (optional)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase.You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-javascript
    e.paymentCustomerPhone = 'The customer phone number. Must have from 4 to 24 digits';
    e.paymentCustomerEmail = 'The customer email';
    ```

    In addition, for card purchasesyou are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-javascript
    e.paymentBillingPostal = 'The postal code of the customer billing address';
    e.paymentBillingCountry = 'The country of the customer billing address, in ISO 3166-1 alpha-2';
    e.paymentBillingCity = 'The city of the customer billing address';
    e.paymentBillingAddress = 'The street of the customer billing address';
    ```

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see [Payment Page API specification](en_PP_Parameters.md).

2.  Generate the URL for opening the payment form:

    ```language-javascript
    const url = e.getUrl();
    ```

    The URL must contain payment parameters and signature \(abbreviated\):

    ```language-javascript
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
    ```

3.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

Here is an example of generating a URL for opening a payment form in English.The payment method selection page includes detailed payment information including amount, currency, and short payment description.

```language-javascript
const e = new Payment('186', '<*secret\_key*>');
        // Project ID and Secret key
e.paymentId = 'TEST_1555943554067';
        // Payment ID must be unique within your project scope
e.paymentAmount = 1000;
        // Amount in minor currency units
e.paymentCurrency = 'EUR';
        // Currency in ISO-4217 alpha-3 format
e.customerId = 'customer_112';
        // Customer ID
e.paymentDescription = 'Payment description';
       // Payment description (optional)
e.language_code: 'EN';
       // Language code to use in payment form
const url = e.getUrl();
       // Complete request with signature
```

## Processing callbacks {#section_qxm_m24_lhb .section}

The Ecommpay payment platform sends payment results to the callback URL you specified when connecting to Ecommpay. Callback is an HTTP POST request that contains response data in JSON format in the `req.body` object. To extract payment information from JSON string, do the following:

1.  Create an instance of `Callback` by using the secret key and the JSON string from the callback obtained from the Ecommpay payment platform:

    ```language-javascript
    const callback = new Callback(<*secret\_key*>, req.body);
    ```

2.  The following example contains the methods for extracting callback information in the source code that uses the Express framework:

    ```language-javascript
    app.post('/payment/callback', function(req, res) {
      const callback = new Callback(<*secret\_key*>, req.body);
      if (callback.isPaymentSuccess()) {
        const paymentCont = callback.payment(); // Getting information about the payment
        const paymentId = callback.getPaymentId(); // Getting payment ID
    
        // Add your code for proccessing successful payment
      }
    });
    ```


By using SDK for JavaScript, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

```
{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }
```

## Related links {#section_skw_c12_phb .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# SDK for PHP {#en_sdk_php}

An article about using data signing SDKs for web services developed in PHP.

SDK for PHP is a software development kit for development of web services which are capable of integrating with the Ecommpay payment solutions to perform purchase by using Payment Page. This section describes how to use SDK for PHP to build purchase experience from inside of your web service.

SDK for PHP is compatible with PHP version 7.0 or higher.You can download SDK for PHP from GitHubor Packagist:

-   GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-php](https://github.com/ITECOMMPAY/paymentpage-sdk-php)
-   Packagist: [https://packagist.org/packages/ecommpay/paymentpage-sdk](https://packagist.org/packages/ecommpay/paymentpage-sdk)

## What can I do with SDK for PHP? {#section_mdv_1pf_nhb .section}

SDK for PHP allows you to do the following:

-   Calculate signature and generate an URL for opening the Payment Page.
-   Check callback signature and extract payment details from callbacks.

## What's inside? {#section_rlb_55f_nhb .section}

SDK for PHP contains the following:

-   **src**—a library for development
-   **tests**—a library for automatic testing
-   **composer.json**—a script for importing libraries
-   **The service files**

## Using SDK for PHP {#section_ow5_sdb_mhb .section}

To start using SDK for PHP you need to complete the following tasks:

1.  Make sure you have ready your merchant ID and secret key obtained from Ecommpay:
    1.  If your company has never obtained any ID or secret key from Ecommpay, you need to submit an application for connecting to the Ecommpay payment platformat [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/).
    2.  If your company already has an ID and a secret key to sign messages obtained from Ecommpay, you need to notify Ecommpay customer support that you want to use SDK for PHP and consult the customer support on how to arrange a test run.
2.  Integrate the Ecommpay payment solution in your web service:
    1.  Install the SDK for PHP libraries into a directory inside your web service project.
    2.  Import the libraries you need into your web service application.
3.  Test and put your web service in production mode.
    -   Use test merchant ID and test values for payment parameters from the **tests** library.
    -   Once testing is complete, request your production merchant ID from Ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for PHP contact the Ecommpay technical support specialists at [support@ecommpay.com](mailto:support@ecommpay.com).

## Installing and importing libraries {#section_y13_j32_nhb .section}

You can install the SDK for PHP libraries manuallyor automatically with Composer, a dependency manager for PHP programming language. Composer can download and install the libraries required for a project, as well as generate a script for importing the libraries.

The following steps describe how to install the SDK for PHP libraries by using Composer:

1.  If you have not yet installed Composer, you need to download, install and check settings. For more information, see [https://getcomposer.org/](https://getcomposer.org/).
2.  Navigate into the web service source code directory in command line interface and run the following command:

    ```language-php
    composer require ecommpay/paymentpage-sdk
    ```

    Composer automatically downloads the SDK for PHP in the **vendor** sub-directory and creates the **autoload.php** script required to enable you to use all the classes provided by the libraries.

3.  Include the **autoload.php** script into your web service project:

    ```php
    require __DIR__.'../../vendor.autoload.php';
    ```


## Opening payment form {#section_bty_ryn_lhb .section}

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Ecommpay payment platform. SDK for PHP allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for PHP do the following:

1.  Create an instance of the `Payment` class and specify payment details.

    ```language-php
    $payment = new ecommpay\Payment('186', 'TEST_1555943554067');
        // Project ID and payment ID and payment ID must be unique within your project scope
    $payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
        // Amount in minor currency units and currency in the ISO-4217 alpha-3 format
    $payment->setCustomerId('customer007');
        // Customer ID
    $payment->setPaymentDescription('Test payment');
        // Payment description (optional)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase.You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-php
    $payment->setCustomerPhone('The customer phone number. Must have from 4 to 24 digits');
    $payment->setCustomerEmail('The customer email');
    ```

    In addition, for card purchasesyou are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-php
    $payment->setBillingPostal('The postal code of the customer billing address');
    $payment->setBillingCountry('The country of the customer billing address, in ISO 3166-1 alpha-2');
    $payment->setBillingCity('The city of the customer billing address');
    $payment->setBillingAddress('The street of the customer billing address');
    ```

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see [Payment Page API specification](en_PP_Parameters.md).

2.  Create a `gate` instance and initiate it with the secret key you obtained from the Ecommpay technical support specialists. The secret key is required to sign parameters.

    ```language-php
    $gate = new ecommpay\Gate('<*secret\_key*>');
        // Secret key you obtained from the technical support service
    ```

3.  Generate the URL for opening the payment form:

    ```language-php
    $url = $gate->getPurchasePaymentPageUrl($payment);
    ```

    The URL must contain payment parameters and signature \(abbreviated\):

    ```language-php
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
    ```

4.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

Here is an example of generating a URL for opening a payment form in English.The payment method selection page includes detailed payment information including amount, currency, and short payment description while the data input page includes a countdown timer.

```language-php
$gate = new ecommpay\Gate('<*secret\_key*>');
    // Secret key
$payment = new ecommpay\Payment('186', 'TEST_1555943554067');
    // Project ID and payment ID and payment ID must be unique within your project scope
$payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
    // Amount in minor currency units and currency in ISO-4217 alpha-3 format
$payment->setCustomerId('customer007');
    // Customer ID
$payment->setPaymentDescription('Test payment');
    // Payment description
$payment->setBestBefore(new \DateTime('2050-01-01 00:00:00 +0000'));
    // Date and time for timer countdown
$payment->setLanguageCode('en');
    // Language code to use in payment form
$url = $gate->getPurchasePaymentPageUrl($payment);
    // Complete request with signature
```

## Using the test mode {#section_l2r_2l1_g5b .section}

When working with the SDK for PHP, you can use the test mode. It allows you to check completeness and correctness of specified parameters and get information about errors if there were any.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to `sdk.ecommpay.com` and that your PHP interpreter meets at least one of the following requirements:

-   It supports the `curl` library \([more](https://www.php.net/manual/en/book.curl.php)\).
-   It supports the `sockets` library with the HTTP access to the URL \([more](https://www.php.net/manual/en/book.sockets.php)\).
-   The directive `allow_fopen_url` is set to `true` and the HTTP access to the URL is supported \([more](https://www.php.net/manual/en/function.fopen.php)\).

This will allow you to specify various parameters to open the payment form as part of the testing activities \(you will be able to use both test and production parameters\) and to analyse error information. Use the following code:

```language-php
$payment = new Payment(<project_id>, '<payment_id_in_your_service>');
$payment->setPaymentAmount(1000)
    ->setPaymentCurrency('EUR')
    ->setPaymentDescription('Test payment')
$gate = new Gate('<secret_key>');
 
try {
    return $gate->getPaymentPageUrl($payment); 
    // Receiving the URL to open the payment form
} catch (ValidationException $e) { // Validating possible exceptions
    error_log($e->getFormattedMessage()); // Logging the error message
}
 
return null;
```

Information about the errors that occurred in testing is provided in error messages as follows:

```language-php
One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified
```

If there are no errors, then the generated URL for opening Payment Page is correct.

## Processing callbacks {#section_qxm_m24_lhb .section}

The Ecommpay payment platform sends payment results to the callback URL you specified when connecting to Ecommpay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from a JSON string do the following:

1.  Create an instance of `Gate` with the secret key, if you did not it earlier.

    ```language-php
    $gate = new ecommpay\Gate('<*secret\_key*>');
    ```

2.  Create an instance of `Callback` by using the JSON string from the callback obtained from the Ecommpay payment platform:

    ```language-php
    $callback = $gate->handleCallback($data);
    ```

3.  Use the following methods to obtain the callback information. You can get either full payment information or request specific payment parameters:

    ```language-php
    Callback::getPaymentId();            // Getting payment ID
    Callback::getPaymentStatus();        // Getting payment status
    Callback::getPayment();              // Getting payment body
    ```


By using SDK for PHP, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

```
{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }
```

## Related links {#section_skw_c12_phb .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# SDK for Python {#en_sdk_python}

An article about using data signing SDKs for web services developed in Python.

SDK for Python is a software development kit for development of web services which are capable of integrating with the Ecommpay payment solutions to perform purchase by using Payment Page. This section describes how to use SDK for Python to build purchase experience from inside of your web service.

SDK for Python is compatible with Python version 3.5 or higher.You can download SDK for Python from GitHubor PyPI:

-   GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-python](https://github.com/ITECOMMPAY/paymentpage-sdk-python)
-   PyPI: [https://pypi.org/project/ecommpay-sdk/](https://pypi.org/project/ecommpay-sdk/)

## What can I do with SDK for Python? {#section_mdv_1pf_nhb .section}

SDK for Python allows you to do the following:

-   Calculate signature and generate an URL for opening the Payment Page.
-   Check callback signature and extract payment details from callbacks.

## What's inside? {#section_rlb_55f_nhb .section}

SDK for Python contains the libraries for development and automated testing, as well as the service files.

## Using SDK for Python {#section_ow5_sdb_mhb .section}

To start using SDK for Python you need to complete the following tasks:

1.  Make sure you have you have ready your merchant ID and secret key obtained from Ecommpay:
    1.  If your company has never obtained any ID or secret key from Ecommpay, you need to submit an application for connecting to the Ecommpay payment platformat [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/).
    2.  If your company already has an ID and a secret key to sign messages obtained from Ecommpay, you need to notify the Ecommpay technical support that you want to use SDK for Python and consult the customer support on how to arrange a test run.
2.  Integrate the Ecommpay payment solution in your web service:
    1.  Install the SDK for Python libraries.
    2.  Import the libraries you need into your web service application.
3.  Test and put your web service in production mode.
    -   Use test merchant ID and test values for payment parameters from the **tests** library.
    -   Once testing is complete, request your production merchant ID from Ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for Python, contact Ecommpay the technical support specialists at [support@ecommpay.com](mailto:support@ecommpay.com).

## Installing and importing libraries {#section_y13_j32_nhb .section}

You can install the SDK for Python libraries manually or automatically with pip, a package-management system used to install and manage software packages written in [Python](https://en.wikipedia.org/wiki/Python_(programming_language)).

The following steps describe how to install the SDK for Python libraries by using pip:

1.  If you have not yet installed pip, you need to download, install and check settings. For more information, see [https://pip.pypa.io/en/stable/](https://pip.pypa.io/en/stable/).
2.  Navigate into the web service directory in command line interface and run the following command:

    ```language-python
    pip install ecommpay-sdk
    ```

    Pip automatically downloads the SDK for Python libraries in the **Scripts** directory to enable you to use all the classes provided by the libraries.

3.  Import the classes into your web service project:

    ```language-python
    from payment_page_sdk.gate import Gate
    from payment_page_sdk.payment import Payment
    ```


## Opening payment form {#section_bty_ryn_lhb .section}

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the Ecommpay payment platform. SDK for Python allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for Python do the following:

1.  Create an instance of the Payment class and specify payment details.

    ```language-python
    payment = Payment('186', 'TEST_1555943554067')
        // Project ID and payment ID and payment ID must be unique within your project scope
    payment.payment_amount = 1001
        // Amount in minor currency units
    payment.payment_currency = 'EUR'
        //  Currency in ISO-4217 alpha-3 format
    payment.customer_id = 'customer_112'  
        // Customer ID
    payment.payment_description = 'Test payment'
        // Payment description (optional)
    ```

    All parameters in this example, except for the payment description, are mandatory for any purchase.You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    ```language-python
    payment.customer_phone = 'The customer phone number. Must have from 4 to 24 digits'
    payment.customer_email = 'The customer email'
    ```

    In addition, for card purchasesyou are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 \([details](en_country_codes.md)\), the postal code, the city, and the street address. Such parameters are specified as follows.

    ```language-python
    payment.billing_postal = 'The postal code of the customer billing address'
    payment.billing_country = 'The country of the customer billing address, in ISO 3166-1 alpha-2'
    payment.billing_city = 'The city of the customer billing address'
    payment.billing_address = 'The street of the customer billing address'
    ```

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see [Payment Page API specification](en_PP_Parameters.md).

2.  Create a `gate` instance and initiate it with the secret key you obtained from Ecommpay. The secret key is required to sign parameters.

    ```language-python
    gate = Gate('<*secret\_key*>')
        // Secret key you obtained from technical support service
    ```

3.  Generate the URL for opening the payment form:

    ```language-python
    payment_url = gate.get_purchase_payment_page_url(payment)
    ```

    The URL must contain payment parameters and signature \(abbreviated\):

    ```language-python
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
    ```

4.  Use the generated URL for opening the payment form \([details](en_PP_Integration.md)\).

Here is an example of generating a URL for opening a payment form in English.The payment method selection page includes detailed payment information including amount, currency, and short payment description.

```language-python
payment = Payment('186', 'TEST_1555943554067')
    // Project ID and payment ID and payment ID must be unique within your project scope
payment.payment_amount = 1001
payment.payment_currency = 'EUR'  
    // Amount in minor currency units and currency in ISO-4217 alpha-3 format
payment.customer_id = 'customer_112'  
    // Customer ID
payment.payment_description = 'Test payment'
    // Payment description
payment.language_code = 'en'
    // Language code to use in payment form
gate = Gate('<*secret\_key*>')    
    // Secret key
payment_url = gate.get_purchase_payment_page_url(payment)
    // Complete request with signature
```

## Using the test mode {#section_s5f_rq1_g5b .section}

When working with the SDK for Python, you can use the test mode. It allows you to check completeness and correctness of specified parameters and get information about errors if there were any.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to `sdk.ecommpay.com`. This allows you to specify various parameters to open the payment form as part of the testing activities \(you will be able to use both test and production parameters\) and to analyse error information. Use the following code:

```language-python
payment = Payment(<project_id>, "<payment_id_in_your_service>")
payment.payment_amount = 1001
payment.payment_currency = 'EUR'
payment.payment_description = 'Test payment'
 
gate = Gate("<secret_key>")
 
try:  # Attempting to execute the code
    return gate.get_purchase_payment_page_url(payment)  
    # Receiving the URL to opent the payment form
except ValidationException as e:  # Validating possible exceptions
    print(e)  # Displaying error messages in the console
 
return null
```

Information about the errors that occurred in testing is provided in error messages as follows:

```language-php
One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified
```

If there are no errors, then the generated URL for opening Payment Page is correct.

## Processing callbacks {#section_qxm_m24_lhb .section}

The Ecommpay payment platform sends payment results to the callback URL you specified when connecting to Ecommpay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from the JSON string do the following:

1.  Create an instance of `Gate` with the secret key, if you did not it earlier.

    ```language-python
    gate = Gate('<*secret\_key*>')
    ```

2.  Create an instance of `Callback` by using the JSON string from the callback obtained from the Ecommpay payment platform:

    ```language-python
    callback = gate.handle_callback(data)
    ```

3.  Use the following methods for extracting callback information. You can get either full payment information or request specific payment parameters:

    ```language-python
    callback.get_payment_id()            // Getting payment ID
    callback.get_payment_status()        // Getting payment status
    callback.get_payment()               // Getting payment body
    ```


By using SDK for Python, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

```language-json
{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1001,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056 ",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1001,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1001,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }
```

## Related links {#section_skw_c12_phb .section}

-   [Handling callbacks](en_platform_callbacks.md)
-   [Payment processing](en_platform_payment_model.md)

**Parent topic:**[Integration using SDK](en_sdk_overview.md)



---

# Integration using plug-ins {#en_CMS}

Articles about using plug-ins for embedding Payment Page into websites powered by various CMS and specialised platforms.

Modern content management systems\(CMSs\)and specialised platforms allow you to launch, maintain, and further develop the web services for your business quickly and efficiently. For the easiest possible integration of such web services with the payment platform, Ecommpay provides merchants with the specialised integration modules—plug-ins.With each plug-in, you can promptly connect your web service created in a popular system to the Ecommpay platform and process payments using the Payment Page payment form, with all necessary interactions between the web service and the payment platform set up.

The Ecommpay plug-ins allow integrating the platform and web services that operate with the use of the following systems:

-   [BigCommerce](en_cms_bigcommerce.md)
-   [commercetools](en_cms_commercetools.md)with the use of the Composable Commerce solution
-   [Magento](en_CMS__magento.md) version 2.2 or later
-   [PrestaShop](en_cms_prestashop.md) version 8.1.5 or later
-   [WordPress](en_CMS__wordpress.md) version6.2or later

If you have any questions regarding the usage of the Ecommpay plug-ins or suggestions as to how their functionality can be expanded and enhanced, contact your Ecommpay account manager. With questions about integrating, testing, and using these plug-ins, contact the technical support specialists.

-   **[Using Ecommpay Payments plug-in for the BigCommerce platform](en_cms_bigcommerce.md)**  
An article about using a plug-in for embedding Payment Page into websites powered by the BigCommerce platform.
-   **[Using plug-in from Ecommpay for commercetools](en_cms_commercetools.md)**  
An article about using a plug-in for embedding Payment Page into websites powered by the commercetools platform.
-   **[Using plug-in from Ecommpay for Magento CMS](en_CMS__magento.md)**  
An article about using a plug-in for embedding Payment Page into websites powered by the Magento CMS platform.
-   **[Using Ecommpay payments for PrestaShop CMS](en_cms_prestashop.md)**  
An article about using a plug-in for embedding Payment Page into websites powered by the PrestaShop CMS platform.
-   **[Using Ecommpay Payments plug-in for WordPress CMS](en_CMS__wordpress.md)**  
An article about using a plug-in for embedding Payment Page into websites powered by the WordPress CMS platform with the installed WooCommerce plug-in.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# Using Ecommpay Payments plug-in for the BigCommerce platform {#en_cms_bigcommerce}

An article about using a plug-in for embedding Payment Page into websites powered by the BigCommerce platform.

**Parent topic:**[Integration using plug-ins](en_CMS.md)

## Overview {#en_cms_bigcommerce_overview}

This article covers the information about using the payment plug-in Ecommpay Payments. This plug-in can be used in the web services developed on the basis of the BigCommerce platform.

The Ecommpay Payments plug-in is installed via the plug-ins directory [Apps&Integrations](https://www.bigcommerce.com/apps/) and the administrative interface BigCommerce and allows opening the Payment Page payment form of Ecommpay for customers. The plug-in also allows you to ensure all necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform \(with all necessary information sent and received\).

Technically, the plug-in is deployed in the Ecommpay payment platform and the interaction between the web service and the plug-in builds via a network connection between them.Thus, an up-to-date plug-in's version is always available in the web service.

![](images/universal/cms/bigcommerce/cms_bigcommerce_orders_overview.png "Administrative interface BigCommerce")

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_pp_embedded1.png "Interface of the Payment Page payment form")

## General information {#en_cms_bigcommerce_general}

### Capabilities {#section_ksx_npx_1bc .section}

With the Ecommpay Payments plug-in, the following is available:

-   Setting up the capability to open the Payment Page payment form of Ecommpay in the web service.

    For this, you only need to install the plug-in from Ecommpay and set up its usage in the BigCommerce CMS interface.

-   Setting up the use of various payment methods available via the plug-in.

    For this, you can use the corresponding accordion items located on the page with the parameters of the plug-in operation in the BigCommerce interface. Technically, for setting up different payment methods, you may need to either configure a minimum of the plug-in parameters in the BigCommerce interface, while all organisational issues can be resolved in cooperation with the Ecommpay account manager.

-   Configuring the plug-in for use with different web services.

    When working with several web services based on the BigCommerce platform, you can configure the plug-in individually for each web service.

-   Testing the operation of the payment form and the capabilities of payment processing.

    For this, you should get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\) and enable the test mode of the plug-in operation via the BigCommerce interface.

-   Processing one-time one-step and two-step purchases.

    For this, you can use the methods that support the corresponding payment type.Along with that, for two-step purchases, the funds being withdrawn can be not only the entire authorised amount but also a part of this amount.

-   Issuing partial and full refunds for purchases, which were processed with the help of the plug-in.

    For this, you can use the BigCommerce interface and, if relevant, the interfaces of the Ecommpay payment platform \(the user interface Dashboard and the Gate API\). Keep in mind that, for information to be updated in the BigCommerce interface in cases of refunds via the payment platform interfaces, the settings of callbacks to be sent from Ecommpay must be configured \([details](en_dbl_projects.md)\).

-   Monitoring the information about payments processed with the help of the plug-in.

    For this, you can use the BigCommerce interface and, if relevant—the Dashboard interface from Ecommpay.

-   Managing orders with related purchases processed with the help of the plug-in—via the BigCommerce interface.

    This includes cancelling these orders and changing their statuses manually. Also keep in mind that automatic change of the orders' statuses is not supported by default but can be set up by the merchant's specialists with the use of capabilities of the BigCommerce platform and with the use of in-house or third-party solutions.

-   Configuring the parameters of the Payment Page operation and adjusting the form to the web service specifics, as well as using various capabilities provided by Ecommpay.

    During the work with the Ecommpay Payments plug-in, you can use most of the capabilities of the payment form \([details](en_PP_Additional.md)\), except for separate capabilities, such as payments by using tokens. Particularly, you can use the payment confirmation procedure when working with Open Banking methods,provide customers with the capability of payment retries \([details](en_PP_Try_Again.md)\), and set up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\). To have these capabilities set up, contact the Ecommpay technical support specialists.


Such a range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure high rates of payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists.

### Workflows {#section_hdz_dlg_vyb .section}

The following diagrams illustrate the workflows of executing one-time one-step and two-step purchases with the use of the Ecommpay Payments plug-in. The workflows involve the customer, the merchant's web service with the built-in plug-in, the Payment Page payment form, the payment platform, and the payment environment. On the web service side, the opening of Payment Page is requested and automatic interaction with the payment platform is carried out in accordance with the plug-in parameters.

In case of *one-step purchases*, one initial request leads to a one-time transfer of funds from the customer to the merchant which is followed by a callback with the information about the payment result sent to the web service.

![](images/universal/cms/en_cms_workflow.svg)

1.  On the web service side, the customer opens the checkout pageand selects a payment method available via the Ecommpay Payments plug-in.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, for processing the paymentwith use of the select payment method.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions and confirms the purchase.
8.  The final purchase request \(with all necessary data\) is received in the platform.
9.  The request is sent to the payment environment.
10. The request is processed in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, the 3‑D Secure authentication\).
11. The purchase result information is sent from the payment environment to the payment platform.
12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the payment information is updated in the BigCommerce interface.
13. The purchase result information is sent from the payment platform to Payment Page.
14. The purchase result information is displayed to the customer in the merchant's web service on the page with the information about the paid order.

In case of *two-step purchases*, based on an initial request \(at the first step\), the funds are held on the customer's account and then \(at the second step\), based on the next request or automatically after a specified period of time, the funds are transferred to the merchant or released. Along with that, at each step, a callback with the information about the corresponding result is sent to the web service.

![](images/universal/cms/en_cms_workflow_auth.svg)

1.  On the web service side, the customer opens the checkout pageand selects a payment method available via the Ecommpay Payments plug-in.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, for processing the paymentwith use of the select payment method.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions and confirms the purchase.
8.  The request for authorisation hold is received in the platform.
9.  The request is sent to the payment environment.
10. The payment is processed and the funds are authorised in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, the 3‑D Secure authentication\).
11. The information about the authorisation hold result is sent from the payment environment to the payment platform.
12. The callback with the information about the authorisation hold result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the payment information is updated in the BigCommerce interface.
13. The information about the authorisation hold result is sent from the payment platform to Payment Page.
14. The information about the authorisation hold result is displayed to the customer in the merchant's web service on the page with the information about the paid order.
15. After it has been confirmed that the funds should be withdrawn, the merchant's specialist initiates the withdrawal, and as result, a request for withdrawing the funds is received and processed in the payment platform \(which is done with the help of the plug-in\).
16. The request is sent to the payment environment.
17. The payment is processed in the payment environment.
18. The information about the withdrawal result is sent from the payment environment to the payment platform.
19. The callback with the information about the withdrawal result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the payment information is updated in the BigCommerce interface.
20. The customer is notified about the withdrawal result by the means of the web service.

For interaction with customers when processing one-step purchases and placing authorisation hold on funds for two-step purchases, the following options can be applied:

-   with the payment form embedded directly into the web service interface\(in an iframe element\);
-   with the payment form opened in a separate tab.

The first of these options is available only for purchases with the direct use of payment cards and is used for such purchases by default. In case of this option, the customer specifies payment card credentials and confirms the order, which is generated in the BigCommerce platform, and the payment, which is generated in the Ecommpay platform, directly on the checkout page of the web service\(using the **Place Order** button\).

The second of these options is used for all alternative payment methods and for purchases with the direct use of payment cards if these purchases are made with the payment form opened in a separate tab.In case of this option, the customer first confirms that they are ready to proceed to payment\(using the **Place Order** button in the web service\) and only after that specifies the necessary data in the payment form and confirms the order, which is generated in the BigCommerce platform, and the payment, which is generated in the Ecommpay platform, \(using the **Pay** button\).

Along with that, the following aspects should be considered:

-   Regardless of the option of opening Payment Page, the interface language of the payment form is selected according to the established workflow \([details](en_PP_WigetLanguages.md#section_x4l_1hb_sqb)\).
-   If the capability of [payment retries](en_PP_Try_Again.md) has been set up for the project, it is important to use the option with Payment Page opened in a separate tab.For the option of embedding the form in the web service interface, the capability to proceed to another payment attempt directly in the payment form is not supported.
-   Orders in the web service and payments in the payment platform have different identifiers and statuses.Orders are assigned ordinal numbers \(for example, `151`\) and statuses used by BigCommerce \([details](https://support.bigcommerce.com/s/article/Order-Statuses?language=en_US)\), while payments on the payment platform side are assigned identifiers that consist of thirty two random characters \(for example, `5876281a-4129-4fad-86ae-f1a24f637c7f`\) and statuses used by Ecommpay \([details](en_platform_payment_model.md)\). With questions about the statuses of payments and orders, contact the Ecommpay account manager.

## Installation {#en_cms_bigcommerce_installation}

To start working with the Ecommpay Payments plug-in, you need to install it. The plug-in can be installed vie the plug-ins directory \([Apps&Integrations](https://www.bigcommerce.com/apps/)\) and the administrative interface of the BigCommerce platform.

1.  Open [the plug-in page](https://www.bigcommerce.com/apps/ecommpay-payments/) in the **Apps&Integrations** directory and click the **Get this app** button.

    ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_get_app.png "Plug-in page in the Apps&Integrations directory")

2.  Select one of the suggested options—register in the BigCommerce platform\(if this has not been done\) or authenticate to the platform.
3.  Click the **Download** button on the page for downloading the Ecommpay Payments plug-in in the BigCommerce interface, in the **Marketplace** subsection of the **Apps** section.
4.  Open the **My Apps** subsection of the **Apps** section and click the **Install** button on the plug-in panel.

As a result of these actions, a network connection between the web service and the Ecommpay Payments plug-in is established and an up-to-date plug-in version is available in the web service.

**Note:** If you have more than one web service that operates on the basis of the BigCommerce platform and need to use the Ecommpay Payments plug-in for several of them, you have to configure the plug-in operation parameters for each of the relevant web services.

## Testing {#en_cms_bigcommerce_testing}

### Overview {#section_tp4_m4r_bbc .section}

Testing the plug-in operation and various payment scenarios without actual debiting of funds is possible via the test environment of the Ecommpay payment platform with the use of the plug-in test mode. You can connect to the platform by using the corresponding form [on the company's main site](https://ecommpay.com/apply-now/) and the identifier and key of the test project received from Ecommpay. Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service, for which the Ecommpay Payments plug-in should be used, the web service URL, and the payment currency if you want to process test payments in a particular currency.

Keep in mind that when you use the testing environment of the Ecommpay payment platform, the plug-in will be connected to the web service and will become available as a payment option to the customers. Therefore, it is recommended that if you need to connect the plug-in to the web service in production mode, test the plug-in operation during the low-load time and warn your customers about planned maintenance.

### Parameters setup {#section_s3d_x4r_bbc .section}

To prepare the Ecommpay Payments plug-in for testing, *activate it* as a payment option in the web service and *set up the parameters* of its operation.When working with several web services, configure the plug-in operation parameters for each of them individually.

To activate the plug-in in the web service, proceed as follows:

1.  Go to the parameters of payment options in the BigCommerce interface.

    For this, select the **Settings** section in the navigation menu and click the **Payments** line in the **Setup** section on the page that opens.

2.  Select one of the available payment options to enable the plug-in.

    For this, open the **Offline Payment Methods** accordion item in the **Additional providers** section and click the **Set up** button in the line of the appropriate payment option \(**Bank Deposit**or another method\).

    ![](images/universal/cms/bigcommerce/cms_bigcommerce_offline_pm.png "Additional providers section in the BigCommerce interface")

3.  Specify `Ecommpay` in the **Display Name** field on the page that opens and save the changes by clicking the **Save** button.

    ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings.png "Page with parameters for using a payment option in the BigCommerce interface")


To set up the plug-in operation parameters, proceed as follows:

1.  Go to the plug-in operation parameters in the BigCommerce interface.

    For this, select the **Apps** section and then—the **Ecommpay Payments** item in the navigation menu.

2.  Go over the key operation parameters of the plug-in and modify them if necessary:
    -   **Plugin Enabled**—the availability in the web service\(must be enabled\).

        If this toggle switch is off, then all payment methods previously set up for working via the plug-in become available in the web service. If this toggle switch is on, then all payment methods set up for working via the plug-in are unavailable for payment processing.

    -   **Store Channel**—the name of the merchant web service in the BigCommerce platform \(select a web service for which you need to set up the parameters of the plug-in\).
    -   **Mode**—the plug-in operation mode\(the **test** option must be selected\).
    -   **Test Project ID**—the test project identifier for interacting with the platform\(must be the one received from Ecommpay\).
    -   **Test Secret Key**—the secret key for the test project\(must be the one received from Ecommpay\).
    -   **Merchant Callback Url**—the URL for receiving callbacks from the payment platform\(the value is generated and specified automatically during the installation of the Ecommpay Payments plug-in\).
    -   **Host Url**—the domain name of the merchant web servicefor which the parameters of the plug-in are set up \(must be specified manually\).
    -   **Payment Mode**—the option for processing payments via the payment platform.

        One of the following options can be selected:

        -   **Sale**—for one-step purchases \(with immediate debiting of funds\)
        -   **Authorization Only**—for two-step purchases \(with debiting after authorisation hold\)
        The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases \(such as Apple Pay, Google Pay, and card payments\).

3.  Set up the parameters for using payment methods \([details](en_cms_bigcommerce.md)\).

**Warning:** The parameters **Test Project ID** and **Test Secret Key** must be specified. Otherwise, processing of payments via the plug-in test mode is not supported.

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_general.png "Section with the basic parameters of the plug-in operation in the BigCommerce interface")

### Processing test purchases {#section_etj_4ts_q5b .section}

When testing the plug-in operation, you can process test purchases in the web service and obtain information about them via the BigCommerce interface—in the **View** subsection of the **Orders** section. Along with that, you can use special payment credentials that allow testing particular payment scenarios.

For testing card payments according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used:

-   `4000 0000 0000 0077`—for a purchase to be processed
-   `4111 1111 1111 1111`—for a purchase to be declined

For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article.

To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the corresponding sections of the articles about working with particular payment methods.

During the processing of two-step purchases, the first step, the authorisation hold, is initiated by the customer when they confirm the purchase, while the second step, the withdrawal of the authorised amount or the release of funds, can be initiated automatically, after the time allocated for the funds to remain authorised expires, or manually via the BigCommerce interface or via the interfaces of the Ecommpay payment platform—Dashboard \([details](en_dbl_payments.md)\) and the Gate API \([details](en_gate_payment_auth.md)\). Along with that, it is possible to withdraw not only the entire authorised amount but also a part of this amount.

To initiate the second step of a two-step purchase via the BigCommerce interface, proceed as follows:

1.  Open the orders register in the BigCommerce interface.

    For this open the **View** subsection of the **Orders** section.

2.  Open the panel with data about a two-step purchase as part of a particular order.

    For this, click the ![](images/universal/cms/bigcommerce/icon_dots.png) button in the **Action** column in the orders register and select the Ecommpay item in the drop-down list.

3.  Initiate the second step of the two-step purchase via the panel with payment data.

    To initiate the debiting of authorised funds, specify the amount for debiting and click the **Capture** button in the corresponding section. To release the authorised amount, click the **Void** button in the corresponding section.


![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_auth.png "Panel with the sections Capture and Void in the orders register of the BigCommerce interface")

To have the automatic initiation of the second step set up, contact the Ecommpay technical support specialists.

For the information about payments to be automatically updated in the BigCommerce interface, if the second step of a two-step purchase is initiated via a payment platform interface, ensure that, for the project in use, the settings of callbacks to be sent from the payment platform have been configured. Along with that, it is important that, for a single payment type, there are no several sets of conditions with the same values of event typesand payment method codes set up. The information about working with callback settings is provided [in the corresponding article of this documentation](en_dbl_projects.md).

**Note:** According to the requirements of the global card networks, the time allocated for holding the funds is limited on the Ecommpay platform side \([details](en_pp_purchase_auth.md#section_hgy_djl_ylb)\).If this time expires and the funds are not withdrawn or released, the payment is automatically declined in the payment platform.

### Processing test refunds {#section_sfw_tj1_cbc .section}

After processing test purchases, you can make test refunds via the BigCommerce interface and, if relevant, via the Dashboard and Gate interfaces in the Ecommpay platform. Also keep in mind that refunds can be made for payments that have been assigned the statuses `success`, `partially reversed`, or `partially refunded` on the payment platform side.The information about refunds can be monitored with the use of the platform interfaces and the BigCommerce interface.

For the information about payments to be automatically updated in the BigCommerce interface in cases of test refunds made via the payment platform interfaces, ensure that, for the project in use, the settings of callbacks to be sent from the payment platform have been configured.Along with that, it is important that, for a single payment type, there are no several sets of conditions with the same values of event typesand payment method codes set up. The information about working with callback settings is provided [in the corresponding article of this documentation](en_dbl_projects.md).

To make a refund via the BigCommerce interface, proceed as follows:

1.  Open the orders register in the BigCommerce interface.

    For this, open the **View** subsection of the **Orders** section.

2.  Open the panel with the payment data from the payment platform.

    For this, click the ![](images/universal/cms/bigcommerce/icon_dots.png) button in the **Action** column and select the **Ecommpay** item.

3.  Initiate the refund.

    For this, specify the amount and the reason for refund and click the **Refund** button in the corresponding section.

4.  Ensure that the refund has been made.

    For this, you can check that the operation information has been updated on the panel with the payment data.


![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_refund.png "Panel with the Refund section in the orders register of the BigCommerce interface")

## Usage {#en_cms_bigcommerce_usage}

### General information {#section_zh5_xv1_cbc .section}

In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web service for which the Ecommpay Payments plug-in is installed and the currency in which payments are to be processed.

After that, you can switch the plug-in to the production mode, specify the receivedidentifier and secret key in the parameters of the plug-in operation and set up other necessary parameters\(or check whether the current setup is relevant for working in real-life conditions\). If, after the setup, you need to suspend the plug-in operation, for example, to test some additional features, the plug-in can be switched to the test mode or disabled.

**Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page.

### Parameters setup {#section_mkk_dw1_cbc .section}

To prepare the Ecommpay Payments plug-in for work, *activate it* as a payment option in the web service and *set up the parameters* of its operation.When working with several web services, configure the plug-in operation parameters for each of them individually. Keep in mind that if the plug-in has been activated for test payments, you do not need to reactivate it, but you should modify the configuration settings as necessary \([details](en_cms_bigcommerce.md#ol_igh_2w1_cbc)\).

To activate the plug-in the web service, proceed as follows:

1.  Go to the parameters of payment options in the BigCommerce interface.

    For this, select the **Settings** section in the navigation menu and click the **Payments** line in the **Setup** section on the page that opens.

2.  Select one of the available payment options to enable the plug-in.

    For this, open the **Offline Payment Methods** accordion item in the **Additional providers** section and click the **Set up** button in the line of the appropriate payment option \(**Bank Deposit**or another method\).

    ![](images/universal/cms/bigcommerce/cms_bigcommerce_offline_pm.png "Additional providers section in the BigCommerce interface")

3.  Specify `Ecommpay` in the **Display Name** field on the page that opens and save the changes by clicking the **Save** button.

    ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings.png "Page with parameters for using a payment option in the BigCommerce interface")


To set up the plug-in operation parameters, proceed as follows:

1.  Go to the plug-in operation parameters in the BigCommerce interface.

    For this, select the **Apps** section, the select the Ecommpay Payments item in the navigation menu.

2.  Go over the key operation parameters of the plug-in and modify them if necessary:
    -   **Plugin Enabled**—the availability in the web service\(must be enabled\).

        If this toggle switch is off, then all payment methods previously set up for working via the plug-in become available in the web service. If this toggle switch is on, then all payment methods set up for working via the plug-in are unavailable for payment processing.

    -   **Store Channel**—the name of the merchant web service in the BigCommerce platform \(select a web service for which you need to set up the parameters of the plug-in\).
    -   **Mode**—the plug-in operation mode\(the **live** option must be selected\).
    -   **Project ID**—the project identifier for interacting with the platform\(must be the one received from Ecommpay\).
    -   **Secret Key**—the secret key for the project\(must be the one received from Ecommpay\).
    -   **Merchant Callback Url**—the URL for receiving callbacks from the payment platform\(the value is generated and specified automatically during the installation of the Ecommpay Payments plug-in\).
    -   **Host Url**—the domain name of the merchant web servicefor which the parameters of the plug-in are set up \(must be specified manually\).
    -   **Payment Mode**—the option for processing payments via the payment platform.

        One of the following options can be selected:

        -   **Sale**—for one-step purchases \(with immediate debiting of funds\)
        -   **Authorization Only**—for two-step purchases \(with debiting after authorisation hold\)
        The first option is supported for all payment methods available via the plug-in, the second option—only for the methods that support two-step purchases \(such as Apple Pay, Google Pay, and card payments\).

3.  Set up the parameters for using payment methods \([details](en_cms_bigcommerce.md)\).

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_general_live.png "Section with the basic parameters of the plug-in operation in the BigCommerce interface")

### Issuing refunds {#section_my1_5x1_cbc .section}

For purchases processed with the use of the Ecommpay Payments plug-in, you can make partial and full refunds via the BigCommerce interface and, if relevant, via the interfaces Dashboard\(with the tools for sending individual and batch requests; [details](en_dbl_payments.md)\) and the Gate API\([details](en_Gate_Refund.md)\) from Ecommpay—for payments with the statuses `success`, `partially reversed`, or `partially refunded` on the payment platform side.All relevant information about refunds and the corresponding payments can be obtained via the BigCommerce interface and the interfaces of the payment platform.

**Warning:** For the information about payments to be automatically updated in the BigCommerce interface in cases of refunds made via the payment platform interfaces, ensure that, for the project in use, the settings of callbacks to be sent from the payment platform have been configured.Along with that, it is important that, for a single payment type, there are no several sets of conditions with the same values of event typesand payment method codes set up. The information about working with callback settings is provided [in the corresponding article of this documentation](en_dbl_projects.md).

To issue a refund via the BigCommerce interface, proceed as follows:

1.  Open the orders register in the BigCommerce interface.

    For this, open the **View** subsection of the **Orders** section.

2.  Open the panel with the payment data from the payment platform.

    For this, click the ![](images/universal/cms/bigcommerce/icon_dots.png) button in the **Action** column and select the **Ecommpay** item.

3.  Initiate the refund.

    For this, specify the amount and the reason for refund and click the **Refund** button in the corresponding section.

4.  Ensure that the refund has been made.

    For this, you can check that the operation information has been updated on the panel with the payment data.


![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_refund.png "Panel with the Refund section in the orders register of the BigCommerce interface")

### Monitoring payments and orders {#section_zhp_ty1_cbc .section}

Information about payments processed with the use of the Ecommpay Payments plug-in and about the corresponding orders can be monitored via the BigCommerce interface, with the use of the tools of the **View** subsection in the **Orders** section.

Additionally, the payment information can be obtained via the Dashboard interface from Ecommpay \([details](en_dbl_payments.md)\).This interface provides the information about payments and refunds processed via the Ecommpay payment platform, but it does not display information about orders.

The **View** subsection of the **Orders** section contains a register with information about every order. Along with that, the orders register provides various functions for working with orders including the capabilities of searching and filtering data and obtaining payment information within separate orders.

![](images/universal/cms/bigcommerce/cms_bigcommerce_orders.png "Orders register in the BigCommerce interface")

To obtain more detailed information about an order, click the ![](images/universal/cms/bigcommerce/icon_plus.png) button in corresponding column of the register. This leads to opening a panel which contains such information as the customer's address, the creation date and amount of the order and other information.

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_order_details.png "Accordion item with order information in the BigCommerce interface")

The **Billing** section of the panel displays the name of the organisation through which the processing of payments with the use of the selected method takes placewith the name of the payment method \(in the field with the ![](images/universal/cms/bigcommerce/icon_method.png) icon\) and the payment identifier \(in the field with the ![](images/universal/cms/bigcommerce/icon_id.png) icon\). To obtain more detailed information about the payment, click the ![](images/universal/cms/bigcommerce/icon_dots.png) button in the **Action** column and the Ecommpay item in the drop-down list. The panel that opens displays the **Order Details** section with information about the payment and can display the following sections \(if the corresponding functions are available within the selected order\):

-   **Capture**—with the capability to initiate debiting of authorised funds as part of a two-step purchase
-   **Void**—with the capability to release the authorised funds as part of a two-step purchase
-   **Refund**—with the capability to initiate a refund as part of a purchase

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_payment.png "Panel with the Order Details section in the BigCommerce interface")

More information about working with orders in the BigCommerce interface is provided [in the BigCommerce documentation](https://support.bigcommerce.com/s/article/Orders?language=en_US).

## Parameters for using payment methods {#en_cms_bigcommerce_methods}

When working with the Ecommpay Payments plug-in, in the BigCommerce interface, you can set up the usage of various payment methods available in the merchant's project. You can do this via expandable accordion itemsin the section with the plug-in parameters—such as **Card Payments** \(with parameters for card payments\), **Alternative payment settings** \(with parameters for various alternative methods\), or **More payment methods** \(with parameters for using all methods set up in the project\).

**Note:** Accordion items displayed by default cannot be removed from the plug-in parameters even if the corresponding methods are not used in the project. If other methods are needed, their usage can be set up only via the **More payment methods** accordion item once the Ecommpay technical support specialists enable these methods in the project upon the merchant's request.

In the expandable accordion items, you can set up the following parameters for using payment methods:

-   **Enabled**—the feature for enabling a payment method to work via the plug-in.
-   **Title**—the payment method namedisplayed on the checkout page in the web service.
-   **Display mode**—the option for opening Payment Page.

    This parameter is used only in the accordion item for card payments. In this parameter, you can select **Embedded** or **Redirected** for opening the payment form in an iframe element or as an HTML page accordingly. If the **Embedded** option is selected, the **Decription** and **Show Description** parameters are not displayed in the accordion item for card payments.

-   **Description**—the text displayed to the customers when they select a certain payment method.
-   **Show Description**—the feature for displaying the text from the **Description** parameter.
-   **Payment method code**—the code of a payment method which is used as an additional method \(in relation to the methods which are set up via separate tabs\).

    This parameter is used only in the **More payment methods** accordion item.

    -   Without this parameter used, when the customer selects a purchase method in the web service interface, they can select the **More payment methods** option \(the exact wording of the option name can be specified in the **Title** field of the **More payment methods** accordion item\), proceed to the payment form, and select one of the methods available for the payment being initiated in the Ecommpay platform.Along with that, all methods from Ecommpay that can be selected directly in the web service \(together with the **More payment methods** option\) become available in the payment form.
    -   With this parameter containing the code of one of the available methods\(taken [from the reference](en_pm_codes.md)\), when the customer selects a purchase method in the web service interface, among other available methods, they can select the one specified via the code and proceed to paying via this method without selecting any other methods in the payment form.To prevent issues that may be triggered by such a selection, alongside the payment method code, the name of the method should also be specified in this section \(in the **Title** field\).

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings_card.png "Accordion item with parameters for card payments in the BigCommerce interface")

![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings_apay.png "Accordion item with parameters for the Apple Pay method in the BigCommerce interface")



---

# Using plug-in from Ecommpay for commercetools {#en_cms_commercetools}

An article about using a plug-in for embedding Payment Page into websites powered by the commercetools platform.

**Parent topic:**[Integration using plug-ins](en_CMS.md)

## Overview {#en_cms_commercetools_overview}

This article covers the information about using the payment plug-in from Ecommpay for the commercetools platform. The plug-in version 1.0 can be applied in the web services that operate with the use of the Composable Commerce solution from commercetools.

The plug-in from Ecommpay is installed either on the merchant's local server or in a cloud service \(such as AWS Lambda, Azure Functions, or Google Cloud Functions\) and allows automatic generation of URLs for opening the Payment Page payment form. The plug-in also allows you to ensure necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform.

The plug-in operation is based on the usage of two modules developed as FaaS \(Function-as-a-Service\) functions: the extension module—for receiving requests from the commercetools platform—and the notification module—for sending information about purchases processed in the Ecommpay payment platform to the commercetools platform.

## General information {#en_cms_commercetools_general}

### Capabilities {#section_jdf_ndm_wzb .section}

With the plug-in from Ecommpay, the following is available:

-   Setting up the capability to open the Payment Page payment form of Ecommpay in the web service.

    For this, you should install the plug-in and set up the opening of the Payment Page payment form on the client side of the web service. If relevant, you can also use additional parameters for opening the form and processing payments \([details](en_PP_Parameters.md)\).

-   Testing the operation of the payment form and the capabilities of payment processing.

    For this, you should get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\).

-   Processing one-time one-step purchaseswith the use of various payment methods.

    For setting up different payment methods, you should contact the Ecommpay technical support specialists, while all organisational issues can be resolved in cooperation with the Ecommpay account manager.

-   Issuing partial and full refunds for purchases, which were processed with the help of the plug-in.

    For this, you can use the HTTP API of the commercetools platform and, if relevant, the interfaces of the Ecommpay payment form \(the user interface Dashboard and the Gate API\). Along with that, when using the interfaces of the Ecommpay payment platform, payment information in the commercetools platform is updated only if conditions for sending callbacks from the payment platform have been configured \([details](en_dbl_projects.md)\).

-   Monitoring the information about payments processed with the help of the plug-in.

    For this, you can use the HTTP API and the Merchant Center interface of commercetools and, if relevant,—the Data API and the Dashboard interface of Ecommpay. Keep in mind that for information to be updated in the commercetools platform in case of refunds made via the payment platform interfaces, it must be insured that the callbacks from Ecommpay will be sent to the URL of the notification module.

-   Managing orders with related purchases processed with the help of the plug-in—via the Merchant Center interface and the HTTP API of commercetools.

    This includes cancelling these orders and changing their statuses manually. Also keep in mind that, in case of working with the plug-in from Ecommpay, automatic change of order statuses is not provided but can be set up by the merchant's specialists with the use of the capabilities supported as part of the Composable Commerce solution in the commercetools platform.

-   Using various capabilities provided by Ecommpay.

    Particularly, you can use the payment confirmation procedure when working with Open Banking methods, provide customers with the capability of payment retries \([details](en_PP_Try_Again.md)\), and set up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\). To have these capabilities set up, contact the Ecommpay technical support specialists.


Such a range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure high rates of payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists.

### Workflow {#section_wqc_ssv_szb .section}

The following diagram illustrates the workflow of executing one-time one-step purchases with the use of the plug-in from Ecommpay for the commercetools platform. The workflow involves the customer, the merchant's web service with the built-in plug-in that interacts with the commercetools platform, the Payment Page payment form, the Ecommpay payment platform, and the payment environment. On the web service side, the URLs for opening Payment Page are generated and payment information in the commercetools platform is updated automatically with the help of the plug-in.

![](images/universal/cms/en_cms_workflow.svg)

1.  On the web service side, the customer proceeds to making a purchase with the use of the plug-in from Ecommpay. Along with that, a payment request is sent to the commercetools platform and the extension module of Ecommpay is called via the API extension. With the help of the extension module, a URL for opening Payment Page is generated, after that, a response with the generated URL and with the information about the payment created on the commercetools side is sent from the commercetools platform to the web service.
2.  The request for opening the Payment Page payment form is generated in the web service and sent to the payment platform.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions and confirms the purchase.
8.  The final purchase request \(with all necessary data\) is received in the platform.
9.  The request is sent to the payment environment.
10. The request is processed in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, the 3‑D Secure authentication\).
11. The purchase result information is sent from the payment environment to the payment platform.
12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the notification module, thus the payment information is updated and the information about the purchase initiated in the payment platform appears in the commercetools platform.
13. The purchase result information is sent from the payment platform to Payment Page.
14. The purchase result information is displayed to the customer in the merchant's web service \(if the automatic [final customer redirection](en_PP_redirect_modes.md) to the web service is set up\) or in the Payment Page payment form \(if final redirection to the web service is performed by the customer's decision or the capability of final redirection is not applied\).

Within the provided general workflow, the customer first confirms the order and the payment to be created in the commercetools platform on the checkout page in the web service and then specifies the needed data in the payment form that opens and confirms the purchase to be created in the Ecommpay platform\(using the **Pay** button\). Along with that, a `Charge` transaction is initially created as part of the payment on the commercetools side and a `sale` operation is subsequently initiated for this transaction as part of the purchase on the Ecommpay side.The exception is the case when the customer confirms the order and the payment in the web service but does not confirm the purchase in the Payment Page payment form—in this situation, a `Charge` transaction is created in the commercetools platform in the `Initial` status, but the purchase is not initiated on the Ecommpay side.

The statuses of transactions in the commercetools platform change automatically according to the commercetools documentation \([details](https://docs.commercetools.com/api/projects/payments#transactionstate)\) and depending on the statuses of operations in the Ecommpay platform. However, the statuses of orders and payments created in the commercetools platform during the work with the plug-in from Ecommpay do not change by default.Orders are created in the `Open` status, while payments are created without any status, but in both cases, you can assign statuses manually or set them to change automatically by using the tools and capabilities provided by commercetools.

Along with that, orders, payments, and transactions on the commercetools side are automatically assigned identifiers that consist of 32 random characters, while purchases in the Ecommpay platform are assigned identifiers that correspond to the identifiers of payments in the commercetools platform\(for example, `eeb30cda-a8a1-4895-ab43-5ef8bb29ee80`\) and are assigned the statuses used by Ecommpay \([details](en_platform_payment_model.md)\).With questions about the statuses of payments and orders, contact the Ecommpay account manager.

## Installation {#en_cms_commercetools_installation}

To start using the plug-in from Ecommpay version 1.0, proceed as follows:

1.  Create an [API client](https://docs.commercetools.com/api/projects/api-clients) providing access to the following capabilities \([scopes](https://docs.commercetools.com/api/scopes)\) within the project on the commercetools side:

    -   Managing payments;
    -   Managing the sets of additional fields \([custom types](https://docs.commercetools.com/api/projects/types)\).
    After that, you are provided with a one-time access to the details about the created API client. These details are specified in the parameters `project_key`, `client_id`, `secret`, `scope`, `API URL`, and `Auth URL` and should be saved for subsequent work with the plug-in with the use of the API client.

2.  Install the plug-in modules in the environment you usefollowing the corresponding instructions provided [on GitHub](https://github.com/ITECOMMPAY/ecommpay-commercetools-integration).
3.  Create sets of additional fields \(custom types\) for specifying information about payments initiated in the Ecommpay payment platform.

    For this, the corresponding requests should be sent to the commercetools platform with the following entities' identifiers: `payment-interface-interaction` and `payment`.

    ```language-json
    {
      "key": "ecommpay-integration-interaction-payment-type",
      "name": {
        "en": "commercetools ecommpay integration payment interface interaction type"
      },
      "resourceTypeIds": ["payment-interface-interaction"],
      "fieldDefinitions": [
        {
          "name": "operation_id",
          "label": {
            "en": "Operation id"
          },
          "required": false,
          "type": {
            "name": "Number"
          },
          "inputHint": "SingleLine"
        },
        {
          "name": "operation_type",
          "label": {
            "en": "Operation type"
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        },
        {
          "name": "operation_status",
          "label": {
            "en": "Operation status"
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        },
        {
          "name": "date",
          "label": {
            "en": "Date"
          },
          "required": false,
          "type": {
            "name": "DateTime"
          },
          "inputHint": "SingleLine"
        },
        {
          "name": "sum_initial",
          "label": {
            "en": "Sum initial"
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        },
            {
          "name": "sum_converted",
          "label": {
            "en": "Sum converted"
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        },
            {
          "name": "message",
          "label": {
            "en": "Message"
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        }
      ]
    }
    ```

    As a result of this request, the fields for saving information about operations that is included in callbacks from the payment platform are created in the commercetools platform. These fields are displayed in the order tabs of the Merchant Center interface \(on the page with the information about operations from the payment platform\) and are included in the responses to requests for payment information that are sent via the HTTP API of commercetools.

    ```language-json
    {
      "key": "ecommpay-integration",
      "name": {
        "en": "commercetools ecommpay integration"
      },
      "resourceTypeIds": ["payment"],
      "fieldDefinitions": [
            {
          "name": "initial_request",
          "label": {
            "en": "Initial request"
          },
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine",
          "required": false
        },
        {
          "name": "pp_url",
          "label": {
            "en": "Payment Page URL"
          },
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine",
          "required": false
        }    ]
    }
    ```

    As a result of this request, thefollowing fieldsare created in the commercetools platform: **Initial request**—for specifying additional parameters of opening Payment Page—and **Payment Page****URL**—for specifying the URL for opening the payment form.The **Initial request** field can be used in payment requests sent to the commercetools platform and, together with the parameter for specifying the URL for opening Payment Page, is displayed in the order tabs of the Merchant Center interface \(in the **commercetools Ecommpay integration** section\) and is included in the responses to payment requests sent via the HTTP API of commercetools.

4.  Create an [API extension](https://docs.commercetools.com/api/projects/api-extensions#create-extension) for the interaction between the commercetools platform and the plug-in from Ecommpay. For this, the corresponding request should be sent to the commercetools platform with the extension module URL specified in the `destination` object.

    ```language-json
    {
      "key": "ecommpay-integration-payment-extension",
      "destination": {
        "type": "HTTP",
        "url": "<extension url>" // URL of the plug-in's extension module
      },
      "triggers": [
        {
          "resourceTypeId": "payment",
          "actions": ["Create","Update"],
          "condition": "paymentMethodInfo is defined AND paymentMethodInfo(paymentInterface is defined) AND paymentMethodInfo(paymentInterface=\"ecommpay-integration\")"
        }
      ],
      "timeoutInMs": 10000
    ```


## Testing {#en_cms_commercetools_testing}

### Overview {#en_cms_commercetools_testing_overview}

Testing the plug-in operation and various payment scenarios without actual debiting of funds is possible via the test environment of the Ecommpay payment platform. You can connect to the platform by using the corresponding form [on the company's main site](https://ecommpay.com/apply-now/) andthe identifier and key of the test project received from Ecommpay. Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service, for which the plug-in from Ecommpay should be used, the web service URL, and the payment currency.

Along with that, keep in mind that during the work with the plug-in from Ecommpay for commercetools, Payment Page opening is ensured on the web service side with regards to the parameters included in the URL for opening Payment Page.If additional [parameters for opening the payment form](en_PP_Parameters.md) are needed, they should be specified in the payment request sent to the commercetools platform—in the `initial_request` parameter of the `fields` object inside the `custom` object. The information about organising interaction with Payment Page is provided in the [Interaction concepts](en_pp_interaction_organisation.md) article.

```language-json
{
  "amountPlanned": {
    "currencyCode": "EUR",
    "centAmount": 1000
  },
  "paymentMethodInfo": {
    "paymentInterface": "ecommpay-integration",
    "method": "ecommpay-integration"
  },
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ecommpay-integration"
    },
    "fields": {
      "initial_request": "\"{\\\"customer_id\\\":123,\\\"billing_country\\\":\\\"DE\\\",\\\"customer_country\\\":\\\"DE\\\"}\""
    }
  }
}
```

### Processing test purchases {#en_cms_commercetools_testing_purchase}

When testing the plug-in operation, you can process test purchases in the web service and obtain information about them via the Merchant Center interface and the HTTP API from commercetools.Along with that, you can use special payment credentials that allow testing particular payment scenarios.

To test card payments, you can use the credentials of test cards. For testing according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used:

-   `4000 0000 0000 0077`—for a purchase to be processed
-   `4111 1111 1111 1111`—for a purchase to be declined

For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article.

To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists in the test environment of payment platform\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the corresponding sections of the articles about working with particular payment methods.

### Processing test refunds {#en_cms_commercetools_testing_refund}

#### Overview {#section_ddh_41r_kbc .section}

After processing test purchases, you can make test refundsvia the HTTP API of commercetools and, if relevant, via [Gate](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Information provided in this subsection is also relevant for issuing refunds in the production environment.

#### Ensuring data synchronisation between platforms {#section_qvf_z1r_kbc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), payment information in the commercetools platform is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the commercetools platform interfaces, it is important to ensure that callbacks can be sent and received for automatic updates of information in the commercetools platform. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the notification module of the plug-in\(to the URL specified during the plug-in installation as an environment variable for the extension module\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the logs of the environment where the plug-in is installed may display errors when payment information is updated in the commercetools platform.

-   On the web service side, the URL for receiving callbacks from the payment platform side is accessible, the Ecommpay IP addresses are in the whitelist and callbacks are not blocked by firewalls or other network devices.

    This can be relevant particularly in case of using the Docker and Node.js platforms.


#### Procedures {#section_h52_z2r_kbc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay and commercetools platforms.

To make a refund, a request for updating the needed payment should be sent to the commercetools platform \([details](https://docs.commercetools.com/api/projects/payments#update-payment)\). This request should contain the `actions` array with the following data:

-   The `action` parameter with the name of the action that should be performed for the payment.

    To initiate a refund, specify the `addTransaction` value.

-   The `transaction` object with the following data:
    -   The `type` parameter with the transaction type in the commercetools platform.

        To initiate a refund, specify the `Refund` value.

    -   The `amount` object with the `currencyCode` and `centAmount` parameters for specifying the currency and the amount of the refund respectively.

        For a partial refund, the refund amount must not exceed the actual payment amount.


```language-json
"actions": [
    {
      "action": "addTransaction",
      "transaction": {
        "type": "Refund",
        "amount": {
          "centAmount": 8300,
          "currencyCode": "EUR"
        }
      }
    }
  ]
```

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

## Usage {#en_cms_commercetools_usage}

### Overview {#en_cms_commercetools_usage_overview}

In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web servicefor which the plug-in from Ecommpay should be used and the currency in which payments are to be processed.

Along with that, keep in mind that during the work with the plug-in from Ecommpay for commercetools, Payment Page opening is ensured on the web service side with regards to the parameters included in the URL for opening Payment Page.If additional [parameters for opening the payment form](en_PP_Parameters.md) are needed, they should be specified in the payment request sent to the commercetools platform—in the `initial_request` parameter of the `fields` object inside the `custom` object. The information about organising interaction with Payment Page is provided in the [Interaction concepts](en_pp_interaction_organisation.md) article.

**Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page.

After resolving all organisational and technical issues, you can specify the identifier and secret key of the production project received from Ecommpay in the variables of the environment where the plug-in modules have been installed and start using the plug-in for production purposes. If you need to suspend the plug-in operation afterwards, you can disable the option to make payments via the plug-in in the web service, remove the plug-in modules from the environment in use, or terminate the work in this environment.

### Issuing refunds {#en_cms_commercetools_usage_refund}

#### Overview {#section_iss_drm_vzb .section}

After processing purchases, you can issue refunds as part of these purchasesvia the HTTP API of commercetools and, if relevant, via [Gate](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. All capabilities and procedures of working with refunds in the life mode correspond to those available in the test environment.

#### Ensuring data synchronisation between platforms {#section_jnp_fmr_kbc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), payment information in the commercetools platform is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the commercetools platform interfaces, it is important to ensure that callbacks can be sent and received for automatic updates of information in the commercetools platform. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the notification module of the plug-in\(to the URL specified during the plug-in installation as an environment variable for the extension module\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the logs of the environment where the plug-in is installed may display errors when payment information is updated in the commercetools platform.

-   On the web service side, the URL for receiving callbacks from the payment platform side is accessible, the Ecommpay IP addresses are in the whitelist and callbacks are not blocked by firewalls or other network devices.

    This can be relevant particularly in case of using the Docker and Node.js platforms.


#### Procedures {#section_v5j_gmr_kbc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay and commercetools platforms.

To make a refund, a request for updating the needed payment should be sent to the commercetools platform \([details](https://docs.commercetools.com/api/projects/payments#update-payment)\). This request should contain the `actions` array with the following data:

-   The `action` parameter with the name of the action that should be performed for the payment.

    To initiate a refund, specify the `addTransaction` value.

-   The `transaction` object with the following data:
    -   The `type` parameter with the transaction type in the commercetools platform.

        To initiate a refund, specify the `Refund` value.

    -   The `amount` object with the `currencyCode` and `centAmount` parameters for specifying the currency and the amount of the refund respectively.

        For a partial refund, the refund amount must not exceed the actual payment amount.


```language-json
"actions": [
    {
      "action": "addTransaction",
      "transaction": {
        "type": "Refund",
        "amount": {
          "centAmount": 8300,
          "currencyCode": "EUR"
        }
      }
    }
  ]
```

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

### Monitoring payments and orders {#en_cms_commercetools_usage_monitoring}

Information about payments processed with the use of the plug-in from Ecommpay and about the corresponding orders can be monitored via the Merchant Center interface and the HTTP API of commercetools. If necessary, you can also use the Dashboard interface and the Data API of Ecommpay, but in this case, you can only monitor the payments initiated in the payment platform.

In the Merchant Center interface, the **Orders** section contains the orders register with main details about every orderincluding the capabilities to search and filter data and to open the tabs of separate orders.

![](images/universal/cms/commercetools/cms_commercetools_orders.png "Orders register in the Merchant Center interface")

To open the tab of a particular order, click on the order's entry in the register. Each tab containsthe details about an order and a payment\(such as the order creation date, amount, and status and other information\). When working with the plug-in from Ecommpay, you can use the following tabs:

-   **General**—with the information about the order and the customer's billing address
-   **Custom Fields**—with the set of additional fields used as part of the order data
-   **Shipping & Delivery**—with the information about the products shipping method
-   **Returns**—with the information about the products returns
-   **Payments**—with the information about payments and transactions within the order

For information about the payment processed via the plug-in from Ecommpay, open the **Payments** tab. This tab displays the payment method code\(in the **Payment method name** parameter\), the purchase method name\(in the **Payment method** parameter\), the payment amount and currency\(in the **Amount planned** parameter\), the status assigned to the payment in the Ecommpay platform\(in the **PSP Status Code** parameter\), and other information.

![](images/ecommpay/cms/commercetools/cms_commercetools_order.png "Order tab in the Merchant Center interface")

The **Payment transactions** table displays the information about transactions in the commercetools platform in the following columns:

-   **Date**—the date of the transaction creation
-   **Transaction type**—the transaction type that depends on the type of the operation in the Ecommpay payment platform\(`Charge` for `sale` operations and `Refund` for `refund` or `reversal` operations\)
-   **Status**—the transaction status
-   **Amount**—the transaction amount and currency
-   **Interaction ID**—the identifier assigned in the Ecommpay platform to an operation that relates to a particular transaction
-   **Transaction ID**—the transaction identifier

The status of each commercetools transaction depends on the state of the corresponding operation in the Ecommpay platform.Thus, transactions can have the following statuses:

-   `Initial` if the callback with the information about the operation has not been received in the commercetools platform yet;
-   `Pending` if the operation has an intermediate status;

-   `Successful` if the operation has been processed;
-   `Failure` if the operation has been declined.

![](images/ecommpay/cms/commercetools/cms_commercetools_order_table.png "Table with the transaction data in the order tab of the Merchant Center interface")

For information about operations initiated in the Ecommpay platform, click the **View PSP transaction log** link. This opens the page with the information about all operations within a particular payment.This information is included in the callbacks from the payment platform and is specified in the additional fields created at the stage of plug-in installation.

![](images/universal/cms/commercetools/cms_commercetools_callback_data.png "Page with the information about operations sent in callbacks from the payment platform")

During the work with the HTTP API, you can get the payment information by sending the corresponding request to the commercetools platform \([details](https://docs.commercetools.com/api/projects/payments#get-payment)\).In such a request, the payment information from the Ecommpay platform is specified in the additional fields created as part of the plug-in installation

```language-json
{
      "id": "7c081cc3-353d-4a80-8879-36e2f7dc5ac4",
      "version": 15,
      "versionModifiedAt": "2023-12-19T11:47:37.374Z",
      "lastMessageSequenceNumber": 10,
      "createdAt": "2023-12-19T11:27:56.278Z",
      "lastModifiedAt": "2023-12-19T11:47:37.374Z",
      "lastModifiedBy": {
        "clientId": "4cD5VUC9rScyTo69eOueu6Jh",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "4cD5VUC9rScyTo69eOueu6Jh",
        "isPlatformClient": false,
        "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902"
      },
      "amountPlanned": {
        "type": "centPrecision",
        "currencyCode": "EUR",
        "centAmount": 12300,
        "fractionDigits": 2
      },
      "paymentMethodInfo": {
        "paymentInterface": "ecommpay-integration",
        "method": "ecommpay-integration",
        "name": {
          "en": "card"
        }
      },
      "custom": {
        "type": {
          "typeId": "type",
          "id": "62408c35-a8b1-4bd0-9c15-99aa86cf8efc"
        },
        "fields": {
          "initial_request": "{\"redirect_success_url\":\"https://example.com/complete-redirect?id=success\"...}",
          "pp_url": "https://paymentpage.ecommpay.com/payment?project_id=109751&interface_type=33..."
        }
      },
      "paymentStatus": {
        "interfaceCode": "success"
      },
      "transactions": [
        {
          "id": "a503a5e0-9677-46d8-bab2-2dbbb10595ce",
          "timestamp": "2023-12-19T11:27:56.272Z",
          "type": "Charge",
          "amount": {
            "type": "centPrecision",
            "currencyCode": "EUR",
            "centAmount": 12300,
            "fractionDigits": 2
          },
          "interactionId": "47382010085133",
          "state": "Success"
        },
        {
          "id": "424ca2fd-0d31-475c-98f1-0f945a30a9ef",
          "type": "Refund",
          "amount": {
            "type": "centPrecision",
            "currencyCode": "EUR",
            "centAmount": 8300,
            "fractionDigits": 2
          },
          "interactionId": "0",
          "state": "Initial"
        }
      ],
      "interfaceInteractions": [
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:18+0000",
            "operation_id": 47382010085133,
            "operation_status": "awaiting 3ds result",
            "message": "Awaiting processing",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        },
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:25+0000",
            "operation_id": 47382010085133,
            "operation_status": "awaiting 3ds result",
            "message": "Awaiting processing",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        },
        {
          "type": {
            "typeId": "type",
            "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86"
          },
          "fields": {
            "operation_type": "sale",
            "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}",
            "date": "2023-12-19T11:47:35+0000",
            "operation_id": 47382010085133,
            "operation_status": "success",
            "message": "Success",
            "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}"
          }
        }
      ],
      "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902"
    }
  }
}
```

More detailed information about working with payments and orders using the capabilities of commercetools is provided [in the commercetools documentation](https://docs.commercetools.com/docs/composable-commerce).



---

# Using plug-in from Ecommpay for Magento CMS {#en_CMS__magento}

An article about using a plug-in for embedding Payment Page into websites powered by the Magento CMS platform.

**Parent topic:**[Integration using plug-ins](en_CMS.md)

## Overview {#en_cms_magento_overview}

This article covers the information about using the payment plug-in from Ecommpayversion2.1.6. This plug-in can be used in web services that are based on the Magento CMS version 2.2 or later.

**Note:** In the Magento and Hyvä documentation, the term *module* refers to what in this documentation is known as *plug-in*.

The plug-in from Ecommpay allows opening the Payment Page payment form of Ecommpay for customers and ensuring all necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform \(with all necessary information sent and received\).

![](images/ecommpay/cms/magento/cms_magento_methods.png "Administrative interface Magento")

![](images/ecommpay/cms/magento/cms_magento_pp_embedded_glr.png "Interface of Payment Page embedded in the web service")

## General information {#en_cms_magento_general}

### Capabilities {#section_jn4_bk5_lcc .section}

With the plug-in from Ecommpay, the following is available:

-   Setting up the capability to open the Payment Page payment form of Ecommpay in the web service.

    For this, you only need to install the plug-in from Ecommpay and set up its usage in the Magento CMS interface.

-   Setting up the usage of separate payment methods available in the merchant's project.

    You can do this directly via the corresponding accordion items in the Magento interface. Technically, for using different payment methods, you may need to either configure a minimum of the plug-in parameters or take no actions at all, while all organisational issues can be resolved in cooperation with the Ecommpay account manager.

-   Setting up the design of the merchant's web service with the use of Hyvä Themes and integrating the Payment Page payment form of Ecommpay into Hyvä Checkout.

    For this, you only need to install the required plug-ins in addition to the plug-in from Ecommpay and set up its usage in the Magento CMS interface.

-   Testing the operation of the payment form and the capabilities of payment processing.

    For initial testing, you can just use the plug-in test mode \(with no additional actions required\), while for deeper testing, you can get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\).

-   Processing one-time one-step or two-step purchases.

    Within a single project, you can select one option to process purchases: when funds are debited immediately \(in one step\)using any of the set up payment methods or when funds are first authorised and then either withdrawn or released \(in two steps\)using any of the methods which support processing of such purchases via Payment Page.

-   Issuing partial and full refunds for purchases, which were processed with the help of the plug-in, as part of the work with methods for which refunds are supported.

    For this, you can use the Magento interface and, if relevant, interfaces of the Ecommpay payment platform \(the user interface Dashboard and the Gate API\). Along with that, when using the interfaces of the Ecommpay payment platform, payment information in the Magento interface is updated only if conditions for sending callbacks from the payment platform have been configured \([details](en_dbl_projects.md)\).

-   Monitoring the information about payments processed with the help of the plug-in.

    For this, you can use the Magento interface and if relevant—the Dashboard interface from Ecommpay. Along with that, it should be considered that in situations when refunds are made via Gate or Dashboard, the information may not be updated in the Magento interface.

-   Managing orders with related purchases processed with the help of the plug-in—via the Magento interface.

    This includes cancelling these orders and changing their statuses manually \(if necessary\).

-   Configuring the parameters of the Payment Page operation and adjusting the form to the web service specifics, as well as using various capabilities provided by Ecommpay.

    Particularly, you can use the payment confirmation procedure when working with Open Banking methods andset up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\). To have these capabilities set up, contact the Ecommpay technical support specialists.


Such a wide range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure a high rate of the payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists.

### Workflows {#section_zp1_by1_mcc .section}

The following diagrams illustrate the workflows of executing one-time one-step and two-step purchases with the use of the plug-in from Ecommpay. The workflows involve the customer, the merchant's web service with the built-in plug-in, the Payment Page payment form, the payment platform, and the payment environment. On the web service side, the opening of Payment Page is requested and automatic interaction with the payment platform is carried out in accordance with the plug-in parameters.

In case of *one-step purchases*, one initial request leads to a one-time transfer of funds from the customer to the merchant which is followed by a callback with the information about the payment result sent to the web service.

![](images/universal/cms/en_cms_workflow.svg)

1.  On the web service side, the customer opens the checkout pageand selects a purchase method available via the plug-in from Ecommpay.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, with regards to the method selected by the customer.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions for purchase and confirms the purchase.
8.  The final purchase request \(with all necessary data\) is received in the platform.
9.  The request is sent to the payment environment.
10. The request is processed in the payment environment, and if necessary, additional actions are performed on the side of the platform and the customer \(for example, for the 3‑D Secure authentication\).
11. The purchase result information is sent from the payment environment to the payment platform.
12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus an invoice is generated and payment information is updated in the Magento interface.
13. The purchase result information is sent from the payment platform to Payment Page.
14. The purchase result information is displayed to the customer in the payment form.

In case of *two-step purchases*, based on an initial request\(at the first step\), the funds are held on the customer's account and then\(at the second step\), based on the next request or automatically after a specified period of time, the funds are transferred to the merchant or released. Along with that, at each step, a callback with the information about the corresponding result is sent to the web service.

![](images/universal/cms/en_cms_workflow_auth.svg)

1.  On the web service side, the customer opens the checkout pageand selects a payment method available via the plug-in from Ecommpay.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, for processing the payment with use of the select payment method.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions and confirms the purchase.
8.  The request for authorisation hold is received in the platform.
9.  The request is sent to the payment environment.
10. The payment is processed and the funds are authorised in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, the 3‑D Secure authentication\).
11. The information about the authorisation hold result is sent from the payment environment to the payment platform.
12. The callback with the information about the authorisation hold result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the payment information is updated in the Magento interface.
13. The information about the authorisation hold result is sent from the payment platform to Payment Page.
14. The information about the authorisation hold result is displayed to the customer on Payment Page.
15. After it has been confirmed that the funds should be withdrawn, the merchant's specialist initiates the withdrawal, and as result, a request for withdrawing the funds is received and processed in the payment platform \(which is done with the help of the plug-in\).
16. The request is sent to the payment environment.
17. The payment is processed in the payment environment.
18. The information about the withdrawal result is sent from the payment environment to the payment platform.
19. The callback with the information about the withdrawal result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus an invoice is generated and payment information is updated in the Magento interface.
20. The customer is notified about the withdrawal result by the means of the web service.

For interaction with customers when processing one-step purchases and placing authorisation hold on funds for two-step purchases, the following options can be applied:

-   with the payment form embedded directly in the web service interface\(in an iframe element\);
-   with the payment form opened in a modal window or in a separate tab.

The first of these options is available only for purchases with the direct use of payment cards and is used for such purchases by default. In case of this option, the customer specifies payment card credentials and confirms the order, which is generated in the Magento CMS, and the payment, which is initiated in the Ecommpay platform, directly on the web service page for proceeding to payment\(using the **Place Order** button\).

The second of these options is used for all alternative payment methods and for purchases with the direct use of payment cards if these purchases are made with the payment form opened in a modal window or a separate tab.In case of this option, the customer first confirms the order, which is generated in the Magento CMS, on the web service page for proceeding to payment \(using the **Place Order** button\) and only after that specifies the necessary data in the payment form and confirms the payment, which is initiated in the Ecommpay platform,\(using the **Pay** button\).

Additionally, the second option allows for cases when the customer confirms the order but does not proceed to payment. In such cases, orders in the `Pending Payment` status appear in the web service with no purchases initiated for these orders. As to the rest, the work with orders and the corresponding payments is the same for both options.

You can monitor the information about orders and payments via the Magento interface: in the **Orders** subsection of the **Sales** section. Orders and payments have different identifiers and statuses.Orders on the web service side are assigned nine-digit numbers \(for example, `000001503`\) and statuses used by Magento \([details](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-status.html?lang=en)\), while payments on the payment platform side are assigned identifiers that consist of the prefix `mag_` and a code of thirteen characters \(for example, `mag_64ca3135cffd3`\) and statuses used by Ecommpay \([details](en_platform_payment_model.md)\). With questions about the statues of payments and orders, contact the Ecommpay account manager.

## Installation {#en_cms_magento_installation}

### General information {#section_tf3_grh_mcc .section}

To start using the plug-in version 2.1.6 from Ecommpay for the Magento CMS, you need to install it. There are two ways to install the plug-in—*via the plug-ins directory* of Magento\(without prior download of the plug-in files\) or *using the zip files* of the plug-in\(with the plug-in files downloaded beforehand\).

If you encounter questions related to the plug-in installation, contact the Ecommpay technical support specialists.

### Installation via the plug-ins directory {#section_tcf_jsh_mcc .section}

To install the plug-in via the directory, proceed as follows:

1.  Execute the command `composer require ecommpay/module-payments` from the root folder with the Magento CMS files.
2.  If necessary, [obtain](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/prerequisites/authentication-keys) and specify the authentication key to access the integration modules on the Magento CMS side.
3.  Execute the following commands from the root folder with the Magento CMS files and wait for the installation completion.

    ```
    php bin/magento setup:upgrade
    php bin/magento cache:flush
    php bin/magento cache:clean
    php bin/magento setup:di:compile
    php bin/magento setup:static-content:deploy
    ```


### Installation using the plug-in zip file {#section_q3n_bth_mcc .section}

To install the plug-in using the plug-in zip file, proceed as follows:

1.  Download the zip file [from GitHub](https://github.com/ITECOMMPAY/ecommpay-magento2).
2.  Unzip the folder with the plug-in files and add it to the folder with the source code of the web service built on the Magento CMS—specifically, to the `app/code` subfolder.

    **Note:**

    If before the plug-in installation, one of its earlier versions has been used and not deleted, the folder with the files of this version should be deleted from the folder with the web service source code before the folder with the new version will be added.

    Also note that, depending on the structure of the folder with the web service source code, additional actions may be required for connecting to this folder \(for example, connecting via the SSH protocol\).

3.  Execute the following commands from the root folder with the Magento CMS files and wait for the installation completion.

    ```
    php bin/magento indexer:reindex 
    php bin/magento setup:upgrade
    php bin/magento setup:di:compile
    php bin/magento cache:flush
    php bin/magento cache:clean
    php bin/magento setup:static-content:deploy
    ```


## Testing {#en_cms_magento_testing}

### Overview {#en_cms_magento_testing_overview}

For testing the plug-in operation and processing test payments without actual debiting of funds, there are the following options available:

-   *Testing in the plug-in test mode.* This is the option to carry out local basic testing without connecting to the Ecommpay payment platform.It allows you to promptly check the payment form operation and separate scenarios of card payments. In this mode, the identifiers of test payments contain the code word `test` and the domain name of the web service \(for example, `test_mysite_mag_64ca3135cffd3`\). This can be convenient for monitoring the processing of payments.
-   *Testing in the test environment of the Ecommpay payment platform.* This is the option to carry out integrated and fully-featured testing after connecting to the Ecommpay payment platform and setting up its components.You can connect to the platform within a few minutes by using the corresponding form [on the company's main site](https://ecommpay.com/sign-up/) and the received identifier and key of the test project. In this case, the plug-in is switched to the production mode and allows you to test a greater number of payment scenarios, including payments via alternative methods available for testing \([details](en_pm_testing.md)\).All payments remain not real \(although, their identifiers do not contain the code word `test` and the domain name of the web service\).

To compare the two testing options, refer to the following table.

|Testing capabilities|in the plug-in test mode|in the test environment of the platform|
|--------------------|------------------------|---------------------------------------|
|Opening the payment form using various options and parameters of its operation|+|+|
|Processing one-time purchases \(in one and two steps\)|+|+|
|Using alternative payment methods \(as coordinated with the Ecommpay specialists\)|–|+|
|Using addition capabilities of the Payment Page payment form \(as coordinated with the Ecommpay specialists\)|–|+|
|Issuing refunds|+|+|
|Monitoring payment information|+|+|
|Managing orders|+|+|

Regardless of the selected testing option \(in the test mode or via the test environment of Ecommpay\), the plug-in is connected to the web service and becomes available to customers as the payment option. Thus,in cases when the plug-in is connected to a web service that operates in live mode, it is recommended to ensure that testing takes place during a low-load period and notify the customers about the ongoing testing activities.

### Parameters setup {#en_cms_magento_testing_setup}

To prepare the plug-in for testing, decide on the preferable testing option and set up the plug-in in the Magento interface as follows:

1.  Go to the plug-in parameters in the Magento interface.

    For this, proceed as follows:

    1.  Select the **Stores** section in the navigation menu and the **Configuration** item in the menu that appears.
    2.  Select the **Sales** section and the **Payment Methods** item in the left menu of the **Configuration** subsection.
    3.  Find the section with the plug-in operation parameters on the page that opens and click the **Configure** button.
2.  Set up the basic parameters of the plug-in operation in the accordion item **General settings**:

    -   **Plugin Enabled**—the feature for enabling the plug-in in the web service.

        If this parameter is set to **Yes**, then all payment methods previously enabled for working via the plug-in become available in the web service. If the parameter is set to **No**, then all payment methods are disabled in the web service and unavailable for payment processing.

    -   **Demo mode**—the feature for switching the plug-in operation mode.

        For using the test mode of the plug-in, set the **Yes** value, for using the test environment of the platform—set the **No** value and specify the parameters for connecting to the test environment received from Ecommpay in the fields **Project ID** and **Secret Key**.

        **Note:** When the plug-in test mode is enabled, the values specified in the fields **Project ID** and **Secret Key** are ignored. Thus, to use the project of the Ecommpay payment platform, you should disable the plug-in test mode.

    -   **Project ID**—the test project identifier.
    -   **Secret Key**—the test project key for interacting with the platform.
    -   **Language**—the language in which the payment form is displayed.
    -   **Additional parameters**—additional [parameters for opening payment form](en_PP_Parameters.md).When specifying several parameters in this field, use the & symbol as a separator.
    -   **Payment action**—the option to process purchases:

        -   **Authorize** — in two steps \(with debiting after authorisation hold\);
        -   **Authorize and Capture** — in one step \(with immediate debiting of funds\).
        The first option is supported only for card payments and for the Apple Pay and Google Pay methods, while the second option is supported for all payment methods available via the plug-in.

    ![](images/ecommpay/cms/magento/cms_magento_settings_general.png "The accordion item General settings with basic parameters for setup")

3.  Set up the parameters for using payment methods \([details](en_CMS__magento.md)\).

    Working in the test mode of the plug-in, you only need to set up the parameters for card payments in either of the accordion items—**Card payments** or **More payment methods via Ecommpay**.

4.  Save the parameters of the plug-in operation.

    For this, click the **Save Config** button.


### Processing test purchases {#en_cms_magento_testing_purchase}

#### Overview {#section_o5k_jrb_mcc .section}

When testing the plug-in operation, you can process test purchases in the web service and obtain basic information about them via the Magento interfacein the **Orders** subsection of the **Sales** section. Along with that, you can use special payment credentials that allow testing particular payment scenarios.

To test card payments, you can use the numbers of test cards. For testing according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used:

-   `4000 0000 0000 0077`—for a purchase to be processed;
-   `4111 1111 1111 1111`—for a purchase to be declined.

For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article.

To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists in the test environment of payment platform\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the sections about testing particular payment methods.

#### Ensuring data synchronisation {#section_nzg_1sb_mcc .section}

When working with two-step purchases, the second steps can be initiated both via the Magento interface and via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\). In case of the Ecommpay interfaces, the order information in the Magento interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the Magento interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the Magento interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS Magento\(to the URL in the format `https://<merchant domain>/ecommpay/endpayment/index`\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_cls_rwb_mcc .section}

A one-step purchase, as well as the first step of a two-step purchase\(authorisation hold\), is initiated by the customer when they confirm the payment. A one-step purchase is processed automatically, while for a two-step purchase, only the first step, authorisation hold, is initiated automatically and after that the second step, withdrawal or release of funds, can be made. The second step can also be initiated automatically \(after a specified authorisation period\) or upon the merchant's request—via the Magento interface or the interfaces of the Ecommpay payment platform: Dashboard\([details](en_dbl_payments.md)\) and the Gate API\([details](en_gate_payment_auth.md)\). Along with that, withdrawals upon requests can be made not only for the entire authorised amount but also for a part of this amount.

To initiate the second step of a purchase via the Magento interface, proceed as follows:

1.  Go to the orders register.

    For this open the **Sales** section and select the **Orders** item in the menu that appears.

2.  Select an order within which the second step of the purchase should be initiated.
3.  Initiate the second step of the purchase.

    For withdrawing the authorised funds, proceed as follows:

    1.  Click the **Invoice** button in the top menu of the order tab.
    2.  Ensure that, on the page that opens, the number of products for which the funds should be withdrawn is specified in the **Qty to Invoice** column.

        **Note:** Take into consideration that, when a partial amount is withdrawn, the rest is automatically released and returned to the customer.

    3.  Ensure that, for the **Amount** parameter in the bottom part of the page, the **Capture Online** value is selected and click the **Submit Invoice** button.
    For releasing the authorised funds, click the **Void** button in the top part of the order tab and confirm the action in the dialogue box that appears.


For setting up automatic initiation of the second step of two-step purchases, contact the Ecommpay technical support specialists.

**Note:** According to the requirements of the global card networks, the time allocated for holding the funds is limited on the Ecommpay platform side \([details](en_pp_purchase_auth.md#section_hgy_djl_ylb)\).If this time expires and the funds are not withdrawn or released, the payment is automatically declined in the payment platform.

### Processing test refunds {#en_cms_magento_testing_refund}

#### Overview {#section_kw3_g3d_mcc .section}

After processing test purchases, you can make test refundsvia the Magento interface and, if relevant, via [Gate](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the Magento interface have the statuses `Processing` or `Complete` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all information provided in this subsection is as well relevant for issuing refunds in the production environment.

**Note:** When the information about a payment processed within a particular order is received from the Ecommpay platform in the web service, an *invoice* is automatically generated for this order in the Magento interface \(the information about this invoice is provided in the **Invoices** section in the order tab\). Before the invoice is generated, the capability of making refunds within the corresponding order via the Magento interface is unavailable.

#### Ensuring data synchronisation {#section_j2d_fjd_mcc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the Magento interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the Magento interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the Magento interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS Magento\(to the URL in the format `https://<merchant domain>/ecommpay/endpayment/index`\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_hbr_5jd_mcc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay and Magento platforms.

To make a refund via the Magento interface, proceed as follows:

1.  Open the orders register.

    For this, open the **Sales** section and select the **Orders** item in the menu that appears.

2.  Select the order that should be refunded, select the **Invoices** item in the left menu of the order tab.
3.  Select an invoice within which the payment has been processed and click the **Credit Memo** buttonin the upper menu of the invoice page.
4.  Specify the number of the items that should be returned and, if necessary, click the **Update Qty's** button for updating the refund amount on the page for making refunds—**New Memo**.
5.  If necessary, specify the reason for the refund in the **Credit Memo Comments** field.
6.  Confirm the refund.

    For this, click the **Refund** button.

7.  Ensure that the order history contains the information about the made refund.

    In case of a partial refund, the order is assigned the status `Processing`, while in case of a full refund, it is assigned the status `Closed`.


![](images/universal/cms/magento/cms_magento_refund.png "The order tab in the Magento interface")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

In case of refunds via the Magento interface, the records with the information about these refunds \(*credit memos*\) are generated in this interface. You can view such records via the **Credit Memos** section in separate order tabs, while more detailed information about refunds can be obtained via the interfaces of the Ecommpay payment platform \(for example, Dashboard and Data API\).

## Usage {#en_cms_magento_usage}

### Overview {#en_cms_magento_usage_overview}

In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web service for which the plug-in from Ecommpay is set up and the currency in which payments are to be processed.

After that, you can switch the plug-in to the production mode, specify the receivedidentifier and secret key in the parameters of the plug-in operation and set up other necessary parameters\(or check whether the current setup is relevant for working in real-life conditions\). If, after the setup, you need to suspend the plug-in operation, for example, to test some additional features, the plug-in can be switched to the test mode or disabled.

### Parameters setup {#en_cms_magento_usage_setup}

To set up the plug-in parameters, proceed as follows:

1.  Go to the plug-in parameters in the Magento interface.

    For this, proceed as follows:

    1.  Select the **Stores** section in the navigation menu and the **Configuration** item in the menu that appears.
    2.  Select the **Sales** section and the **Payment Methods** item in the left menu of the **Configuration** subsection.
    3.  Find the section with the plug-in operation parameters on the page that opens and click the **Configure** button.
2.  Set up the basic parameters of the plug-in operation in the accordion item **General settings**:

    -   **Plugin Enabled**—the feature for enabling the plug-in in the web service.

        If this parameter is set to **Yes**, then all payment methods previously enabled for working via the plug-in become available in the web service. If the parameter is set to **No**, then all payment methods are disabled in the web service and unavailable for payment processing.

    -   **Demo mode**—the feature for switching the plug-in operation mode.

        For using the production environment of the platform, set the **No** value and specify the parameters for connecting to the production environment received from Ecommpay in the fields **Project ID** and **Secret Key**.

    -   **Project ID**—the test project identifier.
    -   **Secret Key**—the test project key for interacting with the platform.
    -   **Language**—the language in which the payment form is displayed.
    -   **Additional parameters**—additional [parameters for opening payment form](en_PP_Parameters.md).When specifying several parameters in this field, use the & symbol as a separator.
    -   **Payment action**—the option to process purchases:

        -   **Authorize** — in two steps \(with debiting after authorisation hold\);
        -   **Authorize and Capture** — in one step \(with immediate debiting of funds\).
        The first option is supported only for card payments and for the Apple Pay and Google Pay methods, while the second option is supported for all payment methods available via the plug-in.

    ![](images/ecommpay/cms/magento/cms_magento_settings_general.png "The accordion item General settings with basic parameters for setup")

3.  Set up the parameters for using payment methods \([details](en_CMS__magento.md)\).
4.  Save the parameters of the plug-in operation.

    For this, click the **Save Config** button.


### Processing purchases {#en_cms_magento_usage_purchase}

#### Overview {#section_oqz_pmd_mcc .section}

If the web service and the plug-in have been set up correctly, the processing of one-step purchases and authorisation hold on funds for two-step purchases are performed automatically.Along with that, it is important to ensure that all necessary data is collected on the web service side.

**Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page.

In case of questions or issues related to purchase processing, contact the Ecommpay technical support specialists.

#### Ensuring data synchronisation {#section_vvw_5md_mcc .section}

When working with two-step purchases, the second steps can be initiated both via the Magento interface and via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\). In case of the Ecommpay interfaces, the order information in the Magento interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the Magento interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the Magento interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS Magento\(to the URL in the format `https://<merchant domain>/ecommpay/endpayment/index`\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_pym_vmd_mcc .section}

A one-step purchase, as well as the first step of a two-step purchase\(authorisation hold\), is initiated by the customer when they confirm the payment. A one-step purchase is processed automatically, while for a two-step purchase, only the first step, authorisation hold, is initiated automatically and after that the second step, withdrawal or release of funds, can be made. The second step can also be initiated automatically \(after a specified authorisation period\) or upon the merchant's request—via the Magento interface or the interfaces of the Ecommpay payment platform: Dashboard\([details](en_dbl_payments.md)\) and the Gate API\([details](en_gate_payment_auth.md)\). Along with that, withdrawals upon requests can be made not only for the entire authorised amount but also for a part of this amount.

To initiate the second step of a purchase via the Magento interface, proceed as follows:

1.  Go to the orders register.

    For this open the **Sales** section and select the **Orders** item in the menu that appears.

2.  Select an order within which the second step of the purchase should be initiated.
3.  Initiate the second step of the purchase.

    For withdrawing the authorised funds, proceed as follows:

    1.  Click the **Invoice** button in the top menu of the order tab.
    2.  Ensure that, on the page that opens, the number of products for which the funds should be withdrawn is specified in the **Qty to Invoice** column.

        **Note:** Take into consideration that, when a partial amount is withdrawn, the rest is automatically released and returned to the customer.

    3.  Ensure that, for the **Amount** parameter in the bottom part of the page, the **Capture Online** value is selected and click the **Submit Invoice** button.
    For releasing the authorised funds, click the **Void** button in the top part of the order tab and confirm the action in the dialogue box that appears.


For setting up automatic initiation of the second step of two-step purchases, contact the Ecommpay technical support specialists.

**Note:** According to the requirements of the global card networks, the time allocated for holding the funds is limited on the Ecommpay platform side \([details](en_pp_purchase_auth.md#section_hgy_djl_ylb)\).If this time expires and the funds are not withdrawn or released, the payment is automatically declined in the payment platform.

### Issuing refunds {#en_cms_magento_usage_refund}

#### Overview {#section_x1n_zmd_mcc .section}

After processing test purchases, you can make refundsvia the Magento interface and, if relevant, via [the Gate API](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the Magento interface have the statuses `Processing` or `Complete` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all capabilities and procedures of working with refunds in the production mode correspond to those available in the test mode.

**Note:** When the information about a payment processed within a particular order is received from the Ecommpay platform in the web service, an *invoice* is automatically generated for this order in the Magento interface \(the information about this invoice is provided in the **Invoices** section in the order tab\). Before the invoice is generated, the capability of making refunds within the corresponding order via the Magento interface is unavailable.

#### Ensuring data synchronisation {#section_wnv_knd_mcc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the Magento interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the Magento interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the Magento interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS Magento\(to the URL in the format `https://<merchant domain>/ecommpay/endpayment/index`\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_yr4_lnd_mcc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay and Magento platforms.

To make a refund via the Magento interface, proceed as follows:

1.  Open the orders register.

    For this, open the **Sales** section and select the **Orders** item in the menu that appears.

2.  Select the order that should be refunded, select the **Invoices** item in the left menu of the order tab.
3.  Select an invoice within which the payment has been processed and click the **Credit Memo** buttonin the upper menu of the invoice page.
4.  Specify the number of the items that should be returned and, if necessary, click the **Update Qty's** button for updating the refund amount on the page for making refunds—**New Memo**.
5.  If necessary, specify the reason for the refund in the **Credit Memo Comments** field.
6.  Confirm the refund.

    For this, click the **Refund** button.

7.  Ensure that the order history contains the information about the made refund.

    In case of a partial refund, the order is assigned the status `Processing`, while in case of a full refund, it is assigned the status `Closed`.


![](images/universal/cms/magento/cms_magento_refund.png "The order tab in the Magento interface")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

In case of refunds via the Magento interface, the records with the information about these refunds \(*credit memos*\) are generated in this interface. You can view such records via the **Credit Memos** section in separate order tabs, while more detailed information about refunds can be obtained via the interfaces of the Ecommpay payment platform \(for example, Dashboard and Data API\).

### Monitoring payments and orders {#en_cms_magento_usage_monitoring}

Information about orders, including basic information about payments processed via the plug-in from Ecommpay, can be monitored in the Magento interface, via the tools of the **Orders** subsection in the **Sales** section. More detailed information about payments and refunds can be obtained via the Dashboard interface of Ecommpay\(although the information about orders is not displayed in the interface\).

The **Orders** subsection contains an orders register with main details about every orderand with the capabilities of searching and filtering data, as well as opening the tabs of separate orders and performing various actions related to the them.

![](images/universal/cms/magento/cms_magento_orders.png "The Orders register in the Magento interface")

To open a tab of a particular order, click on the order's entry in the register. The tabs containthe details about orders\(such as the date of creation, the status, the amount of the order and the shipping address\) as well as basic information about payments and other data. The order tab consist of the following sections:

-   **Order & Account Information**—with the information about an order and a customer.
-   **Address Information**—with the information about the billing and shipping address of the customer.
-   **Payment & Shipping Method**—with the basic information about a payment shipping method.
-   **Items Ordered**—with the information about purchased products.

![](images/universal/cms/magento/cms_magento_order.png "The order tab in the Magento interface")

The **Transactions** item of the left menu contains the information about transactions within the order.Each transaction corresponds to an operation processed on the Ecommpay platform side. Thus, transactions of the following types can be created:

-   **Authorization**—in case of an authorisation hold placed on funds \(the `auth` operation\);
-   **Capture**—in case of a withdrawal of funds \(the `capture` operation for a two-step purchase or the `sale` operation for a one-step purchase\);
-   **Void**—in case of a release of funds within a two-step purchase \(the `cancel` operation\);
-   **Refund**—in case of a refund \(the `refund` operation\).

The identifier if each transaction \(**Transaction ID**\) corresponds to the identifier of the request for processing the operation in the payment platform and is assigned to the subsequent transaction in the order as the identifier of the parent transaction \(**Parent Transaction ID**\).

![](images/universal/cms/magento/cms_magento_transactions.png "The transaction register in the Magento interface")

More detailed information about working with orders in the Magento interface is provided [in the Magento documentation](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-processing.html?lang=en).

## Using Hyvä Themes {#en_cms_magento_theme}

### Overview {#section_ktt_vnk_kfc .section}

For web services based on the Magento CMS version 2.0, you can use a theme from Hyvä instead of the default Magento themes—Blank and Luma. Hyvä Themes combines the lightweight, fast-to-implement frontend with modern development tools \([details](https://www.hyva.io/)\) and is compatible with the plug-in from Ecommpay for the Magento CMS. To use it, you also need to install the following additional components:

-   Hyvä Themes version 1.3 or later—to create the frontend theme for your web service
-   Hyvä Checkout version 1.3 or later—to create the checkout page theme for your web service
-   Ecommpay Hyvä—to integrate the payment form that is adapted for use with Hyvä Checkout

With the use of the Hyvä theme, you can flexibly configure your checkout page, offering either a one-page checkout where all steps \(entering the customer's contact details, shipping and payment information\) are displayed on a single screen or a multi-step checkout that separates them into individual pages. Each checkout configuration supports both options of opening Payment Page: directly in an iframe embedded in the page or with the payment form opened in a modal window or a separate browser tab.

Note that the Ecommpay payment form integrated to work with the Hyvä theme is also backward compatible with the Blank and Luma themes; hence, using these default themes with the Ecommpay Hyvä plug-in will not affect payment acceptance rates.

### Setup and configuration {#section_az2_wnk_kfc .section}

To start using the Hyvä products with the plug-in from Ecommpay for the Magento CMS version 2.0, you should set up the required Hyvä and Ecommpay plug-ins and activate the Hyvä theme in the Magento admin panel. There are two ways to install the plug-in—*via the plug-ins directory* of Magento\(without prior download of the plug-in files\) or *using the zip files* of the plug-in\(with the plug-in files downloaded beforehand\).

The setup and configuration process consists of the following steps:

1.  Install Hyvä Themes and Hyvä Checkout and make sure their modules are listed as dependencies in your Magento project.

    To install, follow the official installation instructions for [Hyvä Themes](https://docs.hyva.io/hyva-themes/getting-started/index.html) and [Hyvä Checkout](https://docs.hyva.io/checkout/hyva-checkout/getting-started/index.html). To check, open the composer.json file located in the root folder with your Magento CMS files and find the following dependencies with the appropriate versions.

    ``` {#codeblock_hpd_cqk_kfc}
    "hyva-themes/magento2-default-theme": "^1.3",
    "hyva-themes/magento2-hyva-checkout": "^1.3"
    ```

2.  Install the Ecommpay Hyvä plug-in in addition to the plug-in from Ecommpay for the Magento CMS version 2.0 and make sure the Ecommpay modules are listed as dependencies in your Magento project.

    To install the plug-in *via the plug-in directory*, run the following Composer commands from the root folder with your Magento CMS files.

    ``` {#codeblock_f5s_vfl_kfc}
    composer config repositories.ecommpay/hyva-magento git https://github.com/ITECOMMPAY/hyva-magento.githttps://github.com/ITECOMMPAY/hyva-magento.git
    composer require ecommpay/hyva-magento
    ```

    To install the plug-in *using the plug-in zip file*, download the zip file [from GitHub](https://github.com/ITECOMMPAY/hyva-magento), unzip the folder with the plug-in files and add it to the folder with the source code of the web service built on the Magento CMS.

    If the Ecommpay plug-in for the Magento CMS version 2.0 has not been installed yet, it will be installed automatically along with the Ecommpay Hyvä plug-in via the plug-in directory, or you can install it manually using the plug-in zip file \([details](en_CMS__magento.md)\).

    Then, proceed to open the composer.json file located in the root folder with your Magento CMS files and confirm that `ecommpay/hyva-magento` and `ecommpay/module-payments` are listed as dependencies.

3.  Enable the installed plug-ins by running the following Composer commands.

    ``` {#codeblock_dtb_x4k_kfc}
    bin/magento setup:upgrade
    bin/magento cache:flush
    bin/magento cache:clean
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy
    ```

4.  Activate Hyvä Themes for your web service and configure settings of plug-ins in the Magento admin panel.

    To do so, follow the official installation instructions for [Hyvä Themes](https://docs.hyva.io/hyva-themes/getting-started/index.html) and [Hyvä Checkout](https://docs.hyva.io/checkout/hyva-checkout/getting-started/index.html).

    **Note:** Note that the data set mandatory for processing card payments includes parameters required for performing the AVS \(Address Verification Service\) check. To submit these data with Payment Page embedded directly into the web service interface \(in an iframe element\), use the fields for collecting the customer's postal code and shipping address on the checkout page. To do so, mark the `postcode` field and at least one field from the `street` group as required in the Hyvä Checkout plug-in settings.

5.  Make sure that the Hyvä theme is applied to your web service and the Ecommpay Hyvä plug-in is enabled.

    To do so, check that the theme is visible on the frontend of your web service and on the checkout page. It is also recommended that you make a test card purchase and, as you place an order, proceed as far as to the step of entering payment details to ensure that the Ecommpay payment form opens correctly.


If you encounter questions related to the Ecommpay Hyvä plug-in installation, contact the Ecommpay technical support.

## Parameters for using payment methods {#en_cms_magento_methods}

When working with the plug-in from Ecommpay, in the Magento interface, you can set up the usage of various payment methods available in the merchant's project. You can do this via separate accordion items on the page with the plug-in operation parameters—**Card payments** \(with parameters for card payments\)and **Alternative payment settings** \(with parameters for using alternative methods\). The latter contains another accordion item **More payment methods via Ecommpay** in which you can set up the usage of all methods available in the project—this can be relevant in case of working with methods for which no separate parameters are allocated in the plug-in operation parameters.

**Note:** The accordion items displayed by default cannot be removed from the plug-in operation parameters even if the corresponding methods are not used in the project. If other methods are needed, their usage can be set up only via the **More payment methods via Ecommpay** accordion item once the Ecommpay technical support specialists enable these methods in the project upon the merchant's request.

The accordion items for payment methods setup contain the following parameters:

-   General parameters:
    -   **Enabled**—the feature for enabling a payment method to work via the plug-in.

        To enable a method, set the value **Yes**, to disable a method, set the value **No**.

    -   **Title**—the payment method namedisplayed on the checkout page in the web service.
    -   **Show Description**—the feature for displaying the text from the **Description** parameter.
    -   **Description**—the text displayed to the customers when they select a certain payment method.
    -   **Sort Order**—the number that indicates the order in which the payment method available via the plug-in from Ecommpay is displayed on the checkout page in the web service.

        For a payment method to be displayed first on the list of methods, specify the value `0` or leave the field blank. Along with that, if a payment method is disabled in the web service, its place on the list of methods is taken by the payment method with the next number. If the `0` value is specified or the **Sort Order** field is left blank for several methods, the order in which these methods are displayed reflects the order of the accordion items with the parameters for using these methods.

-   Parameters used only in the **Card payments** accordion item:

    -   **Display mode**—the option for opening the Payment Page payment form.

        One of the following options can be selected:

        -   **Redirect**—opening as a separate HTML page;
        -   **Popup**—opening in a modal window;
        -   **Embedded**—opening in an iframe element

            **Note:** After installing the plug-in or updating its version, this option is set up by default.

        If the payment form is opened in an iframe element\(the **Embedded** option\), then, when the customer selects to make the purchase using a payment card, the Payment Page payment form is displayed in the section with payment options on the checkout page, is adapted to the standard checkout page design in the web service, and does not contain the button for confirming the purchase. In this payment form, the customer can select the payment card credentials \(if they were saved earlier\) or specify them and then confirm the purchase by using the checkout button on the web service page. When selecting other payment methods, the customer is redirected to subsequent pages.

        ![](images/universal/cms/magento/cms_magento_pp_embedded.png "Example of opening the Payment Page payment form on the checkout page")

    ![](images/universal/cms/magento/cms_magento_settings_card.png "The accordion item Card payments with parameters for card payments")

-   The parameter used only in the **More payment methods via Ecommpay** accordion item:

    -   **Payment method code**—the code of a payment method used as the only additional one \(in relation to the methods which are set up via separate accordion items\).

        -   Without this parameter used, when the customer selects a purchase method in the web service interface, they can select the **More payment methods** option, proceed to the payment form, and select one of the methods available for the payment being initiated in the Ecommpay platform.Along with that, all methods from Ecommpay that can be selected directly in the web service \(together with the **More payment methods** option\) become available in the payment form.
        -   With this parameter containing the code of one of the available methods\(taken [from the reference](en_pm_codes.md)\), when the customer selects a purchase method in the web service interface, among other available methods, they can select the one specified via the code and proceed to paying via this method without selecting any other methods in the payment form.To prevent issues that may be triggered by such a selection, alongside the payment method code, the name of the method should also be specified in this section \(in the **Title** field\).
        **Note:** Since in the plug-in test mode, it is possible to process only card purchases, the work of the **More payment methods via Ecommpay** accordion item in this mode can be tested only for the `card` method.

    ![](images/ecommpay/cms/magento/cms_magento_settings_pm.png "The accordion item More payment methods via Ecommpay with parameters for using all payment methods")




---

# Using Ecommpay payments for PrestaShop CMS {#en_cms_prestashop}

An article about using a plug-in for embedding Payment Page into websites powered by the PrestaShop CMS platform.

**Parent topic:**[Integration using plug-ins](en_CMS.md)

## Overview {#en_cms_prestashop_overview}

This article covers the information about using the payment plug-in Ecommpay payments version 2.0.0. This plug-in version can be used in web services that are based on the PrestaShop CMS version 8.1.5 or later.

The Ecommpay payments plug-in is installed via the PrestaShop interface and allows opening the Payment Page payment form of Ecommpay for customers and ensuring all necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform \(with all necessary information sent and received\).

![](images/ecommpay/cms/prestashop/cms_prestashop_orders_overview.svg "Administrative interface PrestaShop")

![](images/unimethods/en_pp_browser_tab.svg "Interface of the Payment Page payment form")

## General information {#en_cms_prestashop_general}

### Capabilities {#section_lbv_jb2_lwb .section}

With the Ecommpay payments plug-in, the following is available:

-   Setting up the capability to open the Payment Page payment form of Ecommpay in the web service on the fly.

    For this, you only need to take a few actions in the interface of the PrestaShop CMS.

-   Setting up the usage of separate payment methods available via the plug-in: payments made with the direct use of payment cards, the Apple Pay and Google Pay methods, and other alternative methods\(if they are available for the project in use\).

    For this, you can use the tabs with parameters of using payment methods on the plug-in configuration page in the PrestaShop interface.

-   Testing the operation of the payment form and the capabilities of payment processing.

    For this, you can get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\) and use the identifier and secret key of this project.

-   Processing one-time one-step purchaseswith the use of various payment methods.

    For resolving all organisational issuesand setting up different payment methods, contact the Ecommpay account manager.

-   Issuing partial and full refunds for purchases, which were processed with the help of the plug-in.

    For this, you can use the PrestaShop interface and, if relevant, the interfaces of the Ecommpay payment form \(the user interface Dashboard and the Gate API\). Along with that, when using the interfaces of the Ecommpay payment platform, order information in the PrestaShop interface is updated only if conditions for sending callbacks from the payment platform have been configured \([details](en_dbl_projects.md)\).

-   Monitoring the information about payments, which were processed with the help of the plug-in.

    For this, you can use the PrestaShop and, if relevant,—the Data API and the Dashboard interface of Ecommpay.

-   Managing orders with related purchases processed with the help of the plug-in.

    For this, you can use the PrestaShop interface that allows cancelling these orders and changing their statuses manually \(if necessary\).

-   Configuring the parameters of the Payment Page operation and adjusting the form to the web service specifics, as well as using various capabilities provided by Ecommpay.

    Particularly, you can use the payment confirmation procedure when working with the Open Banking methods \([details](pm_openbanking.md#section_yln_qjn_ftb)\), provide customers with the capability of payment retries \([details](en_PP_Try_Again.md)\), and set up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\).


This range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure a high rate of the payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists.

### Workflow {#section_wtg_4v3_mwb .section}

The following diagram illustrates the workflow of executing purchases with the use of the Ecommpay payments plug-in. The workflow involves the customer, the merchant's web service with the built-in plug-in, the Payment Page payment form, the payment platform, and the payment environment. On the web service side, the opening of Payment Page is requested and automatic interaction with the payment platform is carried out in accordance with the plug-in parameters.

![](images/universal/cms/en_cms_workflow.svg)

1.  On the web service side, the customer selects the option to pay with the use of the Ecommpay payments plug-in.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions for purchase and confirms the purchase.
8.  The final purchase request \(with all necessary data\) is received in the platform.
9.  The request is sent to the payment environment.
10. The request is processed in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, for the 3‑D Secure authentication\).
11. The purchase result information is sent from the payment environment to the payment platform.
12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the order information is updated in the PrestaShop interface.
13. The purchase result information is sent from the payment platform to Payment Page.
14. The purchase result information is displayed to the customer eitherin the Payment Page payment form\(if the form was opened in a modal window or a separate tab\) or on the web service page \(if the form was opened directly in the web service\).

### Options for using the payment form {#section_rtj_mwk_bgd .section}

Different options for invoking Payment Page can be used within the described general workflow of the Ecommpay payments plug-in:

-   For card payments, the payment form embedded directly into the web service interface \(in an iframe element\) is the default option. Opening the payment form in a modal window or a separate tab is also available for card payments.
-   For alternative payment methods, opening the payment form in a separate tab is the only option.

When the Payment Page payment form is embedded directly into the web service interface \(in an iframe element\), the customer specifies the payment card credentials and confirms the order in the PrestaShop CMS and the payment initiated in the Ecommpay platform directly on the web service page for proceeding to payment \(using the **Place Order** button\).

When the Payment Page payment form is opened in a modal window or a separate tab, the customer first confirms the order generated in the PrestaShop CMS on the web service page for proceeding to payment \(using the **Place Order** button\) and only after that specifies the necessary data in the payment form and confirms the payment initiated in the Ecommpay platform \(using the **Pay** button\).

![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_embedded.svg "Payment form embedded into the web service interface")

![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_popup.svg "Payment form opened in a modal window")

More information about opening Payment Page is provided [in the corresponding articles](en_PP_Integration.md).

### Monitoring orders and payments {#section_vgh_wyk_bge .section}

While working with the Ecommpay payments plug-in, keep in mind that orders in the web service and payments in the payment platform have different identifiers and statuses.Orders are assigned ordinal numbers \(for example, `71`\) and statuses associated with payment statuses in the Ecommpay platform:

-   `Ecommpay: Pending` if the payment has an intermediate status.
-   `Ecommpay: Approved` if the payment has been processed.
-   `Ecommpay: Declined` if the payment has been declined.
-   `Ecommpay: Partially refunded` if a partial refund has been made within the order.
-   `Ecommpay: Refund` if a full refund has been made within the order.

Similarly, payments on the payment platform side are assigned identifiers that consist of the prefix `pt_` and ten arbitrary characters \(for example, `pt_64ca3135cf`\) and statuses that you can look up in the section about the payment processing model \([details](en_platform_payment_model.md)\). With questions about the statuses of payments and orders, contact your Ecommpay account manager.

## Installation {#en_cms_prestashop_installation}

To start using the Ecommpay Payments plug-in version 2.0.0, you need to install it.

If an earlier version of this plug-in was previously used, before updating the plug-in, it is recommended to do the following:

1.  Copy the values of parameters of the plug-in operation for further use with the new plug-in version.

    This is because updating the plug-in leads to clearing the parameters which means you have to set up them again.

2.  Deactivate the earlier version of the plug-in.

    This can be done via the register with the installed plug-ins in the PrestaShop interface, using the **Uninstall** button.


To install the plug-in, download its [zip file](https://github.com/ITECOMMPAY/ecommpay-prestashop) and proceed in the PrestaShop interface as follows:

1.  Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu.
2.  Click the **Upload a module** button on the **Module Manager** page and select the previously downloaded zip file of the plug-in.
3.  Wait for the completion of the download and automatic installation of the plug-in.

Upon the completion of these steps, you can find the Ecommpay payments plug-in panel on the **Module Manager** page and proceed to working with the plug-in.

![](images/ecommpay/cms/prestashop/cms_prestashop_installation.png "Module Manager page with the plug-in panel in the PrestaShop interface")

## Testing {#en_cms_prestashop_testing}

### Overview {#en_cms_prestashop_testing_overview}

Testing the plug-in operation and various payment scenarioswithout actual debiting of funds is possible via the test environment of the Ecommpay payment platform. You can connect to the platform by using the corresponding form [on the company's main site](https://ecommpay.com/apply-now/) andthe identifier and secret key of the test project received from Ecommpay.Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service for which the plug-in from Ecommpay will be used, the web service URL, and the payment currency.

Keep in mind that when you use the testing environment of the Ecommpay payment platform, the plug-in will be connected to the web service and will become available as a payment option to the customers. Therefore, it is recommended that if you need to connect the plug-in to the web service in production mode, test the plug-in operation during the low-load time and warn your customers about planned maintenance.

### Parameters setup {#en_cms_prestashop_testing_setup}

To prepare the plug-in for testing, decide on the preferable testing option and set up the plug-in in the PrestaShop interface. For this, proceed as follows:

1.  Go to the plug-in operation parameters in the PrestaShop interface.

    For this, proceed as follows:

    1.  Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu.
    2.  Search for the Ecommpay payments plug-in on the page that opens and click the **Configure** button in the corresponding line.
2.  Set up the basic parameters of the plug-in operation in the **General Settings** taband save changes by clicking **Save Settings**:

    -   **Project ID**—the test project identifier.
    -   **Secret key**—the test project key.
    -   **Language**—the language in which the payment form is displayed.
    ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Tab with the basic parameters of the plug-in operation")

3.  Set up the general parameters for using the payment method on its setup taband save changes by clicking **Save Settings**:
    -   **Enabled**—the setting for enabling a payment method to work via the plug-in.

        To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected.

    -   **Title**—the payment method namedisplayed on the checkout page in the web service.
    -   **Description**—the text displayed to the customers when they select a certain payment method.

        **Note:** If necessary, the fields **Title** and **Description** can be used for notifying customers that the plug-in is operating in the test mode.

4.  If necessary, set up the other parameters for using payment methods \([details](en_cms_prestashop.md)\) and save changes by clicking **Save Settings** in each tab.

### Processing test purchases {#en_cms_prestashop_testing_purchase}

When testing the plug-in operation, you can process test purchases in the web service and obtain information about them via the PrestaShop, in the **Orders** subsection of the **Orders** section. Along with that, you can use special payment credentials that allow testing particular payment scenarios.

To test card payments, you can use the credentials of test cards. For testing according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used:

-   `4000 0000 0000 0077`—for a purchase to be processed
-   `4111 1111 1111 1111`—for a purchase to be declined

For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article.

To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists in the test environment of payment platform\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the corresponding sections of the articles about working with particular payment methods.

### Processing test refunds {#en_cms_prestashop_testing_refund}

#### Overview {#section_ddh_41r_kbc .section}

After processing test purchases, you can make test refundsvia the PrestaShop interface and, if relevant, via [the Gate API](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Refunds can be made for payments that meet two conditions. First, they must be the payments made using methods that support refunds. Second, they must be the payments for which the full amount has not been refunded—on the payment platform side, such payments are assigned statuses `success`, `partially reversed`, or `partially refunded`. You can monitor the execution of refunds through the Ecommpay platform interfaces and the PrestaShop interface. Also, note that all information about test refunds provided in this subsection is also relevant for issuing refunds in the production environment.

#### Ensuring data synchronisation {#section_qvf_z1r_kbc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the PrestaShop interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the PrestaShop interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the PrestaShop interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the PrestaShop CMS, to the URL specified on the page with the plug-in operation parameters \(in the format of `https://<sitedomain>/en/module/Ecommpay/callback`\), are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

#### Procedures {#section_efy_1ck_kbc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay platform and the PrestaShop interface.

To make a refund via the PrestaShop interface, proceed as follows:

1.  Open the tab of the order that should be refunded.

    For this, select the **Orders** item in the similarly-named section of the **SELL** section and click the line of the needed order.

2.  Initiate the refund.

    For this, proceed as follows:

    1.  Open the **Products** panel by clicking the **Partial refund** button.
    2.  Specify the refund amount in the **Amount \(Tax included\)** field and select the **Refund via Ecommpay** checkbox.
    3.  Click the **Partial refund** button in the bottom right corner of the **Products** panel.
3.  Ensure that the refund has been made.

    For this, you can check that the order status has changed to `Ecommpay: Partially refunded` \(in case of a partial refund\) or `Ecommpay: Refund` \(in case of a full refund\).


![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Products panel with the capability to issue refunds in the order tab")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

## Usage {#en_cms_prestashop_usage}

### Overview {#en_cms_prestashop_usage_overview}

In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web servicefor which the Ecommpay payments plug-in will be used and the currency in which payments are to be processed.

After that, specify the identifier and secret key of the production project received from Ecommpay in the parameters of the plug-in operation and set up other necessary parameters\(or check whether the current setup is relevant for working in real-life conditions\). If later you need to suspend the plug-in operation, the plug-in methods can be disabled. Besides, if additional testing is needed, for example when setting up new features, the plug-in can be switched to using the test project.

### Parameters setup {#en_cms_prestashop_usage_setup}

To set up the plug-in parameters, proceed as follows:

1.  Go to the plug-in operation parameters in the PrestaShop interface.

    For this, proceed as follows:

    1.  Select the **Modules** section and the **Module Manager** item in the **IMPROVE** section of the navigation menu.
    2.  Search for the Ecommpay payments plug-in on the page that opens and click the **Configure** button in the corresponding line.
2.  Set up the basic parameters of the plug-in operation in the **General Settings** taband save changes by clicking **Save Settings**:

    -   **Project ID**—the production project identifier.
    -   **Secret key**—the production project secret key.
    -   **Language**—the language in which the payment form is displayed.
    ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Tab with the basic parameters of the plug-in operation")

3.  Set up the general parameters for using the payment method on its setup taband save changes by clicking **Save Settings**:
    -   **Enabled**—the feature for enabling a payment method to work via the plug-in.

        To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected.

    -   **Title**—the payment method namedisplayed on the checkout page in the web service.
    -   **Description**—the text displayed to the customers when they select a certain payment method.

        **Note:** If during testing the fields **Title** and **Description** were used for notifying customers about ongoing testing activities, when switching to work in the production project, it is important to remove the notifications.

4.  If necessary, set up the other parameters for using payment methods \([details](en_cms_prestashop.md)\) and save changes by clicking **Save Settings** in each tab.

### Processing purchases {#en_cms_prestashop_usage_purchase}

If the web service and the plug-in have been set up correctly, purchases are processed automatically.Along with that, it is important to ensure that all necessary data is collected on the web service side.

**Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page.

In case of questions or issues related to purchase processing, contact the Ecommpay technical support specialists.

### Issuing refunds {#en_cms_prestashop_usage_refund}

After processing purchases, you can issue refunds as part of these purchasesvia the PrestaShop interface and, if relevant, via the interfaces [Gate](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the PrestaShop interface have the statuses `Ecommpay: Approved` or `Ecommpay: Partially refunded` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all capabilities and procedures of working with refunds in the production environment correspond to those available in the test environment.

#### Ensuring data synchronisation {#section_ac1_mhm_sbc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), order information in the PrestaShop interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the order information via the PrestaShop interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the PrestaShop interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the PrestaShop CMS, to the URL specified on the page with the plug-in operation parameters \(in the format of `https://<sitedomain>/en/module/Ecommpay/callback`\), are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

#### Procedures {#section_fkp_mhm_sbc .section}

Refunds are available for purchases that have been processed and not fully refunded.On the Ecommpay payment platform side, such purchases have the statuses `success`, `partially reversed`, and `partially refunded`. You can monitor the processing of refunds via the interfaces of the Ecommpay platform and the PrestaShop interface.

To make a refund via the PrestaShop interface, proceed as follows:

1.  Open the tab of the order that should be refunded.

    For this, select the **Orders** item in the similarly-named section of the **SELL** section and click the line of the needed order.

2.  Initiate the refund.

    For this, proceed as follows:

    1.  Open the **Products** panel by clicking the **Partial refund** button.
    2.  Specify the refund amount in the **Amount \(Tax included\)** field and select the **Refund via Ecommpay** checkbox.
    3.  Click the **Partial refund** button in the bottom right corner of the **Products** panel.
3.  Ensure that the refund has been made.

    For this, you can check that the order status has changed to `Ecommpay: Partially refunded` \(in case of a partial refund\) or `Ecommpay: Refund` \(in case of a full refund\).


![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Products panel with the capability to issue refunds in the order tab")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

### Monitoring payments and orders {#en_cms_prestashop_usage_monitoring}

Information about payments processed with the use of the Ecommpay payments plug-in and about the corresponding orders can be monitored via the PrestaShop interfaceby using the tools of the **Orders** section in the similarly-named subsection, while more detailed information about payments and refunds can be obtained via Dashboard \([details](en_dbl_payments.md)\) and Data API \([details](en_dbl_using_api.md)\) from Ecommpay.

In the PrestaShop interface, the **Orders** subsection contains orders register with main details about every order including the capabilities to search and filter data, open the tabs of separate orders, and perform various actions.

![](images/ecommpay/cms/prestashop/cms_prestashop_orders.png "Orders register in the PrestaShop interface")

To open the tab of a particular order, click on the order's entry \(or the button ![](images/universal/cms/prestashop/cms_prestashop_icon_view.png)\) in the register. Each tab, among other functions, provides order details \(such as the information about customers, purchased products, and shipping methods\) as well as the capability to make refunds.

For information about the payment initiated via the plug-in from Ecommpay, use the **Payment** section.This section displays the information about the payment amount and currency and other relevant data. Along with that, keep in mind that specific information regarding the status and details of the payment \(in particular, the payment method selected by the customer\) is updated based on the callbacks received from the payment platform.

![](images/ecommpay/cms/prestashop/cms_prestashop_order_tab.png "Order tab in the PrestaShop interface")

More detailed information about working with orders can be obtained by using the **Help** button in the similarly-named subsection in the **Orders** section in the PrestaShop interface.

## Parameters for using payment methods {#en_cms_prestashop_methods}

When working with the plug-in from Ecommpay, in the PrestaShop interface, you can set up the usage of various payment methods available in the merchant's project. You can do this on the page with the plug-in operation parametersvia separate tabs—for example, **Card Settings** \(with parameters for card payments\), **Apple Pay** \(with parameters for payments with the Apple Pay service\), **Google Pay** \(with parameters for payments with the Google Pay service\), and **More Methods** \(with parameters for payments with other alternative methods\).

The tabs for payment methods setup contain the following parameters:

-   General parameters:
    -   **Enabled**—the feature for enabling a payment method to work via the plug-in.

        To enable a method, select the **Enabled** checkbox. By default, the checkbox is not selected.

    -   **Title**—the payment method namedisplayed on the checkout page in the web service.
    -   **Description**—the text displayed to the customers when they select a certain payment method.
-   Parameters used only in the **Card Settings** tab:
    -   **Display mode**—the option for opening the Payment Page payment form.

        One of the following options can be selected:

        -   **Redirect**—opening as a separate HTML page;
        -   **Popup**—opening in a modal window;
        -   **Embedded**—opening in an iframe element. After installing the plug-in or updating its version, this option is set up by default.
        ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_card.png "Card Settings tab with parameters for card payments")

        If the payment form is opened in an iframe element\(the **Embedded** option\), then, when the customer selects to make the purchase using a payment card, the Payment Page payment form is displayed in the section with payment options on the checkout page, is adapted to the standard checkout page design in the web service, and does not contain the button for confirming the purchase. In this payment form, the customer can select the payment card credentials \(if they were saved earlier\) or specify them and then confirm the purchase by using the checkout button on the web service page. When selecting other payment methods, the customer is redirected to subsequent pages.

        ![](images/ecommpay/cms/prestashop/en_cms_prestashop_pp_embedded.png "Example of opening Payment Page on the checkout page in an inframe element")

-   The parameter used only in the **More Methods** tab:

    -   **Payment method code**—the code of a payment method used as the only additional one \(in relation to the methods which are set up via separate accordion items\).
        -   Without this parameter used, when the customer selects a payment method in the web service interface, they can select the option specified in the **Title** field \(**More payment methods** is the default option\), proceed to the payment form, and select one of the methods available for the payment initiated in the Ecommpay platform.Along with that, all methods from Ecommpay that can be selected directly in the web service \(together with the **More payment methods** option\) become available in the payment form.
        -   With this parameter containing the code of one of the available methods\(taken [from the reference](en_pm_codes.md)\), when the customer selects a payment method in the web service interface, among other available methods they can select the one specified via the code and proceed to paying with this method without selecting any other methods in the payment form.To prevent issues that may be triggered by such a selection, alongside the payment method code, the name of the method should also be specified in this section \(in the **Title** field\).
    ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_pm.png "More Methods tab with parameters for other alternative methods")




---

# Using Ecommpay Payments plug-in for WordPress CMS {#en_CMS__wordpress}

An article about using a plug-in for embedding Payment Page into websites powered by the WordPress CMS platform with the installed WooCommerce plug-in.

**Parent topic:**[Integration using plug-ins](en_CMS.md)

## Overview {#en_cms_wordpress_overview}

This article covers the information about using the payment plug-in Ecommpay Paymentsversion 5.0. This plug-in version enhances the capabilities of the WooCommerce plug-in for web services that are based on the WordPress CMSin accordance with the following conditions:

-   the WordPress CMS version is 6.2 or later,
-   the WooCommerce plug-in version is 8.2 or later,
-   the PHP language version is 7.4 or later.

The Ecommpay Payments plug-in is installed via the WordPress interface and allows opening the Payment Page payment form of Ecommpay for customers and ensuring all necessary actions for payment processing with regard to the interaction with both customers and the Ecommpay payment platform \(with all necessary information sent and received\).

![](images/ecommpay/cms/wordpressplugin/cms_wordpress_methods.png "Administrative interface WordPress")

## General information {#en_cms_wordpress_general}

### Capabilities {#section_lbv_jb2_lwb .section}

With the Ecommpay Payments plug-in, the following is available:

-   Setting up the capability to open the Payment Page payment form of Ecommpay in the web service on the fly.

    For this, you only need to take a few actions in the interface of the WordPress CMS.

-   Setting up the usage of separate payment methods available in the merchant's project.

    For this, you can use the tabs with parameters of using payment methods in the plug-in tab of the WordPress interface.

-   Testing the operation of the payment form and the capabilities of payment processing.

    For this, you can get a test project in the Ecommpay payment platform \(by submitting [an application](https://ecommpay.com/sign-up/) on the company's main site\) and use the identifier and secret key of this project.

-   Processing one-time one-step or two-step purchases.

    Within a single project, you can select one option to process purchases: when funds are debited immediately \(in one step\) using any of the set up payment methods or when funds are first authorised and then either withdrawn or released \(in two steps\) using any of the methods which support processing of such purchases via Payment Page.

-   Registering and processing COF purchases \(*subscriptions*\)with the direct use of payment cards and the use of the Apple Pay and Google Pay methods—if the web service has the [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/) extension installed.

    For this, you can manage the properties of such purchases \(such as the payment amount and schedule, free trial period\), inform customers about subscription related events, and combine different purchases into a single order.

-   Issuing partial and full refunds for purchases, which were processed with the help of the plug-in.

    You can do this as part of working with payment methods for which refunds are supported by initiating the operations via the WordPress interface and, if relevant, via the interfaces of the Ecommpay payment platform \(the Dashboard user interface and the Gate API\). Along with that, when using the interfaces of the Ecommpay payment platform, payment and order information in the WordPress interface is updated only if conditions for sending callbacks from the payment platform have been configured \([details](en_dbl_projects.md)\).

-   Monitoring the information about payments, which were processed with the help of the plug-in.

    For this, you can use the WordPress interface and if relevant—the Dashboard interface from Ecommpay, with the information in these interfaces synchronised.

-   Managing orders with related purchases processed with the help of the plug-in—via the WordPress interface.

    This includes cancelling and deleting these orders and changing their statuses manually \(if necessary\).

-   Configuring the parameters of the Payment Page operation and adjusting the form to the web service specifics, as well as using various capabilities provided by Ecommpay.

    Particularly, you can use the payment confirmation procedure when working with Open Banking methods, provide customers with the capability of payment retries \([details](en_PP_Try_Again.md)\), and set up sending notifications to customers about the purchased goods and services \([details](en_PP_receipt_data.md)\). To have these capabilities set up, contact the Ecommpay technical support specialists.

-   Using various capabilities provided by the developers of the WooCommerce plug-in.

    Particularly, you can set up the usage of this plug-in \(and the connected Ecommpay Payments plug-in\) in different countries \([details](https://woocommerce.com/document/setting-up-shipping-zones/)\).


This range of capabilities allows you to adjust to various business specifics, flexibly configure user scenarios, and ensure a high rate of the payment form conversion and payment acceptance. For setting up and using the capabilities provided by Ecommpay, refer to the technical documentation on this portal and, if necessary, contact the Ecommpay specialists. With questions about using various capabilities for the WooCommerce plug-in, refer to the documentation [on the corresponding portal](https://woocommerce.com/documentation/).

### Workflows {#section_wsr_ndl_zdc .section}

The following diagram illustrates the workflows of executing purchases with the use of the Ecommpay Payments plug-in. The workflows involve the customer, the merchant's web service with the built-in WooCommerce and Ecommpay Payments plug-ins, the Payment Page payment form, the payment platform, and the payment environment. On the web service side, the opening of Payment Page is requested and automatic interaction with the payment platform is carried out in accordance with the plug-in parameters.

In case of *one-step purchases*, one initial request leads to a one-time transfer of funds from the customer to the merchant which is followed by a callback with the information about the payment result sent to the web service.

![](images/universal/cms/en_cms_workflow.svg)

1.  On the web service side, the customer opens the checkout page of the WooCommerce interfaceand selects a payment method set up via the Ecommpay Payments plug-in. Usually along with that, an order is automatically created in the web service.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, with regards to the method selected by the customer.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare either for displaying the payment form or for redirecting the customer to a third-party service, in accordance with the parameters for opening the payment form.
6.  The payment form is displayed to the customer or the customer is redirected to a third-party service—depending on the selected payment method.
7.  The customer completes the required actions for purchase and confirms the purchase.
8.  The final purchase request \(with all necessary data\) is received in the platform. In case of redirecting the customer to a third-party service, the final request can be received at step 5.
9.  The request is sent to the payment environment.
10. The request is processed in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, for the 3‑D Secure authentication\).
11. The purchase result information is sent from the payment environment to the payment platform.
12. The callback with the purchase result information is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the payment information is updated in the WordPress interface.
13. The purchase result information is sent from the payment platform to Payment Page.
14. The purchase result information is displayed to the customer: in the merchant's web service, on the page with the information about the paid order of the WooCommerce interface, \(in the general case\) or in the Payment Page payment form \(in case if the capability of payment retries is set up\).

In case of *two-step purchases*, based on an initial request\(at the first step\), the funds are held on the customer's account and then\(at the second step\), based on the next request or automatically after a specified period of time, the funds are transferred to the merchant or released. Along with that, at each step, a callback with the information about the corresponding result is sent to the web service.

![](images/ecommpay/cms/wordpressplugin/en_cms_workflow_auth.svg)

1.  On the web service side, the customer opens the checkout page of the WooCommerce interfaceand selects a payment method set up via the Ecommpay Payments plug-in. Usually along with that, an order is automatically created in the web service.
2.  The request for opening the Payment Page payment form is automatically generated and sent to the payment platform via the plug-in, with regards to the method selected by the customer.
3.  The request for opening Payment Page is received in the payment platform.
4.  The request is processed in the payment platform and checked for correctness.
5.  The necessary actions are performed on the payment platform side to prepare for displaying the payment form to the customer.
6.  The payment form is displayed to the customer.
7.  The customer completes the required actions and confirms the purchase.
8.  The request for authorisation hold is received in the platform.
9.  The request is sent to the payment environment.
10. The payment is processed and the funds are authorised in the payment environment. And if necessary, additional actions are performed on the side of the platform and the customer \(for example, the 3‑D Secure authentication\).
11. The information about the authorisation hold result is sent from the payment environment to the payment platform.
12. The callback with the information about the authorisation hold result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the order and payment statuses are updated in the WordPress interface.
13. The information about the authorisation hold result is sent from the payment platform to Payment Page.
14. The information about the authorisation hold result is displayed to the customer on Payment Page.
15. After it has been confirmed that the funds should be withdrawn, the merchant's specialist initiates the withdrawal, and as result, a request for withdrawing the funds is received and processed in the payment platform \(which is done with the help of the plug-in\).
16. The request is sent to the payment environment.
17. The payment is processed in the payment environment.
18. The information about the withdrawal result is sent from the payment environment to the payment platform.
19. The callback with the information about the withdrawal result is sent from the payment platform to the web service. The callback is automatically processed with the help of the plug-in, thus the order and payment statuses are updated in the WordPress interface.
20. The customer is notified about the withdrawal result by the means of the web service.

### Options for opening Payment Page {#section_arb_hfz_djc .section}

Three options are available for interacting with customers when processing one-step payments and placing authorisation holds in two-step payments:

-   `Redirect`—for opening the payment form in a separate browser tab\([details](en_PP_method_NewTab.md)\). This option applies to all payment methods and is activated by default upon plug-in installation, during version updates, and in cases where another selected option is unavailable.
-   `Popup`—for opening the payment form in a modal window on top of the web service interface\([details](en_PP_method_ModalWindow.md)\). This option is applicable to most payment methods, and in cases where it cannot be used, it is replaced by the `Redirect` option.
-   `Embedded`—for embedding the payment form directly into the web service interface\(via an iframe element; [details](en_pp_microframe_solution.md)\). This option is only applicable to standard card payments and subject to prior approval from Ecommpay technical support.

    When opened in an iframe, the payment form does not contain the button for confirming the purchase.The form is displayed in an element for using a payment card directly, and the customer can select their payment card details \(if previously saved\) or enter them, and then confirm the purchase by using the corresponding button in the WooCommerce user interface. If this option is selected and the customer selects another payment method, the customer is redirected to the payment form as a separate page\(using the `Redirect` option\).


![](images/ecommpay/cms/wordpressplugin/cms_wordpress_redirect.svg "Payment Page opened in a separate tab")

![](images/ecommpay/cms/wordpressplugin/cms_popup.svg "Payment Page opened in a modal window")

![](images/ecommpay/cms/wordpressplugin/cms_wordpress_embedded.svg "Payment Page opened in an iframe element of the web service interface")

You can customise the option for opening the payment form separately for each payment method via the plug-in tab\([details](en_CMS__wordpress.md)\).

### Monitoring orders and payments {#section_qtr_gfz_djc .section}

When working with the Ecommpay Payments plug-in, keep in mind that different identifiers and statuses are used for orders in the web service and payments in the payment platform.

The process of creating an order and then a payment depends on which option for opening the payment form is used and whether payment retries are triggered.

-   If the payment form is opened using the `Embedded` option\(via an iframe element; [details](en_pp_microframe_solution.md)\), the order and payment are created only after the customer confirms the purchase. In this case, the payment identifier consists of the `wp_` prefix and an arbitrary sequence of ten characters\(for example, `wp_ert12h2t1o`\). Along with that, each payment retry results in the creation of a new order and a new payment.
-   If any other option\(except `Embedded`\) is used to open the payment form, the order is created after the customer proceeds to pay and opens the payment form, and the payment is initiated after the customer confirms the purchase in the payment form interface. In this case, the payment identifier consists of the number of the order and the number of the attempt to pay for this order in the web service\(for example, the identifier can be `123_2` if the customer makes the second attempt to pay for order number `123`\). Along with that, if the capability of payment retries is used, the final digit of the payment identifier always equals one, since all payment retries are made within one payment \(for example, the identifier can be `123_1` even if the customer made at least two attempts to pay for the order\).

Orders and payments are assigned statuses from two different status models. Payments processed via the Ecommpay payment platform are assigned statuses based on the Ecommpay payment model, while orders created on the web service side are assigned statuses used by WooCommerce \([details](https://woocommerce.com/document/managing-orders/#visual-diagram-to-illustrate-order-statuses)\).You can monitor the information about these payments and statuses in the sections of the WordPress interface: **Orders** \(for one-time purchases\) and **Subscriptions** \(for COF purchases\). With questions about the statuses of payments and orders, contact your Ecommpay account manager.

## Installation {#en_cms_wordpress_installation}

### General information {#section_qr4_2f3_bxb .section}

To start using the Ecommpay Payments plug-inversion 5.0, you need to install it. Along with that, if an earlier version of this plug-in was previously used, it is recommended to deactivate this version before installing the new one\(you can do it through the list of installed plug-ins in the WordPress interface\). There are two ways to install the plug-in in the WordPress interface—*via the plug-ins directory* of WordPress \(without prior download of the plug-in file\) or *via the plug-ins upload function* in the WordPress interface \(with the plug-in file downloaded beforehand\). The plug-in file can be downloaded [from the directory](https://wordpress.org/plugins/ecommpay-payments/) or [from GitHub](https://github.com/ITECOMMPAY/woocommerce-ecommpay).

**Warning:** If before the plug-in installation, one of its previous versions has been used and not deactivated, then, after the installation, you may see a notification in the WordPress interface stating that an update is needed. In this case, click the **Run the updater** button and wait for the parameters update. Otherwise, previously used settings may be lost.

### Installation via the plug-ins directory {#section_eb1_pf3_bxb .section}

To install the plug-in via the directory, go to the WordPress interface and proceed as follows:

1.  Select the **Plugins** section in the navigation menuand the **Add New Plugin** itemin the menu that appears.
2.  Search for the Ecommpay Payments plug-in from Ecommpayon the page that opens.

    For this, use the search box on the right side of the page and ensure that the plug-in in the search results is provided by Ecommpay \(this is stated on the plug-in panel\).

3.  Click the **Install now** button \(or the **Update Now** button if an earlier plug-in version was used\) on the panel and wait for the installation completion.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_shop_installation.png "The CMS WordPress page used for installing plug-ins from the directory")

4.  Activate the plug-in using the **Activate** button, which is displayed instead of the **Install now** button \(or instead of the **Update Now** button\) after the installation.
5.  If the plug-in is being installed for the web service that is already in live mode and the previous version was enabled—check that the plug-in has not been automatically connected to the web service as a result of the activation\(in order to ensure the plug-in is not available to customers before the parameters setup\).

    For this,proceed as follows:

    1.  Go to the **Payments** tab in the **Settings** subsection of the **WooCommerce** section.
    2.  Find thepayment methods for working with Ecommpay in the **Method** column and ensure that the **Enable** toggle switch is offfor all the methods \(and switch it off if needed\).

**Note:** If an earlier plug-in version has been used, it can also be updated through the list of installed plug-ins in the WordPress interface \(in the **Installed Plugins** subsection of the **Plugins** section\).

### Installation via the plug-ins upload function {#section_zfz_qg3_bxb .section}

To install the plug-in using the upload function, go to the WordPress interface and proceed as follows:

1.  Select the **Plugins** section in the navigation menuand the **Add New Plugin** itemin the menu that appears.
2.  Click the **Upload Plugin** buttonon the page that opens.

    ![](images/universal/cms/wordpressplugin/cms_wordpress_installation.png "The CMS WordPress page used for installing plug-ins via the upload function")

3.  Select the previously downloaded zip file of the plug-in.
4.  Click the **Install Now** button and wait for the installation completion.
5.  Click the **Activate Plugin** button for activation\(if the plug-in has not been installed in the web service\)or the **Replace current with uploaded** button for the version update \(if the plug-in has already been installed\).

    **Note:** After an attempt to update the plug-in, you may see a notification in the WordPress interface stating that the plug-in cannot be updated and find its both versions—the previous and new one—on the list of installed plug-ins. This can happen when the names of zip files with the previous and the new version are different. When this is the case, deactivate and delete the previous version and active the new one for the plug-in to operate correctly.

6.  If the plug-in is being installed for the web service that is already in live mode and the previous version was enabled—check that the plug-in has not been automatically connected to the web service as a result of the activation\(in order to ensure the plug-in is not available to customers before the parameters setup\).

    For this,proceed as follows:

    1.  Go to the **Payments** tab in the **Settings** subsection of the **WooCommerce** section.
    2.  Findpayment methods for working with Ecommpay in the **Method** column and ensure that the **Enable** toggle switch is offfor all the methods \(and switch it off if needed\).
7.  If a notification about the needed parameters update is displayed in the WordPress interface—click the **Run the updater** button and wait for the update completion.

## Testing {#en_cms_wordpress_testing}

### Overview {#en_cms_wordpress_testing_overview}

Testing the Ecommpay Payments plug-in operation and various payment scenarios without actual debiting of funds is possible via the test environment of the Ecommpay payment platform.You can connect to the platform by using the corresponding form [on the company's main site](https://ecommpay.com/apply-now/) and the identifier and key of the test project received from Ecommpay. Along with that, it is necessary to provide the Ecommpay technical support specialists with the name of the web service, for which the plug-in from Ecommpay should be used, the web service URL, and the payment currency.

Keep in mind that, when using the test environment of the Ecommpay payment platform, the plug-in is connected to the web service and becomes available to customers as the payment option. Thus, in cases when the plug-in is connected to a web service that operates in live mode, it is recommended to ensure that testing takes place during a low-load period and notify the customers about the ongoing testing activities.

### Parameters setup {#en_cms_wordpress_testing_setup}

To prepare the plug-in for testing, proceed as follows:

1.  Open the plug-in tab in the WordPress interface.

    For this, proceed as follows:

    1.  Go to the **Payments** tab in the **Settings** subsection of the **WooCommerce** section.
    2.  Find one of the payment methods set up for working with Ecommpay in the **Method** column and click the **General settings** button in the corresponding line.
2.  Set up the basic parameters of the plug-in operation on the **General** tab:

    -   **Project ID**—the test project identifier.
    -   **Secret Key**—the test project key for interacting with the platform.
    -   **Purchase type**— option for processing payments:
        -   **Sale \(one-step purchase\)**—for one-step purchases \(with immediate withdrawal of funds\)
        -   **Auth \(two-step purchase\)**—for two-step purchases \(with withdrawal after authorisation hold\)
    -   **Automatic cancellation of payments**—automatic releases of funds as part of two-step purchases when the corresponding orders are cancelled.

        To set up this capability, select the **Enable** checkbox. In this case, when an order is assigned the **Cancelled** status, the two-step purchase in this order is cancelled automatically.

    -   **Language**—the language in which the payment form is displayed.
    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_general.png "The General tab with basic parameters for setup")

3.  If necessary, specify additional plug-in parameters.

    For this, click the **Advanced settings** link on the **General** tab and set up the parameters in the sections **Transaction Cache** and **Shop Admin Setup**:

    -   **Enable Caching**—the feature for caching payment datato optimise the plug-in operation in the web service.
    -   **Cache Expiration**—the duration of cached data storage in seconds.
    -   **Log Level**—the level of logging the plug-in operation.

        The information about created logs is provided on the **Logs** tab in the **Status** subsection of the **WooCommerce** section.

    -   **Fetch Payment Info**—the feature for displaying payment statuses in the **Orders** section.

        For the payment statuses to be displayed in the **Orders** section, select the **Enable** checkbox, otherwise, clear the checkbox. By default, the checkbox is selected.

    -   **Complete order automatically**—the feature for completing orders automatically when payments are processed.

        For orders to be completed automatically when payments get the **Success** status, select the **Enable** checkbox, otherwise, clear the checkbox. By default, the checkbox is not selected.

    -   **Payment page version**—Payment Page generation to be used by the plug-in.

        **Note:** Use of this parameter should be brought up with Ecommpay technical support specialists.It is typically used when opening Payment Page in an iframe \([details](en_CMS__wordpress.md#section_arb_hfz_djc)\). To do this, specify the value `v5`; otherwise, leave it at `v4`.

    ![](images/universal/cms/wordpressplugin/cms_wordpress_advanced.jpg "The General tab with additional parameters for setup")

4.  Save the basic plug-in parameters.

    For this, click the **Save changes** button.

5.  If necessary, enable the capability of immediate withdrawal of funds within orders with particular types of products.

    Usage of this capability can be relevant in case of working with two-step purchases and is carried out via one-step purchases.

    To set up the capability of immediate withdrawal of funds, open the **Products** tab in the plug-in operation parameters and select the checkboxes **Enable automatic confirmation of payments** for the following parameters:

    -   **Virtual products**—for orders with virtual products
    -   **Downloadable products**—for orders with downloadable products
    Along with that, the following should be considered:

    -   If the checkbox is selected only for one of the parameters, immediate withdrawal of funds is applied only if the order contains products of the corresponding type \(virtual or downloadable\). If the order contains products of different types or at least one tangible product, authorisation hold, as part of a two-step purchase, is performed \(without the payment being completed at once\).
    -   If both checkboxes are selected, immediate withdrawal of funds is applied if the order contains products of one of the types or both types \(virtual and downloadable\). However, if the order contains products of different types or at least one tangible product, authorisation hold, as part of a two-step purchase, is performed \(without the payment being completed at once\).
    Information about working with the virtual and downloadable product types is provided [in the WooCommerce documentation](https://woocommerce.com/document/managing-products/virtual-downloadable/).

6.  Save the changes.

    For this click the **Save changes** button.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_products.png "Products tab with parameters for enabling immediate withdrawal of funds")

7.  If the [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/) extension is used, in case of necessity, enable the capability of immediate withdrawal of funds when registering purchases within orders with particular product types.

    Usage of this capability can be relevant in case of working with two-step purchases and is carried out via one-step purchases.

    To set up the capability of immediate withdrawal of funds, open the **Subscriptions** tab in the plug-in operation parameters and select the checkboxes **Enable automatic confirmation of payments** for the following parameters:

    -   **Virtual subscriptions**—for orders with virtual products
    -   **Downloadable subscriptions**—for orders with downloadable products
    -   **Other subscriptions**—for orders with products of any type, except for virtual and downloadable
    Along with that, the following should be considered:

    -   If the checkbox is selected only for one of the parameters, immediate withdrawal of funds is applied only if the order contains products of the corresponding type \(virtual or downloadable\). If the order contains products of different types or types for which the checkbox has not been selected, authorisation hold, as part of a two-step purchase, is performed for registering the subscription.
    -   If several checkboxes are selected, immediate debiting of funds is applied if the order contains products of one of the types or all types for which the checkbox is selected.
8.  Save the changes.

    For this click the **Save changes** button.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_subscriptions.png "Subscriptions tab with parameters for enabling immediate withdrawal of funds")

9.  Set up the parameters for using payment methods \([details](en_CMS__wordpress.md)\).

### Processing test purchases {#en_cms_wordpress_testing_purchase}

#### Overview {#section_gcq_bfj_12c .section}

When testing the plug-in operation, you can process test purchases in the web service and obtain information about them via the WordPress interfacein the **Orders** section. Along with that, you can use special payment credentials that allow testing particular payment scenarios.

To test card payments, you can use the numbers of test cards. For testing according to the shortest scenarios\(without the emulation of the 3‑D Secure authentication\), the following numbers of cards can be used:

-   `4000 0000 0000 0077`—for a purchase to be processed
-   `4111 1111 1111 1111`—for a purchase to be declined

For more comprehensive testing, it is possible to use extended test data for card payments\(including scenarios with the 3‑D Secure authentication\) provided in the [Test cards](en_test_cards.md) article.

To test payments using alternative payment methods\(with these methods set up through an account manager or the technical support specialists in the test environment of payment platform\), you can use the information provided in the [Testing](en_pm_testing.md) article and in the sections about testing particular payment methods.

#### Ensuring data synchronisation {#section_cmk_kfj_12c .section}

When working with two-step purchases, the second steps can be initiated both via the WordPress interface and via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\). In case of the Ecommpay interfaces, the order information in the WordPress interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the WordPress interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the WordPress interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS WordPress \(to the URL in the format `https://<site domain>/?wc-api=WC_Ecommpay` provided also in the plug-in operation parameters\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_u33_5fj_12c .section}

A one-step purchase, as well as the first step of a two-step purchase\(authorisation hold\), is initiated by the customer when they confirm the payment. A one-step purchase is processed automatically, while for a two-step purchase, only the first step, authorisation hold, is initiated automatically and after that the second step, withdrawal or release of funds, can be made. The second step can also be initiated automatically \(after a specified authorisation period\) or upon the merchant's request—via the WordPress interface or the interfaces of the Ecommpay payment platform: Dashboard\([details](en_dbl_payments.md)\) and the Gate API\([details](en_gate_payment_auth.md)\). Along with that, withdrawals upon requests can be made not only for the entire authorised amount but also for a part of this amount.

To initiate the second step of a purchase via the WordPress interface, proceed as follows:

1.  Go to the orders register.

    For this, open the **WooCommerce** section and select the **Orders** item in the menu that appears.

2.  Select an order within which the second step of the purchase should be initiated.
3.  If only a partial amount of payment should be withdrawn, change the order amount using the ![](images/ecommpay/cms/wordpressplugin/edit_item.png) button in the line of the corresponding order in the order information tab.
4.  Initiate the second step of the purchase.

    To withdraw the held funds, click the **Capture** button, with the amount to be withdrawn, and confirm the action in the dialog box that appears. For releasing the funds, click the **Cancel payment** button and confirm the action in the dialog box that appears.


For setting up automatic initiation of the second step of two-step purchases, contact the Ecommpay technical support specialists.

**Note:** According to the requirements of the global card networks, the time allocated for holding the funds is limited on the Ecommpay platform side \([details](en_pp_purchase_auth.md#section_hgy_djl_ylb)\).If this time expires and the funds are not withdrawn or released, the payment is automatically declined in the payment platform.

### Processing test refunds {#en_cms_wordpress_testing_refund}

#### Overview {#dshkdsddsd1433cdcdc .section}

After processing test purchases, you can make test refundsvia the WordPress interface and, if relevant, via [the Gate API](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the WordPress interface have the statuses `Processing` or `Completed` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all information provided in this subsection is as well relevant for issuing refunds in the production environment.

#### Ensuring data synchronisation {#section_acb_dyj_vcc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), payment and order information in the WordPress interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment and order information via the WordPress interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the WordPress interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the WordPress CMS are configured \(these callbacks should be sent to the URL specified in the **Merchant callback URL** field of the plug-in parameters in the format `https://<site domain>/?wc-api=WC_Ecommpay`\).

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

**Warning:** Keep in mind that, in case of refunds made via the interfaces of the Ecommpay platform, the WordPress CMS does not contain the information on what products \(or services\) within a particular order have been refunded.

#### Procedures {#section_abl_21k_vcc .section}

To make a refund via the WordPress interface, proceed as follows:

1.  Open the orders register.

    For this, open the **WooCommerce** section and select the **Orders** item in the menu that appears.

2.  Select the order that should be refunded and click the **Refund** buttonin the order tab that opens.
3.  Specify the number of the items that should be returned \(in this case, the refund amount is calculated automatically\) or specify the refund amount without changing the number of items in the order.
4.  If necessary, specify the reason for the refund in the **Reason for refund** field.
5.  Confirm the refund.

    For this, click the **Refund via** **Ecommpay** button.

6.  Ensure that the order amount has changed by the refund amount and the right sidebar **Order notes** displays the notification about the performed operation.

    In case of a partial refund, the order is assigned one of the statuses: `Processing` or `Completed`, while in case of a full refund, the order is assigned the status `Refunded`.


![](images/ecommpay/cms/wordpressplugin/cms_wordpress_refund.png "The order tab in the WordPress interface")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

## Usage {#en_cms_wordpress_usage}

### Overview {#en_cms_wordpress_usage_overview}

In order to process payments with actual debiting of funds, you should initially solve all organisational issues related to the interaction with Ecommpay\(submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from Ecommpay about the possibility to process payments, as well as the identifier and secret key of the production project\). Along with that, it is necessary to provide the Ecommpay technical support specialists with the name and URL of the web service for which the Ecommpay Payments plug-in is set up and the currency in which payments are to be processed.

After that, you specify the identifier and secret key of the production project received from Ecommpay in the parameters of the plug-in operation and set up other necessary parameters\(or check whether the current setup is relevant for working in real-life conditions\). If later you need to suspend the plug-in operation, the plug-in methods can be disabled. Besides, if additional testing is needed, for example when setting up new features, the plug-in can be switched to using the test environment.

### Setup of the parameters for one-time purchases {#en_cms_wordpress_usage_setup}

To set up the plug-in for processing one-time purchases, proceed as follows:

1.  Open the plug-in tab in the WordPress interface.

    For this, proceed as follows:

    1.  Go to the **Payments** tab in the **Settings** subsection of the **WooCommerce** section.
    2.  Find one of the payment methods set up for working with Ecommpay in the **Method** column and click the **General settings** button in the corresponding line.
2.  Set up the basic parameters of the plug-in operation on the **General** tab:

    -   **Demo mode**—the feature for switching the plug-in operation mode.

        For using the production environment of the platform, clear the **Enable Demo mode** checkbox and specify the parameters for connecting to the platform received from Ecommpay in the fields **Project ID** and **Secret Key**.

    -   **Project ID**—the production project identifier.
    -   **Secret Key**—the production project key for interacting with the platform.
    -   **Purchase type**— option for processing payments:
        -   **Sale \(one-step purchase\)**—for one-step purchases \(with immediate withdrawal of funds\)
        -   **Auth \(two-step purchase\)**—for two-step purchases \(with withdrawal after authorisation hold\)
    -   **Automatic cancellation of payments**—automatic releases of funds as part of two-step purchases when the corresponding orders are cancelled.

        To set up this capability, select the **Enable** checkbox. In this case, when an order is assigned the **Cancelled** status, the two-step purchase in this order is cancelled automatically.

    -   **Language**—the language in which the payment form is displayed.
    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_general.png "The General tab with basic parameters for setup")

3.  If necessary, specify additional plug-in parameters.

    For this, click the **Advanced settings** link on the **General** tab and set up the parameters in the sections **Transaction Cache** and **Shop Admin Setup**:

    -   **Enable Caching**—the feature for caching payment datato optimise the plug-in operation in the web service.
    -   **Cache Expiration**—the duration of cached data storage in seconds.
    -   **Log Level**—the level of logging the plug-in operation.

        The information about created logs is provided on the **Logs** tab in the **Status** subsection of the **WooCommerce** section.

    -   **Fetch Payment Info**—the feature for displaying payment statuses in the **Orders** section.

        For the payment statuses to be displayed in the **Orders** section, select the **Enable** checkbox, otherwise, clear the checkbox. By default, the checkbox is selected.

    -   **Complete order automatically**—the feature for completing orders automatically when payments are processed.

        For orders to be completed automatically when payments get the **Success** status, select the **Enable** checkbox, otherwise, clear the checkbox. By default, the checkbox is not selected.

    -   **Payment page version**—Payment Page generation to be used by the plug-in.

        **Note:** Use of this parameter should be brought up with Ecommpay technical support specialists.It is typically used when opening Payment Page in an iframe \([details](en_CMS__wordpress.md#section_arb_hfz_djc)\). To do this, specify the value `v5`; otherwise, leave it at `v4`.

    ![](images/universal/cms/wordpressplugin/cms_wordpress_advanced.png "The General tab with additional parameters for setup")

4.  Save the basic plug-in parameters.

    For this, click the **Save changes** button.

5.  If necessary, enable the capability of immediate withdrawal of funds within orders with particular types of products.

    Usage of this capability can be relevant in case of working with two-step purchases and is carried out via one-step purchases.

    To set up the capability of immediate withdrawal of funds, open the **Products** tab in the plug-in operation parameters and select the checkboxes **Enable automatic confirmation of payments** for the following parameters:

    -   **Virtual products**—for orders with virtual products
    -   **Downloadable products**—for orders with downloadable products
    Along with that, the following should be considered:

    -   If the checkbox is selected only for one of the parameters, immediate withdrawal of funds is applied only if the order contains products of the corresponding type \(virtual or downloadable\). If the order contains products of different types or at least one tangible product, authorisation hold, as part of a two-step purchase, is performed \(without the payment being completed at once\).
    -   If both checkboxes are selected, immediate withdrawal of funds is applied if the order contains products of one of the types or both types \(virtual and downloadable\). However, if the order contains products of different types or at least one tangible product, authorisation hold, as part of a two-step purchase, is performed \(without the payment being completed at once\).
    Information about working with the virtual and downloadable product types is provided [in the WooCommerce documentation](https://woocommerce.com/document/managing-products/virtual-downloadable/).

6.  Save the changes.

    For this click the **Save changes** button.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_products.png "Products tab with parameters for enabling immediate withdrawal of funds")

7.  Set up the parameters for using payment methods \([details](en_CMS__wordpress.md)\).

### Setup of parameters for COF purchases {#en_cms_wordpress_usage_setup_recurring}

In order to set up registering and processing of COF purchases \(*subscriptions*\) with the use of the Ecommpay Payments plug-in and the [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/) extension, you should set up the parameters of the Ecommpay Payments plug-in \(according to the setup instructions for one-time purchases\) and use the tools available in the WooCommerce plug-in tab of the **Subscriptions** tab.On the **Subscriptions** tab, it is possible to set up different parameters, including the following ones: the names of the buttons, which are used for adding the products to the cart and paying for them, options of COF purchases renewal after their suspension, and other parameters. Information about working with COF purchases via the WooCommerce Subscriptions extension is provided [in the WooCommerce documentation](https://woocommerce.com/document/subscriptions/store-manager-guide/#section-25).

![](images/universal/cms/wordpressplugin/cms_wordpress_subscriptions_setup.png "The Subscriptions tab with parameters for COF purchases setup")

Along with that, when working with the Ecommpay Payments plug-in, you can enable the capability of immediate withdrawal of funds when registering purchases within orders with particular product types.It can be relevant when the two-step purchases option is selected in the plug-in parameters and you do not need to initiate withdrawal of funds manually. In this case, COF purchases are registered via the processing of one-step purchases.

To set up the capability of immediate debiting of funds when registering subscription purchases, open the **Subscriptions** tab in the plug-in operation parameters and select the checkboxes **Enable automatic confirmation of payments** in the following parameters:

-   **Virtual subscriptions**—for orders with virtual products
-   **Downloadable subscriptions**—for orders with downloadable products
-   **Other subscriptions**—for orders with products of any type, except for virtual and downloadable

Along with that, the following should be considered:

-   If the checkbox is selected only for one of the parameters, immediate withdrawal of funds is applied only if the order contains products of the corresponding type \(virtual or downloadable\). If the order contains products of different types or types for which the checkbox has not been selected, authorisation hold, as part of a two-step purchase, is performed for registering the subscription.
-   If several checkboxes are selected, immediate debiting of funds is applied if the order contains products of one of the types or all types for which the checkbox is selected.

![](images/ecommpay/cms/wordpressplugin/cms_wordpress_subscriptions.png "Subscriptions tab with parameters for enabling immediate withdrawal of funds")

### Processing purchases {#en_cms_wordpress_usage_purchase}

#### Overview {#section_hqf_pfn_12c .section}

If the web service and the plug-in have been set up correctly, the processing of one-step purchases and authorisation hold on funds for two-step purchases are performed automatically.Along with that, it is important to ensure that all necessary data is collected on the web service side.

**Note:** The data set mandatory for processing card payments with the 3‑D Secure authentication has been expanded. To submit these data, use the fields for collecting the customer's phone number or email on the checkout page.

In case of questions or issues related to purchase processing, contact the Ecommpay technical support specialists.

#### Ensuring data synchronisation {#section_vpq_5fn_12c .section}

When working with two-step purchases, the second steps can be initiated both via the WordPress interface and via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\). In case of the Ecommpay interfaces, the order information in the WordPress interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment information via the WordPress interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the WordPress interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the CMS WordPress \(to the URL in the format `https://<site domain>/?wc-api=WC_Ecommpay` provided also in the plug-in operation parameters\) are configured.

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

    Otherwise, the plug-in logs display error messages related to processing of callbacks received from the payment platform.


#### Procedures {#section_e2q_wfn_12c .section}

A one-step purchase, as well as the first step of a two-step purchase\(authorisation hold\), is initiated by the customer when they confirm the payment. A one-step purchase is processed automatically, while for a two-step purchase, only the first step, authorisation hold, is initiated automatically and after that the second step, withdrawal or release of funds, can be made. The second step can also be initiated automatically \(after a specified authorisation period\) or upon the merchant's request—via the WordPress interface or the interfaces of the Ecommpay payment platform: Dashboard\([details](en_dbl_payments.md)\) and the Gate API\([details](en_gate_payment_auth.md)\). Along with that, withdrawals upon requests can be made not only for the entire authorised amount but also for a part of this amount.

To initiate the second step of a purchase via the WordPress interface, proceed as follows:

1.  Go to the orders register.

    For this, open the **WooCommerce** section and select the **Orders** item in the menu that appears.

2.  Select an order within which the second step of the purchase should be initiated.
3.  If only a partial amount of payment should be withdrawn, change the order amount using the ![](images/ecommpay/cms/wordpressplugin/edit_item.png) button in the line of the corresponding order in the order information tab.
4.  Initiate the second step of the purchase.

    To withdraw the held funds, click the **Capture** button, with the amount to be withdrawn, and confirm the action in the dialog box that appears. For releasing the funds, click the **Cancel payment** button and confirm the action in the dialog box that appears.


For setting up automatic initiation of the second step of two-step purchases, contact the Ecommpay technical support specialists.

**Note:** According to the requirements of the global card networks, the time allocated for holding the funds is limited on the Ecommpay platform side \([details](en_pp_purchase_auth.md#section_hgy_djl_ylb)\).If this time expires and the funds are not withdrawn or released, the payment is automatically declined in the payment platform.

### Issuing refunds {#en_cms_wordpress_usage_refund}

#### Overview {#section_tnq_m2k_vcc .section}

After processing test purchases, you can make refundsvia the WordPress interface and, if relevant, via [the Gate API](en_Gate_Refund.md) and [Dashboard](en_dbl_payments.md) from Ecommpay. Along with that, keep in mind that refunds can be made in case if orders in the WordPress interface have the statuses `Processing` or `Completed` and if payments in the Ecommpay payment platform have the statuses `success`, `partially reversed`, or `partially refunded`. Also, you can take into consideration that all capabilities and procedures of working with refunds in the production environment correspond to those available in the test environment.

#### Ensuring data synchronisation {#section_bv4_s2k_vcc .section}

When refunds are initiated via the interfaces of the Ecommpay payment platform \(Dashboard and the Gate API\), payment and order information in the WordPress interface is updated only if conditions that trigger callbacks from the payment platform have been configured. Thus, if the merchant needs to issue refunds via the Ecommpay platform interfaces and monitor the payment and order information via the WordPress interface, it is important to ensure that callbacks can be sent and received for automatic updates of information in the WordPress interface. For this, the following conditions must be met:

-   For the project in use, conditions that trigger callbacks sent from the payment platform to the WordPress CMS are configured \(these callbacks should be sent to the URL specified in the **Merchant callback URL** field of the plug-in parameters in the format `https://<site domain>/?wc-api=WC_Ecommpay`\).

    Information about working with conditions for sending callbacks is provided [in a separate article](en_dbl_projects.md).

-   The configured conditions for sending callbacks do not have duplicates with the same payment type, event type, and payment method code.

**Warning:** Keep in mind that, in case of refunds made via the interfaces of the Ecommpay platform, the WordPress CMS does not contain the information on what products \(or services\) within a particular order have been refunded.

#### Procedures {#section_mgd_t2k_vcc .section}

To make a refund via the WordPress interface, proceed as follows:

1.  Open the orders register.

    For this, open the **WooCommerce** section and select the **Orders** item in the menu that appears.

2.  Select the order that should be refunded and click the **Refund** buttonin the order tab that opens.
3.  Specify the number of the items that should be returned \(in this case, the refund amount is calculated automatically\) or specify the refund amount without changing the number of items in the order.
4.  If necessary, specify the reason for the refund in the **Reason for refund** field.
5.  Confirm the refund.

    For this, click the **Refund via** **Ecommpay** button.

6.  Ensure that the order amount has changed by the refund amount and the right sidebar **Order notes** displays the notification about the performed operation.

    In case of a partial refund, the order is assigned one of the statuses: `Processing` or `Completed`, while in case of a full refund, the order is assigned the status `Refunded`.


![](images/ecommpay/cms/wordpressplugin/cms_wordpress_refund.png "The order tab in the WordPress interface")

To make a refund via the Gate API or Dashboard of the Ecommpay platform, use the procedures provided in the corresponding articles: [Purchase refunds](en_Gate_Refund.md)\(for the Gate API\) and [Issuing refunds](en_dbl_payments.md)\(for the Dashboard interface\).

### Monitoring payments and orders {#en_cms_wordpress_usage_monitoring}

The information about payments \(including series of debits as part of COF purchases\) processed with the use of the Ecommpay Payments plug-in and about the corresponding orders can be monitored via the WordPress interfacevia the tools of the **Orders** subsection in the **WooCommerce** section.

Additionally, the payment information can be obtained via the Dashboard interface from Ecommpay \([details](en_dbl_payments.md)\). This interface provides the information about payments and refunds processed via the Ecommpay payment platform, but it does not display information about orders.

The **Orders** subsection contains an orders register with main details about every orderand with the capabilities of searching and filtering data, as well as opening the tabs of separate orders and performing various actions related to the orders. \(Alongside order statuses, the register can also contain payment statuses—if the **Fetch Payment Info** checkbox in the plug-in parameters is selected.\)

![](images/universal/cms/wordpressplugin/cms_wordpress_orders.png "The Orders register in the WordPress interface")

To open a tab of a particular order, click on the order's entry in the register. The tabs contain the details about orders and payments, such as the order creation date, the purchase amount, the payment option and status, delivery address, and other data. The tabs also contain the specialised panels:

-   **Ecommpay** **Payment**—with the payment information and the capability to update this information manually using the **Refresh** button.
-   **Order actions**—with tools for performing various actions on the order.
-   **Order notes**—with notifications about various events related to the order and the payment.

![](images/ecommpay/cms/wordpressplugin/cms_wordpress_order_tab.png "The order tab in the WordPress interface")

More detailed information about working with orders in the WordPress interface is provided [in the WooCommerce documentation](https://woocommerce.com/document/managing-orders/?quid=0126ec88eba314cb70e4e8a8db82482e#viewing-and-managing-multiple-orders).

### Monitoring COF purchases {#en_cms_wordpress_usage_recurring}

With the WooCommerce Subscriptions extension, you have the access to the **Subscriptions** subsection in the **WooCommerce** section. This subsection contains the information about COF purchases \(in addition to the information displayed in the **Orders** subsection\).Similarly to the **Orders** subsection, the **Subscriptions** subsection displays the subscriptions register with main details about every subscription and provides the capabilities of searching and filtering data as well as opening the tabs of separate subscriptions and performing various actions related to the subscriptions.

![](images/universal/cms/wordpressplugin/cms_wordpress_subscriptions.png "The Subscriptions register in the WordPress interface")

More detailed information about working with COF purchases in the WordPress interface is provided [in the WooCommerce documentation](https://woocommerce.com/document/subscriptions/store-manager-guide/#section-14).

## Parameters for using payment methods {#en_cms_wordpress_methods}

When working with the Ecommpay Payments plug-in, in the WordPress interface, you can set up the usage of various payment methods available in the merchant's project. You can do this on separate tabsin the plug-in tab—such as **Card settings** \(with parameters for card payments\), **Pay by Bank** \(with parameters for using the payment methods of the European Open banking group\), or **More methods** \(with parameters for using all methods set up in the project\).

**Note:** The tabs displayed by default cannot be removed from the plug-in tab even if the corresponding methods are not used in the project.If other methods \(except the ones with separate tabs\) are needed, their usage can be set up only on the **More methods** tab once the Ecommpay technical support specialists enable these methods in the project upon the merchant's request.

The tabs for payment methods setup contain the following parameters:

-   General parameters:
    -   **Enable/Disable**—the feature for enabling a payment method to work via the plug-in.
    -   **Title**—the payment method namedisplayed on the checkout page of the WooCommerce interface.
    -   **Show Description**—the feature for displaying the text from the **Description** parameter.
    -   **Description**—the text displayed to the customers when they select a certain payment method.
    -   **Order button text**—the name of the button used for proceeding to payment\(for example, ‘Pay for order’\).
-   Parameters used only in the **Card settings** tab:

    -   **Display mode**—the option for opening the payment form.

        One of the following options can be selected:

        -   `Redirect`—opening as a separate HTML page \(used by default\).
        -   `Popup`—opening in a modal window.
        -   `Embedded`—opening in an iframe element.

            This option is available if approved by Ecommpay technical support. To use it,open the **WooCommerce** section, navigate to the **Payments** tab in the **Settings** subsection, click the **Advanced settings** link, and set the **Payment page version** parameter to `v5` \([details](en_CMS__wordpress.md)\).

    -   **Close on misclick**—the capability to close the payment form displayed in the modal window with a mouse click outside of this window.

        After the window closes, the customer can open the payment form again, but in this case, they need to re-enter the data they previously specified in the form. If this option is not enabled, the modal window can be closed only with the close button or after the purchase is processed.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_card_settings.png "The Card settings tab with parameters for card payments")

-   The parameter used only in the **More methods** tab:

    -   **Payment method code**—the code of a payment method used as the only additional one \(in relation to the methods which are set up via separate tabs\).

        -   Without this parameter used, when the customer selects a purchase method in the web service interface, they can select the **More payment methods** option \(the exact wording of the option name can be specified in the **Title** field of the **More methods** tab\), proceed to the payment form, and select one of the methods available for the payment being initiated in the Ecommpay platform.Along with that, all methods from Ecommpay that can be selected directly in the web service \(together with the **More payment methods** option\) become available in the payment form.
        -   With this parameter containing the code of one of the available methods\(taken [from the reference](en_pm_codes.md)\), when the customer selects a purchase method in the web service interface, among other available methods, they can select the one specified via the code and proceed to paying via this method without selecting any other methods in the payment form.To prevent issues that may be triggered by such a selection, alongside the payment method code, the name of the method should also be specified in this section \(in the **Title** field\).
        **Note:** Since in the plug-in test mode, it is possible to process only card purchases, the work of the **More methods** accordion item in this mode can be tested only for the `card` method.

    ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_more_methods.png "The More methods tab with parameters for using all payment methods")




---

# Using Payment Page in embedded mode for card payments {#en_pp_microframe_solution}

An article about using Payment Page embedded mode edition to accept standard card payments.

## Overview {#section_bym_5hy_k3c .section}

In certain processing scenarios merchants may need to use a minimalist payment form embedded into the user interface of their web servicewhich allows their customers to have a faster and optimised checkout experience as compared to standard solutions, at least in case of the most frequently used payments. When working with the Ecommpay payment platform, you can use a specialised *embedded mode edition* of Payment Pagewith the least number of input fields and without the payment confirmation button \(the expectation being that the button or any other element is to be developed on the merchant web service side\).

![](images/ecommpay/en_pp_microframe_solution_1.svg "Interface of the payment form in embedded mode. Essential fields")

The *embedded mode edition* is intended for processing standard card payments with support of the most relevant procedures and capabilities. To work with augmented processing scenarios as well as to accept alternative payments, you can use other editions of Payment Page. You can implement and use several editions of the payment form at the same time and customise them to fit the needs of your web service.For example, you can use Payment Page in embedded mode to process card payments and implement a specialised edition with embedded buttons for Apple Pay and Google Pay payments \([details](en_pp_embedded_payment_buttons.md)\), while relying on the standard edition of Payment Page for accepting payments with other payment methods.

![](images/ecommpay/microframe_1.svg "Combining several editions of the payment form to accept different payment methods")

## Capabilities {#section_oq2_2rf_l3c .section}

When working with Payment Page in embedded mode, you can:

-   Customise the appearance of the payment form using the **Payment Page Designer**in Dashboard \([details](en_PP__design_customisation.md)\).
-   Customise the fields to be displayed on the payment form. You can remove the field to enter the cardholder's name \(if this option is enabled for the project\)and add fields to collect additional customer data\([details](en_PP_Gathering_customer_data.md)\).
-   Enable your customers to save card details, subsequently use them to pay, or remove them\(this option is available by default, but it can be disabled upon agreement with the Ecommpay account manager\).
-   Accept one-timeone-step and two-step card purchases and perform card verification, with the option to register COF purchases available in both cases and the capability to execute relevant auxiliary proceduressuch as 3‑D Secure authentication, AVS checks, and submitting additional payment information.

## Processing scenario {#section_vhx_ctf_l3c .section}

The basic steps of the customer payment scenario with the use of Payment Page in embedded mode are the following:

![](images/ecommpay/en_pp_microframe_solution_scenario_1.svg "Opening the payment form")

![](images/ecommpay/en_pp_microframe_solution_scenario_2.svg "Entering card details")

![](images/ecommpay/en_pp_microframe_solution_scenario_3.svg "Web service preloader")

![](images/ecommpay/en_pp_microframe_solution_scenario_4.svg "3‑D Secure authentication")

![](images/ecommpay/en_pp_microframe_solution_scenario_5.svg "Redirecting to the web service")

1.  The customer initiates the purchase in the web service following which the customer can provide the details of the card.

    At this step, the payment form can contain the card selection tabs \(if this customer saved any cards before\) and fields to enter the card details to be used for payment as well as additional fields and the checkbox to consent to saving the card details \(if this option is set up for the project\).

2.  The customer provides necessary data and confirms the payment.

    If the data is missing or entered incorrectly, the customer is shown notifications about it in the payment form.

3.  The customer is shown the preloader.

    This can be done either in the interface of the payment form or in the interface of the web service, depending on the web service configuration. Note that the payment form remains open throughout.

4.  If it is necessary for payment processing, the customer is shown the forms for performing additional actions which the customer then executes.

    These additional forms include the modal window with the fields to enter additional data shown in the web service \(over the payment form\) and the page to perform the 3‑D Secure authentication, shown in the iframe element of the payment form instead of the payment form.

5.  The customer is shown the payment result information.

    This involves the use of the payment form, and if it is configured in the web service, then the web service as well.


## Workflow {#section_vqs_wyf_l3c .section}

Processing a purchase made via Payment Page in embedded mode requires the interaction between the web service and the payment form with the use of the specialised libraries from Ecommpay. In a standard case, when the web service displays its own preloader page \(over the interface of the payment form\), the interaction is carried out as follows.

**Note:** There is no need to redirect the customer to a separate preloader page or repeatedly check the payment status from your backend — Payment Page checks the status directly and sends the corresponding callback once a final payment result is received.

![](images/ecommpay/en_pp_microframe_solution_uml.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service invokes Payment Page with the use of the `EPayWidget.runEmbedded` method.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  The customer is shown Payment Page embedded in the page of the web service.
7.  The customer enters required data and confirms payment the way it is configured in the web service.
8.  The web service calls the `trySubmit` method of the `EPayWidget` object for initial validation of entered data.
9.  The data provided by the customer is validated on the side of Payment Page.
10. Using the `onCheckSubmit` function, Payment Page sends to the web service the confirmation that payment processing can be initiated and that the payment needs confirmation by the customer.
11. The web service calls the `resolve` method of the `onCheckSubmit` function following which information about payment confirmation is sent to Payment Page.
12. The web service invokes the `onShowLoader` function to display the preloader to the customer.
13. The web service preloader page is displayed to the customer.
14. The request for processing a payment is sent to the payment platform.
15. The payment platform processes the request and sends it to the payment environment.
16. The purchase is processed in the payment environment.
17. The payment environment sends a notification about the result to the payment platform.
18. The payment platform sends the result information to Payment Page.
19. The web service invokes the `onHideLoader` function to hide the preloader and show the payment form to the customer.
20. The result information is displayed to the customer on Payment Page.

## Setup and testing {#section_zxq_q2g_l3c .section}

To start working with Payment Page in embedded mode:

1.  If you have not yet finalised organisational steps that need to be taken towards integration with Ecommpay, take necessary actionby signing up and providing required information \([details](en_pp_interaction_organisation.md)\).
2.  If you have not yet carried out the work for integrating Payment Page with the use of specialised libraries, do so by taking the following steps:
    1.  On the client side, add the Ecommpay CSS and JavaScript librariesavailable at `https://paymentpage.ecommpay.com/shared/merchant.css` and `https://paymentpage.ecommpay.com/shared/merchant.js`.

        ``` {#codeblock_c31_yrr_c3c .language-xml}
        <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
        <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
        ```

        **Warning:** Note that you must link the Ecommpay CSS and JavaScript libraries via the CDN \(Content Delivery Network\).Storing these libraries locally can lead to critical errors in the payment form's behaviour.

    2.  Configure the Content Security Policy by specifying the source URLs required for correct operation of the payment form in the `Content-Security-Policy` HTTP header \([details](en_pp_interaction_organisation.md#section_jth_vnh_qjc)\).

        ``` {#codeblock_ejr_n4k_mjc}
        Content-Security-Policy:
        script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com;
        style-src https://paymentpage.ecommpay.com;
        img-src https://applepay.cdn-apple.com;
        frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com
        ```

    3.  On the server side, set up collection and signing data passed in the requests for opening Payment Page \(you can automate the following [algorithms](en_platform_signature.md) or use [one of the specialised SDKs](en_sdk_overview.md#section_vcj_5zv_tvb)\) and sending signed data to the client side of the web service.
3.  On the client side, take all necessary steps to ensure the web service can work with the embedded mode of Payment Page:
    1.  Implement the HTML element to display the form.

        ``` {#codeblock_kpz_1sr_c3c .language-xml}
        <div id="widget-container-card-embedded"></div>
        ```

    2.  Implement invoking the payment form using the JavaScript library from Ecommpay and the `EPayWidget.runEmbedded` method \(more below\).
    3.  Implement declaring functions for handling interface events \(more below\).
4.  If necessary, agree upon the fields displayed on the form and enabling the capabilities with your Ecommpay account manager. You can configure the following:
    -   Removing the field for entering the name of the cardholder, on the condition that each request for opening the payment form will contain parameters `customer_first_name` and `customer_last_name` \(subsequently you can populate this field with the data passed in the requests for opening the payment form\). Alternatively, you can avoid collecting cardholder data and accept the risk of possible decrease in payment acceptance rates.
    -   Displaying additional fields for collecting customer data, for example, their emails and phone numbers, \([details](en_PP_Gathering_customer_data.md)\).
    -   Enabling your customers to save card details, subsequently use them to pay, or remove themwhen they use the payment form \(this option is available by default, but it can be disabled\).
5.  If necessary, you can customise the appearance of the payment form using the **Payment Page Designer**in Dashboard \([details](en_PP__design_customisation.md)\).
6.  Once you have set up, you can test payment processing using test card details and test projects \([details](en_test_cards.md)\) and proceed to taking real payments.

If you have any questions about working with the platform using the Payment Page embedded mode, refer to this documentation as well as your account manager and the Ecommpay technical support.

## Using callback functions {#section_cw5_fxp_l3c .section}

Using Payment Page in embedded mode involves using callback functions that are declared by the web service when invoking the form.

To ensure correct payment processing, invoke the `onCheckSubmit` function. In addition, you can use other functions:

-   `onShowLoader`—for displaying the web service preloader
-   `onHideLoader`—for hiding the web service preloader\(if it is necessary to display the payment form pages to the customer\)
-   `onPaymentSubmitResult`—for receiving information about the request identifier
-   `onPaymentFail`— for receiving information about the payment decline
-   `onPaymentSuccess`—for receiving information about the payment completion
-   `onError`—for receiving information about errors on the payment form side

**Note:** Use the `onPaymentFail` and `onPaymentSuccess` functions as the primary mechanism for handling payment results as well as for initiating redirection of a customer to a corresponding page of the web service if the `redirect_success_url` parameter is not used for this purpose \([details](en_pp_microframe_solution.md#section_ick_qhq_l3c)\).

There is no need to redirect the customer to a separate preloader page or repeatedly check the payment status from your backend — Payment Page checks the status directly and sends the corresponding callback once a final payment result is received.

In addition, other relevant functions can be usedto handle interface events \([details](en_pp_ui_monitoring.md)\).

The following is the example of invoking necessary functions on the client side of the web service.

``` {#codeblock_psg_fqr_c3c .language-javascript}
const checkoutButtonsWidget = EPayWidget.runEmbedded({
    ...configObj,
 
    // Declaring the function for showing the web service preloader 
    onShowLoader: merchantPage.showMerchantLoader,

    // Declaring the function for hiding the web service preloader
    onHideLoader: merchantPage.hideMerchantLoader,

    // Declaring the function for receiving information about the payment completion
    // and for subsequent redirection of the customer
    onPaymentSuccess: function (data) {
        merchantPage.redirectToSuccessPage();
    },

    // Declaring the function for receiving information about the payment decline
    // and for displaying the corresponding message to the customer
    onPaymentFail: function (data) {
        merchantPage.showPaymentFailMessage();
    },

    // Declaring the function for validating the payment request
    onCheckSubmit: async function (data, resolve, reject) {
        try {
            // Validating the order
            if (!await merchantPage.validateCheckoutPage()) {
                return reject() // Rejecting due to incorrect order contents
            }
 
            if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) {
                return reject() // Rejecting due to errors with the amount and currency of the payment
            }
 
            // Registering the order on the side of the web service
            const { orderId, additionalParameters } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo);
 
            if (!orderId) {
                return reject() // Rejecting due to errors occurred in the process of registering the order 
            }
         
            // Confirming payment by the web service with additional information  
            return resolve({ additional_parameters: additionalParameters});
 
        } catch (error) {
            console.error('onCheckSubmit error:', error);
            return reject();
        }
    },

    // Declaring the function for receiving information about the request registration in the payment platform
    onPaymentSubmitResult: async function (data) {
        await merchantAPI.saveTransactionId(orderId, data.request_id)
    },

    // Declaring the function for displaying error messages to customers
    onError: async function ({ messages }) {
        await merchantAPI.log("Payment error occurred " + messages)
        if (messages.includes("invalid payment_id")) {
            merchantPage.redirectToContactSupportPage();
        }
    },
}, 'POST');
 
    // Invoking the trySubmit function when the customer confirms the payment (by clicking the button) 
    document.getElementById('placeOrderBtn').addEventListener('click', function() {
        checkoutButtonsWidget.trySubmit();
    });
```

## Use {#section_jzt_pzp_l3c .section}

In general, to process a payment using Payment Page in embedded mode, the following is required on the web service side.

1.  Generate a request to open the payment form. The request must contain the `configObj` JavaScript object with [the parameters for invoking the payment form](en_pp_embedded_payment_buttons.md) and [the signature](en_platform_signature.md) for them. The essential data set required for processing a paymentin this case includes:

    -   `target_element`—identifier of the iframe elementin which the payment form should be opened
    -   `payment_id`—payment identifierunique within the project
    -   `payment_amount`—payment amountin the smallest currency unit
    -   `payment_currency`—payment currency codein the ISO-4217 alpha-3 format
    -   `project_id`—project identifierobtained from Ecommpay during integration
    -   `merchant_domain`—domain name of the web service in which the payment form should be opened
    -   `force_payment_method`—code of the payment methodthat will be shown as preselected, with `card` passed as a value
    -   `mode`—Payment Page operation mode indicator with the value `purchase` for any of the one-time purchases and `card_verify` for card verification
    -   `signature`—request signaturegenerated after all target parameters are specified
    ``` {#codeblock_nhw_3tr_c3c .language-json}
    const configObj = {
        target_element: "widget-container-card-embedded",
        payment_id: "X03937",
        payment_amount: 1960,
        payment_currency: "EUR",
        project_id: 22,
        merchant_domain: "cosmoshop.jupiter.example",
        force_payment_method : "card",
        signature: "0ByxpQ30hfTIjaCCsVIwVyabcDEF123"
    };
    ```

2.  Invoke the payment form using the `EPayWidget.runEmbedded` method, specifying the `configObj` JavaScript object and functions`onCheckSubmit`, `onShowLoader`, and `onHideLoader` \(more below\).
3.  When the customer confirms the intent to pay, for example by clicking the button,invoke the `trySubmit` method of `EPayWidget`. As a result, on the Payment Page side, the initial verification of payment information is performed following which one of the two functions is invoked automatically:

    -   `onCheckSubmit`—if there are no errors, without anything specified in the `data` object
    -   `onValidationError`—if there are errors, with information about these errors specified in the `data` object
    ``` {#codeblock_nsp_4rw_c3c .language-json}
    "{\"message\":\"epframe.embedded_mode.validation_error\",\"data\":{\"pan\":\"Invalid card number.\",\"month_year\":\"Expiry date required.\",\"cvv\":\"CVV2/CVC2 required.\",\"card_holder\":\"Cardholder name required.\"},\"guid\":\"288d-f68c-e53d-3890\"}"
    
    ```

4.  Verify payment information \(such as the payment amount and currency as well as other required data\)and call one of these functions:

    -   `resolve`—to confirm the payment\(if there are no errors\)
    -   `reject`—to decline the payment\(if there are errors\)
    Along with the payment confirmation, at this stage you can pass the customer information\(if it was not passed when the payment form was initialised or if it needs to be changed\) as well as specify URLs for automatic customer redirection once the payment is complete. For this, use the `additional_parameters` object.

    ``` {#codeblock_rv4_xyr_c3c .language-json}
    {
    // General customer information
        customer_id:"customer_112",
        customer_first_name:"Arthur",
        customer_last_name:"McDonald",
        customer_phone:"447700900123",
        customer_email:"mcdonald@space.com"
     
    // Customer's address
        customer_country:"GB",
        customer_city:"Belfast",
        customer_address:"14A Cosmos Crescent, Flat 25",
        customer_zip:"BT99 0ZZ",
     
    // Customer's billing address
        billing_country:"GB",
        billing_city:"Belfast",
        billing_address:"14A Cosmos Crescent, Flat 25",
        billing_postal:"BT99 0ZZ",
     
    // Customer's address for the AVS check
        avs_street_address:"14A Cosmos Crescent, Flat 25",
        avs_post_code:"BT99 0ZZ",
     
    // Customer's redirection information 
        redirect_success_url:"https://cosmoshop.jupiter.example/pages/success",
        redirect_success_mode:"parent_page",
        redirect_fail_url:"https://cosmoshop.jupiter.example/pages/failed",
        redirect_fail_mode:"parent_page"
    }
    ```


## Parameters {#section_ick_qhq_l3c .section}

The following parameters can be used for opening the payment form in embedded mode.

|Parameter|Description|
|---------|-----------|
|`avs_post_code`  
 string, optional

|The postal code of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Example: `BT99 0ZZ`

|
|`avs_street_address`  
 string, optional

|The address of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Consists of a house number and a street name.

 Example: `14A Cosmos Crescent, Flat 25`

|
|`billing_address`  
 string, optional

|The name of the street and the house number\(including any additional parts of the address such as building indicators\) in the customer's billing address.

 Example: `14A Cosmos Crescent, Flat 25`

|
|`billing_city`  
 string, optional

|The name of the city in the customer's billing address.

 Example: `Belfast`

|
|`billing_country`  
 string, optional

|The country code in the customer's billing address.

 Specified in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|
|`billing_postal`  
 string, optional

|The postal code in the customer's billing address.

 Example: `BT99 0ZZ`

|
|`customer_address`  
 string, optional

|The name of the street and the house number\(including any additional parts of the address such as building indicators\) in the customer's address, separated by a comma.

 The length of the string cannot be more than 255 characters.

 Example: `14A Cosmos Crescent, Flat 25`

|
|`customer_city`  
 string, optional

|The name of the city \(or other settlement type\) in the customer's address.

 The length of the string cannot be more than 255 characters.

 Example: `Belfast`

|
|`customer_country`  
 string, optional

|The country code in the customer's address.

 Specified in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|
|`customer_email`  
 string, optional

|The email address of the customer.

 The length of the string cannot be more than 255 characters. The string consists of a local-part and a domain name, separated by the `@` symbol.

 Example: `mcdonald@space.com`

|
|`customer_first_name`  
 string, optional

|The first name of the customer.

 The length of the string cannot be more than 255 characters.

 Example: `Arthur`

|
|`customer_id`  
 string, optional

|The identifier assigned to the customer within the scope of the project\(specified in `project_id`\).

 Each web service account should be linked to only one identifier and vice versa. This requirement is intended to address various risks and fraudulent operations.

 Example: `customer_112`

|
|`customer_last_name`  
 string, optional

|The last name of the customer.

 The length of the string cannot be more than 255 characters.

 Example: `McDonald`

|
|`customer_phone`  
 string, optional

|The phone number of the customer.

 Generally, should include the country code; however, some cases do not require a country code to be specified. Should contain between four and 24 digits.

 Example: `447700900123`

|
|`force_payment_method`  
 string, required

|In case of processing payments via the Payment Page embedded mode, must be set to `card`.

 Example: `card`

|
|`merchant_domain`  
 string, required

|Domain name of the web service in which the payment form should be opened.

 Example: `cosmoshop.jupiter.example`

|
|`mode`  
 string, required

|Indicator that specifies the Payment Page operation mode.

 In case of processing payments with the use of buttons, must be set to `purchase` or `card_verify`.

 Example: `purchase`

|
|`operation_type`  
 string, optional

|Indicator that specifieswhether a purchaseis processed in one or two steps.

 Should be specified in cases where the intended payment type is different from the one specified by default \(with regard to the number of steps\). Can have one of the following values:

 -   `sale`—for one-step purchases \(with the funds transferred to the merchant immediately;[details](en_pp_purchase.md)\)
-   `auth`—for two-step purchases \(with the funds transferred to the merchant after first being in an authorisation hold;[details](en_pp_purchase_auth.md)\)

 Example: `auth`

|
|`payment_amount`  
 integer, required

|The amount of the payment.

 Specified in the smallest currency unit without a decimal separator.

 Example: `1960`\(represents an amount of 19.60 currency units when referring to a currency with two decimals\)

|
|`payment_currency`  
 string, required

|Three-letter code of the payment currency.

 Specified in the ISO-4217 alpha-3 format, according to the [currency codes reference](en_currency_codes.md).

 Example: `EUR`

|
|`payment_id`  
 string, required

|The payment identifier.

 Must be assigned by the web service. Should consist of a string no longer than 255 characters, be case-insensitive, and correspond one-to-one with the relevant payment within that project.

 Example: `X03936`

|
|`project_id`  
 integer, required

|Identifier of the projectintended to manage the interactions of the web service with the payment platform. This identifier is assigned by Ecommpayduring the integration \([details](en_glossary.md)\).

 Example: `22`

|
|`recurring`  
 string, optional

|Data of the COF purchase being registered \([details](en_pp_recurring.md)\).

 If the JavaScript library from Ecommpay is used, the data can be passed in the JSON objectthat can include any number of supported parameters.

 ``` {#codeblock_st1_lbb_j3c .language-json}
{
    "register": true,
    "type": "U"
}
```

|
|`redirect_fail_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is declined.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\)
-   `parent_page`—opens the pagein the currently active tab
-   `blank_page`—opens the pagein a new tab

 Example: `parent_page`

|
|`redirect_fail_url`  
 string, optional

|URL for final redirection to the web service if the purchase is declined.

 Example: `https://cosmoshop.jupiter.example/pages/failed`

|
|`redirect_success_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is completed.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe objectin which the payment form is opened
-   `parent_page`—opens the pagein the currently active tab
-   `blank_page`—opens the pagein a new tab

 Example: `parent_page`

|
|`redirect_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is completed.

 Example: `https://cosmoshop.jupiter.example/pages/success`

|
|`signature`  
 string, required

|The digital signature used to sign the query parameters.

 Should be generated using the appropriate algorithm after all relevant parameters have been specified \([details](en_platform_signature.md)\).

|
|`style_id`  
 integer, optional

|The identifier of the payment form design style.

 Can be used for working with different Payment Page design styles \([details](en_PP__design_customisation.md)\).

 Example: `6123`

|
|`target_element`  
 string, required

|The iframe element identifier\(for the HTML page of the web service\) of the element where the payment form should be opened.

 Example: `widget-container-card-embedded`

|

## Useful links {#section_asc_w4q_l3c .section}

When working with the payment platform via Payment Page in embedded mode, you can use the following articles:

-   [Customisation](en_PP__design_customisation.md)—an article about working with the **Payment Page Designer**.
-   [Collecting customer data](en_PP_Gathering_customer_data.md)—an article about the capability of collecting customer data.
-   [Payment retries](en_PP_Try_Again.md)—an article about the capability of payment retries.
-   [Signature generation and verification](en_platform_signature.md)—an article about generating and verifying signatures in requests and callbacks for interaction with the payment platform.
-   [SDKs for data signing](en_sdk_overview.md#section_vcj_5zv_tvb)—information about using SDKs for data signing.
-   [Handling events in Payment Page](en_pp_ui_monitoring.md)—an article about the capability of handling interface events of the payment form and related customer actions.
-   [Handling payment processing information](en_platform_payment_information.md)—a section on different ways to retrieve information that can be used for monitoring payment processing and analysing payment results.
-   [Test cards](en_test_cards.md)—an article with test card numbers that can be used for testing various payment processing scenarios.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# Using embedded buttons for Apple Pay and Google Pay payments {#en_pp_embedded_payment_buttons}

An article about using a specialised version of Payment Page that enables seamless, native-style integration of the Apple Pay and Google Pay services.

## Overview {#section_vdt_3tq_1hc .section}

In certain processing scenarios merchants may need to use branded payment buttons that allow their customers to pay for orders with the Apple Pay and Google Pay payment methods. When working with the Ecommpay payment platform, you can use a specialised version of Payment Page embedded into the web service in the form of payment buttons with specific brand identities. These embedded buttons allow you to process express checkout payments, with the collection of all required information, including shipping details, in the services of the payment methods used to make the purchase.

![](images/ecommpay/en_pp_one_click_buttons.svg)

When this functionality is implemented, the interface of the web service displays branded buttons of specific payment methods clicking which redirects the customer to the relevant payment service without involvement of the Payment Page interface. However, if additional data is required for payment processing, the customer can be shown a modal window with the relevant pages of the payment form. To avoid such cases, you are recommended to ensure that all additional data is passed in the requests for invoking Payment Page as well as to use the capability to collect customer data in the Apple Pay and Google Pay services.

Embedded payment buttons functionality is supported for Apple Pay and Google Pay payments and can be combined with invoking Payment Page for other payment processing options including card payments with tokens, redirecting to other payment methods by preselection in the web service, and using all available payment methods on the form. The appearance of embedded buttons can be configured via parameters for invoking the payment form. As of now, it is not possible to use the **Payment Page Designer** in Dashboard to set up the design of these buttons; however, the designer tool can be useful if you need to customise those pages of the payment form that are shown to the customers if additional data is required.

## Special aspects {#section_knm_zqz_t3c .section}

When using embedded Apple Pay and Google Pay buttons from Ecommpay, consider the following special aspects:

-   Embedding branded payment buttons directly into the web service of the merchant can improve user experience and increase conversion rates: firstly, the buttons of these global payment services are easily recognised and enhance customer trust, and, secondly, with the use of these buttons the number of steps in the standard user scenario is kept to a minimum, without any additional redirections and confirmations. To compare, opening Payment Page with the Apple Pay or Google Pay method preselected adds at least one more step to a similar user scenario.
-   The design of the branded buttons is customised according to the guidelines of Apple and Google and can be configured by the merchant as long as the style is consistent with their recommendations.
-   The minimalist design of the embedded buttons can be useful in different cases, namely, for interfaces with high information density or for mobile purchases.
-   Processing a payment with the use of embedded buttons implies native collection of necessary additional customer data \(including the customer's billing address, shipping address and shipping option, and other details\) directly in the Apple Pay and Google Pay services, within the payment session. It spares merchants the effort of collecting these data on the side of the web service or in Payment Page, as well as prevents increasing the number of steps in user scenarios and eliminates the need to take more action in order to configure this functionality.
-   When the customer has been authenticated in the Apple Pay or Google Pay service, and this service already has relevant information, the customer's payment can be processed according to the *express checkout* flow. This processing workflow implies that all necessary customer data \(card details, billing address, and shipping information\) is automatically collected and specified. In addition, the relevant shipping information and billing address can be available to the merchant through the payment session of this service. The *express checkout* flow can be useful for unregistered customers, as it enables guest checkout, without the need to create a user account in the web service.
-   The Apple Pay and Google Pay buttons can be embedded into any page of the web service \(for example, the product page or the section of the product catalogue\) and into almost any structural element of the web page \(including menus, various panels and containers\), which ensures high level of flexibility and allows implementation of various ways to guide customers to payment.

## Processing scenario {#section_xhp_hfr_1hc .section}

Below is a user scenario of making a purchase with embedded buttons.

![](images/ecommpay/en_one_click_button_scenario_1.svg "Selecting method")

![](images/ecommpay/en_one_click_button_scenario_2.svg "Providing shipping details")

![](images/ecommpay/en_one_click_button_scenario_3.svg "Confirming payment")

![](images/ecommpay/en_one_click_button_scenario_4.svg "Redirecting to the web service")

1.  The customer navigates to a page in the web service interface where embedded buttons are displayed and initiates a purchase using one of the payment methods.
2.  The customer is redirected to the service of the selected method.
3.  In the service, the customer provides a shipping address and selects the shipping option, if necessary, and performs other required actions.
4.  The customer is notified about the payment result \(how this information is communicated depends on the configuration of the web service\).

## Button design styles {#section_x2j_5lj_1jc .section}

The merchant can customise different aspects of the branded button's appearance, including the button's colour, contents \(i.e. the caption and the logo\), placement, size, and corner radius, with the help of the [following](en_pp_embedded_payment_buttons.md#section_fmg_ghl_nhc) parameters for opening the payment form.

![](images/ecommpay/en_embedded_payment_buttons_customisation.svg "Standard and customised design styles")

When working with the parameters for customising the appearance of branded buttons, consider the following:

-   You must comply with the requirements and guidelines of Apple \([details](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons)\) and Google \([details](https://developers.google.com/pay/api/web/guides/brand-guidelines)\).
-   Values that you specify for parameters determining the placement and the size of the buttons apply to all buttons used, whereas other parameters can be passed to customise each branded button individually.
-   If you specify the layout option for the buttons, it will be applied only when the width of the element where the buttons are embedded exceeds 1047 pixels. In all other cases, the buttons will be vertically stacked.
-   To resize the buttons, you can specify their height, but not their width. The width is determined automatically and is adjusted depending on the width of the element where the buttons are embedded and the number of buttons in one row. The minimum allowed width of each button is 160 pixels, and the maximum allowed corresponds to the width of the element where the buttons are embedded. The default height of the buttons is 44 pixels.

## Workflow {#section_uy1_lgr_1hc .section}

The interaction between the web service and the payment platform when the branded buttons are embedded requires the use of specialised libraries provided by Ecommpay and includes the following steps.

![](images/ecommpay/en_pp_one_click_buttons_uml.svg)

1.  The web service sends the request for processing a purchase via Payment Page to the specified Ecommpay URL.
2.  The request for processing a purchase via Payment Page is sent to the payment platform.
3.  The payment platform receives the request and validates the required parameters and signature.
4.  Payment Page is generated based on the project and request parameters.
5.  Embedded payment buttons are shown to the customer.
6.  The customer clicks the button of the payment method they need.
7.  The request is processed on the side of Payment Page.
8.  Payment Page sends a message that requires confirmation of the payment to the web service.
9.  The web service responds to Payment Page with a message that confirms the payment, following which the processing workflow for this specific method is invoked.
10. Payment Page sends a message with the result information and the customer redirection URL to the web service.

The interaction between the web service and the payment platform when shipping information is provided in the service of the selected payment method \(Google Pay or Apple Pay\) includes the following steps.

![](images/ecommpay/en_pp_one_click_buttons_shipping_uml.svg)

1.  The web service responds to Payment Page with a message that confirms the payment.
2.  The request for invoking the interface and the payment form of Google Pay is sent to the payment platform.
3.  The request for invoking the interface and the payment form of Google Pay and retrieving information about the customer's cards is sent to the Google Pay service.
4.  The Google Pay service processes the request and generates the payment form with the list of cards available to the customer.
5.  The customer is shown the interface of the Google Pay service with the list of cards with masked numbers and the fields to enter shipping details.
6.  The customer enters a shipping address.
7.  The Google Pay service processes the request.
8.  The Google Pay service sends the message with the shipping address to Payment Page.
9.  Payment Page sends the message with the shipping address to the web service.
10. The web service responds to Payment Page with a message confirming shipping availability to this address.
11. Payment Page sends the message confirming shipping availability to the Google Pay service.
12. The Google Pay service processes the request.
13. The customer is shown information about available shipping options.
14. The customer selects a shipping option.
15. The Google Pay service processes the request.
16. The Google Pay service sends the message with the information about the selected shipping option to Payment Page.
17. Payment Page sends the message with the information about the selected shipping option to the web service.
18. The web service responds to Payment Page with a message confirming this shipping option availability.
19. Payment Page sends the message confirming the shipping option availability to the Google Pay service.
20. The Google Pay service processes the request.
21. The customer is shown purchase details with shipping information \(shipping address and option\).
22. The customer performs other actions, if necessary, and confirms payment.
23. The Google Pay service processes the request.
24. The Google Pay service sends the message with purchase details that include shipping information to Payment Page
25. Payment Page sends the message with purchase details that include shipping information to the web service.
26. The web service responds to Payment Page with a message that confirms the payment, following which the processing workflow for this specific method is invoked.
27. Payment Page sends a message with the result information and the customer redirection URL to the web service.

## Setup and configuration {#section_nqn_lgr_1hc .section}

To start working with the embedded payment buttons functionality:

1.  On the client side, add the Ecommpay CSS and JavaScript libraries available at `https://paymentpage.ecommpay.com/shared/merchant.css` and `https://paymentpage.ecommpay.com/shared/merchant.js`.

    **Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS library via the CDN \(Content Delivery Network\). Storing this library locally is not allowed.

    ``` {#codeblock_gn5_ncq_qhc .language-xml}
    <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
    <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
    ```

2.  Configure the Content Security Policy by specifying the source URLs required for correct operation of the payment form in the `Content-Security-Policy` HTTP header \([details](en_pp_interaction_organisation.md#section_jth_vnh_qjc)\).

    ``` {#codeblock_ejr_n4k_mjc}
    Content-Security-Policy:
    script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com;
    style-src https://paymentpage.ecommpay.com;
    img-src https://applepay.cdn-apple.com;
    frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com
    ```

3.  On the client side, add the element for displaying embedded payment buttons.

    ``` {#codeblock_hn5_ncq_qhc .language-xml}
    <!-- Displaying each embedded payment button in a separate iframe element -->
    <div class="row">
      <div id="widget-container-google-pay"></div>
      <div id="widget-container-apple-pay"></div>
    </div>
    
    <!-- Displaying two embedded payment buttons in a single iframe element -->
    <div id="widget-container-one-click-buttons"></div>
    ```

4.  On the server side, set up data signing and sending signed data to the client side of the web service \([use one of the specialised SDKs](en_sdk_overview.md#section_vcj_5zv_tvb)\).
5.  Implement invoking the payment form on the client side using the JavaScript library from Ecommpay and the `EPayWidget.runEmbedded` method.
6.  On the client side, implement functions for handling interface events. In addition to the functions described in this article, you can use event handlers [described here](en_pp_ui_monitoring.md).
7.  If you plan to take Apple Pay payments, make sure to register production domains of your web service in the Apple Pay service.

## Use {#section_f34_lgr_1hc .section}

In general, to process a payment made with the use of embedded payment buttons, you need to:

1.  Generate requests to display the required buttons.
2.  Invoke the payment form displayed as branded buttons.
3.  Confirm the transition to payment when the customer clicks a specific button.
4.  Confirm the availability of the shipping option selected by the customer.
5.  Confirm processing the payment with the finalised set of parameters.

Here is a more detailed description of these steps:

1.  Generate the required number of requests to open a payment form displayed as branded buttons.

    It can be one request to display both buttons in a single iframe element, two separate requests to display each button in separate iframe elements, or one separate request to display just one of the buttons. Each of the requests must contain the `configObj` JavaScript object with [the parameters](en_pp_embedded_payment_buttons.md) for invoking the payment form and [the signature](en_platform_signature.md) for them.

    When creating a request for opening the payment form, consider the following:

    -   The essential data set required for processing a payment in this case includes:
        -   `target_element`—identifier of the iframe element in which the payment form should be opened
        -   `payment_id`—payment identifier unique within the project
        -   `payment_amount`—payment amount in the smallest currency unit
        -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
        -   `project_id`—project identifier obtained from Ecommpay during integration
        -   `merchant_domain`—domain name of the web service in which the payment form should be opened
        -   `force_payment_group` to display buttons for both methods \(with the value `one_click_buttons`\) or `force_payment_method` to display the button for only one of the methods \(with the value `apple_pay_core` for the Apple Pay method or `google_pay_host` for the Google Pay method\)
        -   `mode`—Payment Page operation mode indicator with the value `purchase`
        -   `signature`—request signature generated after all parameters have been specified
    -   To initiate additional steps to be performed on the side of the Apple Pay and Google Pay services, use the `payment_methods_options` parameter and specify the following:

        -   a list of requested customer information in the `billing_contact_fields` array if collection of customer information is not configured for all payments within the project being used \([details](en_PP_Gathering_customer_data.md)\)
        -   information about the available shipping options in the `shipping` object—so that the customer can select one
        The detailed list of information that can be specified in the `payment_methods_options` parameter can be found [below](en_pp_embedded_payment_buttons.md#section_fmg_ghl_nhc).

    ``` {#codeblock_hgm_1yl_wgc .language-javascript}
    {
      "target_element":"widget-container-one-click-buttons",
      "payment_id":"X03936",
      "payment_amount":131960,
      "payment_currency":"USD",
      "project_id":22,
      "merchant_domain":"cosmoshop.jupiter.example",
      "force_payment_group":"one_click_buttons",
      "mode":"purchase",
      "signature":"YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV"
    }
    ```

    ``` {#codeblock_p4q_12m_dhc .language-json}
    {
      "express_checkout":{
        "billing_contact_fields":[
          "email",
          "name",
          "phone",
          "billing_address",
          "postal_code"
        ],
        "shipping":{
          "shipping_fields":[
            "shipping_address",
            "name",
            "phone"
          ],
          "allowed_country_codes":[
            "GB",
            "IE"
          ],
          "shipping_methods":[
            {
              "label":"Speed of sound shipping",
              "detail":"Express shipping (1 hour)",
              "amount":199,
              "identifier":"cosmo-shipping-009"
            },
            {
              "label":"Warp drive shipping",
              "detail":"Instant shipping",
              "amount":2999,
              "identifier":"cosmo-shipping-012"
            }
          ]
        },
          "buttons":{
             "max_column":1,
             "height": 40,
             "border_radius": 100
          }
      },
       "google_pay_host":{
          "shipping":{
             "allowed_country_codes":[
                "GB",
                "IE"
             ]
          },
          "button":{
             "color":"black",
             "type":"checkout",
             "border_type":"no_border"
          }
       },
      "apple_pay_core":{
          "button":{
             "theme":"black",
             "type":"buy"
          }
       }
    }
    ```

2.  Invoke the payment form using the `EPayWidget.runEmbedded` method.

    When invoking the form, specify the `configObj` JavaScript object and declare necessary event handler functions, such as `onCheckSubmit` \(used for handling button click information; more details below\).

    ``` {#codeblock_s5r_xyl_wgc .language-javascript}
    const checkoutButtonsWidget = EPayWidget.runEmbedded({
        ...configObj,
        onCheckSubmit: async function (data, resolve, reject) {
            if (!await merchantPage.validateCheckoutPage()) {
                return reject() // Decline of purchase
            }
            if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) {
                return reject() // Decline of purchase
            };
            return resolve(); // Purchase confirmation, with the option to specify the additional_parameters object as an argument
        },
    }, 'POST');
    ```

3.  When the customer confirms the payment \(via the embedded button\), check the payment details \(including the amount and currency, as well as other important parameters\) and call the relevant function: `resolve` to confirm the purchase or `reject` to decline it.

    At this stage, along with the payment confirmation, you can specify additional information if it was not specified when the payment form was invoked or if the information needs to be changed. You can pass:

    -   customer information and redirect URLs—in the `additional_parameters` object
    -   the customer identifier, information about the purchased items, and extended purchase data to be used on the web service side—in the `payment_update` object \(in which you also specify the project identifier, the payment identifier, amount, and currency, as well as the [signature](en_platform_signature.md) for the parameters in this object\)
    If the payment is declined, the customer should be provided with information about the error on the web service side.

    ``` {#codeblock_ctr_ztl_wgc .language-json}
    {
    // General customer information
        customer_first_name:"Arthur",
        customer_last_name:"McDonald",
        customer_phone:"447700900123",
        customer_email:"mcdonald@space.com"
     
    // Customer's residential address
        customer_country:"GB",
        customer_city:"Belfast",
        customer_address:"14A Cosmos Crescent, Flat 25",
        customer_zip:"BT99 0ZZ",
     
    // Customer's billing address
        billing_country:"GB",
        billing_city:"Belfast",
        billing_address:"14A Cosmos Crescent, Flat 25",
        billing_postal:"BT99 0ZZ",
     
    // Customer's address used for the AVS check
        avs_street_address:"14A Cosmos Crescent, Flat 25",
        avs_post_code:"BT99 0ZZ",
     
    // Customer's redirection information
        redirect_success_url:"https://cosmoshop.jupiter.example/pages/success",
        redirect_success_mode:"parent_page",
        redirect_fail_url:"https://cosmoshop.jupiter.example/pages/failed",
        redirect_fail_mode:"parent_page",
    };
    ```

    ``` {#codeblock_znb_khr_1jc .language-json}
    {
       "project_id":22,
       "payment_id":"X03936",
       "payment_amount":131960,
       "payment_currency":"USD",
       "customer_id":"customer_112",
       "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=",
       "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"",
       "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w=="
    }
    ```

4.  If the request to open a payment form included information about available shipping options for goods or services in the `shipping` object, verify and confirm \(or decline\) the shipping availability.

    Use the `onCheckShippingAddress` and `onCheckShippingMethod` functions of the merchant.js library to respond to the customer's input of a shipping address and shipping option, respectively. When using these functions, keep in mind that the order in which the shipping address and shipping option are specified may vary depending on the specifics of the service being used, and that checking the shipping availability is repeated whenever the customer's input changes. You are also recommended to ensure that the error messages related to shipping availability are structured to provide sufficient information and convenience to customers and prevent future errors.

    To check shipping availability, each time the customer changes shipping parameters, follow these steps:

    -   Regarding the shipping address, check the availability of shipping to the address specified by the customer and call the relevant function:

        -   `onCheckShippingAddress.resolve`—to confirm shipping availability, with the mandatory passing of the payment amount with shipping included and, if applicable, with updated shipping parameters \(specified in the `shipping_methods` array\).
        -   `onCheckShippingAddress.reject`—to notify that shipping is unavailable, with the mandatory passing of the payment amount excluding shipping and, if applicable, with the messages to be displayed to the customer, including a general error message and specific clarifications for each of the shipping details.
        ``` {#codeblock_w41_dkk_dhc .language-json}
        {
          "region":"Belfast City",
          "city":"Belfast",
          "country_code":"GB",
          "postal_code":"BT99 0ZZ"
        }
        ```

        ``` {#codeblock_y5q_ttn_jhc .language-javascript}
        errors = {
            "fields": {
                "country_code": "Supported shipping countries: GB, DE, IT",
                "region": "This region is not supported",
                "city": "Only Dublin is available",
                "postal_code": "The range of postal address 10060 - 100150",
            },
            "message": "Cannot ship to the provided address"
        }
        ```

    -   Regarding the shipping option, check the availability of the shipping option selected by the customer and call the relevant function:

        -   `onCheckShippingMethod.resolve`—to confirm shipping availability, with the mandatory passing of the payment amount with shipping included.
        -   `onCheckShippingMethod.reject`—to notify that shipping is unavailable, with the mandatory passing of the payment amount excluding shipping and, if applicable, with the messages to be displayed to the customer.
        ``` {#codeblock_n4l_zlk_dhc .language-json}
        {
          "identifier":"cosmo-shipping-012"
        }
        ```

        ``` {#codeblock_bv1_pwn_jhc .language-javascript}
        errors = {
            "message": "This shipping option cannot be selected for this address",
        }
        ```

5.  If you need to confirm the payment \(with the selected shipping address and shipping option, or other details provided by the customer\), check whether the finalised payment information is accurate.

    Use the `onConfirmation` function of the merchant.js library to obtain this information. After verifying, call the relevant function:

    -   `onConfirmation.resolve`—to confirm the payment, with final details provided by the web service. This information includes:
        -   the project identifier, the identifier, amount, and currency of the payment, and other relevant information \(as needed, including information about the purchased items and extended purchase data for subsequent use on the web service side\) and the [signature](en_platform_signature.md) for these parameters in the `payment_update` object
        -   customer information and redirect URLs \(if such information needs to be specified or updated\) in the `additional_parameters` object
    -   `onConfirmation.reject`—to decline the payment, with the mandatory passing of the payment amount and, if applicable, with the error message to be displayed to the customer.
    ``` {#codeblock_ml1_4wt_fjc .language-json}
    {
      "customer":{
          "email":"mcdonald@space.com",
          "first_name":"Arthur",
          "last_name":"McDonald",
          "phone":"447700900123"
       },
      "billing_address":{
          "address":"14A Cosmos Crescent, Flat 25",
          "city":"Belfast",
          "region":"Belfast City",
          "country_code":"GB",
          "postal_code":"BT99 0ZZ"
      },
      "shipping_address":{
        "address":"Dock 7, Innovation Hangar",
        "city":"Belfast",
        "region":"Belfast City",
        "country_code":"GB",
        "postal_code":"BT99 1XY",
        "first_name":"Arthur",
        "last_name":"McDonald",
        "phone":"447700900321"
      }
    }
    ```

    ``` {#codeblock_ugm_wnk_dhc .language-javascript}
    {
       "project_id":22,
       "payment_id":"X03936",
       "payment_amount":131960,
       "payment_currency":"USD",
       "customer_id":"customer_112",
       "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=",
       "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"",
       "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w=="
    }
    ```

    ``` {#codeblock_wfp_fc2_fhc .language-json}
    {"billing_country": "GB", "customer_email": "mcdonald@space.com", "avs_post_code": "BR1 1AA", "redirect_success_url":"https://cosmoshop.jupiter.example/order?id=123"}
    
    ```

    ``` {#codeblock_ncc_swt_fjc .language-javascript}
    errors = {
        "fields": {
            "country_code": "Supported shipping countries: GB, DE, IT",
            "region": "This region is not supported",
            "city": "Only Dublin is available",
            "postal_code": "The range of postal address 10060 - 100150",
        },
        "message": "Cannot ship to the provided address"
    }
    ```


Additionally, on the merchant's web service side, it is possible to manage the display of the preloader page and receive information about errors and payment processing results using the following functions for handling interface events:

-   `onShowLoader`—for displaying the web service preloader
-   `onHideLoader`—for hiding the web service preloader \(if it is necessary to display the payment form pages to the customer\)
-   `onPaymentSubmitResult`—for receiving information about the request identifier \(if it is necessary to check payment status information\)
-   `onError`—for receiving information about errors on the payment form side

You can also use [callbacks](en_platform_callbacks.md) to monitor payment processing results.

The following is an example of the HTML code for the web service frontend that ensures the capability of performing purchases made with embedded payment buttons.

``` {#codeblock_fd1_mxx_1hc .language-javascript}
const expressButtons = EPayWidget.runEmbedded({
    payment_amount: 131960,
    payment_currency: "USD",
    project_id: "22",
    payment_id: "X03936",
    force_payment_group: "one_click_buttons",
    payment_methods_options: {"google_pay_host": {"billing_contact_fields": ["name", "email", "phone", "billing_address"]}},
    target_element: "widget-container-one-click-buttons",
    merchant_domain: cosmoshop.jupiter.example,
    signature: "abcYWb6Z30hfTIjaCCsVIDEF123",
 
    onShowLoader: merchantPage.showMerchantLoader,
    onHideLoader: merchantPage.hideMerchantLoader,
    onCheckSubmit: async function (data, resolve, reject) {
        if (await merchantAPI.canStartPayment(merchantPage.cart)) {
            return resolve();
        }
        return reject();
    },
    onCheckShippingAddress: async function (data, resolve, reject) {
        const {addressIsAvailable, newPaymentAmount, newShippingMethods, errors} = await merchantAPI.validateShippingAddress(data);
        if (addressIsAvailable) {
            return resolve({payment_amount: newPaymentAmount, shipping_methods: newShippingMethods});
        } else {
            return reject({payment_amount: newPaymentAmount, errors});
        }
    },
    onCheckShippingMethod: async function (data, resolve, reject) {
        const {addressIsAvailable, newPaymentAmount} = await merchantAPI.saveShippingMethod(orderId, data.identifier);
        if (addressIsAvailable) {
            return resolve({payment_amount: newPaymentAmount});
        } else {
            return reject({payment_amount: newPaymentAmount});
        }
    },
    onConfirmation: async function (data, resolve, reject) {
        const { orderId, paymentUpdate, additionalParameters, errors } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo);
         
        if (orderId) {
            return resolve({payment_update: paymentUpdate, additional_parameters: additionalParameters});
        } else {
            return reject({errors})
        }
    },
    onPaymentSubmitResult: async function (data) {
        await merchantAPI.saveTransactionId(data.request_id)
    },
    onError: async function ({ messages }) {
        await merchantAPI.log("Payment error occurred " + messages)
        if (messages.includes("invalid payment_id")) {
            merchantPage.redirectToContactSupportPage();
        }
    },
});
```

**Parent topic:**[Payment Page](en_PP_about.md)

## Parameters {#en_pp_embedded_payment_buttons_parameters}

### General parameters {#section_cgy_fhl_nhc .section}

The following parameters can be used when you work with the functionality of embedded payment buttons.

|Parameter|Description| |
|---------|-----------|--|
|`avs_post_code`  
 string, optional

|The postal code of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Example: `BT99 0ZZ`.

| |
|`avs_street_address`  
 string, optional

|The address of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Consists of a house number and a street name.

 Example: `14A Cosmos Crescent, Flat 25`.

| |
|`billing_address`  
 string, optional

|The house number \(including any additional parts of the address such as building and apartment numbers\) and the name of the street in the customer's billing address.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `14A Cosmos Crescent, Flat 25`.

| |
|`billing_city`  
 string, optional

|The name of the city in the customer's billing address.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `Belfast`.

| |
|`billing_country`  
 string, optional

|The country code in the customer's billing address.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `GB`.

| |
|`billing_postal`  
 string, optional

|The postal code in the customer's billing address.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `BT99 0ZZ`.

| |
|`billing_region`  
 string, optional

|The name of the region \(i.e., state, province, or other administrative division type\) in the customer's billing address.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `Belfast City`.

| |
|`billing_region_code`  
 string, optional

|The recipient's country subdivision code \(state, province, region, or territory\). The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. This parameter should be specified in requests where the `billing_country` parameter is also specified.

 To collect customer billing address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `BFS`.

| |
|`customer_address`  
 string, optional

|The name of the street and the house number \(including any additional parts of the address such as building and apartment numbers\) in the customer's address, separated by a comma.

 The length of the string cannot be more than 255 characters.

 Example: `14A Cosmos Crescent, Flat 25`.

| |
|`customer_birthplace`  
 string, optional

|The name of the customer's birthplace \(e.g., town, city, or other settlement type\).

 The length of the string cannot be more than 255 characters.

 Example: `York`.

| |
|`customer_city`  
 string, optional

|The name of the place of residence \(e.g., town, city, or other settlement type\) in the customer's address.

 The length of the string cannot be more than 255 characters.

 Example: `Belfast`.

| |
|`customer_country`  
 string, optional

|The country code in the customer's address.

 Specified in ISO 3166-1 alpha-2 format.

 Example: `GB`.

| |
|`customer_day_of_birth`  
 string, optional

|The date of birth of the customer.

 Consists of a string specified in `DD-MM-YYYY` format.

 Example: `12-03-1986`.

| |
|`customer_email`  
 string, optional

|The email address of the customer.

 The length of the string cannot be more than 255 characters. The string consists of a local-part and a domain name, separated by the `@` symbol.

 To collect customer email address information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `mcdonald@space.com`.

| |
|`customer_first_name`  
 string, optional

|The first name of the customer.

 The length of the string cannot be more than 255 characters.

 To collect customer first name information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `Arthur`.

| |
|`customer_id`  
 string, optional

|The identifier assigned to the customer within the scope of the project \(specified in `project_id`\).

 Each web service account should be linked to only one identifier and vice versa. This requirement is intended to address various risks and fraudulent operations.

 Example: `customer_112`.

| |
|`customer_last_name`  
 string, optional

|The last name of the customer.

 The length of the string cannot be more than 255 characters.

 To collect customer last name information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `McDonald`.

| |
|`customer_middle_name`  
 string, optional

|The middle, second, or patronymic name of the customer.

 The length of the string cannot be more than 255 characters.

 Example: `Rhys`.

| |
|`customer_phone`  
 string, optional

|The phone number of the customer.

 Generally, should include the country code; however, some cases do not require a country code to be specified.

 Should contain between four and 24 digits. If a particular project and payment method allow for the inclusion of punctuation marks and special characters in the phone number, the parameter can contain such characters in those cases; this is usually specially arranged beforehand.

 To collect customer phone number information on the Apple Pay and Google Pay service side, use the `payment_methods_options` parameter.

 Example: `447700900123`.

| |
|`customer_state`  
 string, optional

|The name of the region \(state, province, or other administrative subdivision type\) of the customer's address.

 The length of the string cannot be more than 255 characters.

 Example: `Belfast City`.

| |
|`customer_street`  
 string, optional

|The name of the street in the customer's address.

 The length of the string cannot be more than 255 characters.

 Example: `Cosmos Crescent`.

| |
|`customer_zip`  
 string, optional

|The postal or zip code in the customer's address.

 The length of the string cannot be more than 10 characters.

 Example: `BT99 0ZZ`.

| |
|`force_payment_method`  
 string, required\*

|For processing payments using embedded payment buttons; can take one of the following values:

 -   `apple_pay_core`—to display the button for the Apple Pay method
-   `google_pay_host`—to display the button for the Google Pay method

 Only one of the parameters, `force_payment_method` or `force_payment_group`, must be specified with each payment form invocation, not both.

 Example: `google_pay_host`.

| |
|`force_payment_group`   
 string, required\*

|For processing payments using embedded payment buttons; can take the value `one_click_buttons`. In this case, buttons for both methods, Apple Pay and Google Pay, are displayed.

 Only one of the parameters, `force_payment_method` or `force_payment_group`, must be specified with each payment form invocation, not both.

 Example: `one_click_buttons`.

| |
|`merchant_data`  
 string, optional

|Additional information that needs to be tracked by the web service.

 The data that is passed in this parameter can vary. However, what data set is passed in this parameter should be communicated to the Ecommpay specialists and configured beforehand to ensure the data is processed and displayed correctly in callbacks and payment information tabs \(see [this article](en_pp_additional_data.md)\). In specific cases can contain a JSON object; then, the `"` character \(quotation mark, U+0022\) needs to be preceded by the `\` escape character \(reverse solidus, U+005C\) in order to be sent via a POST request.

 ``` {#codeblock_ts4_xhb_d2c .language-json}
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"
```

| |
|`merchant_domain`  
 string, required

|Domain name of the web service in which the payment form should be opened.

 Example: `cosmoshop.jupiter.example`.

| |
|`mode`  
 string, required

|Indicator that specifies the Payment Page operation mode.

 For processing payments using One-click buttons, must take the value `purchase`.

 Example: `purchase`.

| |
|`payment_amount`  
 integer, required

|The amount of the payment in the smallest currency unit.

 Specified in the smallest currency unit without a decimal separator.

 Example: `131960` \(for the amount of 1319.60 in the currency with two decimals\).

| |
|`payment_currency`  
 string, required

|Three-letter code of the payment currency.

 Specified in the ISO-4217 alpha-3 format, according to the [currency codes reference](en_currency_codes.md).

 Example: `USD`.

| |
|`payment_id`  
 string, required

|The payment identifier.

 Must be assigned by the web service. Should consist of a string no longer than 255 characters, be case-insensitive, and correspond one-to-one with the relevant payment within that project.

 Example: `X03936`.

| |
|`payment_methods_options`  
 string, optional

|Additional information relevant for specific payment methods and third-party services. Should include parameters listed [in the table below](en_pp_embedded_payment_buttons.md#section_fmg_ghl_nhc).

| |
|`project_id`  
 integer, required

|Identifier of the project intended to manage the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration \([details](en_glossary.md)\).

 Example: `22`.

| |
|`receipt_data`  
 string, optional

|Information about line items in an order.

 Can be used to generate a proof of purchase document to be sent to the customer \(see [this article](en_PP_receipt_data.md)\). Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. The JSON object can include various combinations of elements from the list of supported data.

 -   `positions`, array—array which allows listing up to 300 purchased items in the notification. For each listed item, the following information can be specified:
    -   `amount`, integer—the price of the item
    -   `quantity`, integer—the number of purchased items of the same kind
    -   `tax`, integer—the VAT rate if it differs for different listed items
    -   `tax_amount`, integer—the VAT amount
    -   `description`, string—the description of the purchased item.
-   `total_tax_amount`, integer—the total VAT amount for the entire purchase
-   `common_tax`, integer—the VAT rate if it is the same for all listed items

 ``` {#codeblock_vd1_r3b_d2c .language-json}
{  
   "receipt_data":{  
      "positions":[  
         {  
            "quantity":3,
            "amount":10000,
            "tax":18,
            "tax_amount":1800,
            "description":"Design frame"
         }
      ],
      "total_tax_amount":1800,
      "common_tax":18       
   }
}
```

 ``` {#codeblock_k1g_r3b_d2c}
receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAg
ICAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI
6MTgsCiAgICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiJEZXN
pZ24gZnJhbWUiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAsCiAgICA
gICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ"
```

| |
|`redirect_fail_url`  
 string, optional

|URL for final redirection to the web service if the purchase is declined.

 Example: `https://cosmoshop.jupiter.example/pages/failed`.

| |
|`redirect_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is completed.

 Example: `https://cosmoshop.jupiter.example/pages/success`.

| |
|`signature`  
 string, required

|The digital signature used to sign the query parameters.

 Should be generated using the appropriate algorithm after all relevant parameters have been specified \(see [this article](en_platform_signature.md)\).

| |
|`target_element`  
 string, required

|The iframe element identifier \(for the HTML page of the web service\) of the element where the payment form should be opened.

 Example: `widget-container-one-click-buttons`.

| |

### Parameters specific to Apple Pay and Google Pay {#section_fmg_ghl_nhc .section}

When working with the functionality of embedded payment buttons, you can specify the following data relevant to Apple Pay and Google Pay payments in the `payment_methods_options` parameter.

|Parameter|Description| |
|---------|-----------|--|
|`express_checkout`  
 object, optional

|Additional information relevant for all payment methods.|29-3|
|`buttons`  
 object, optional

|Parameters customising the appearance of the branded buttons.

 Example: `"buttons":{"max_column":1, "height": 40, "radius": 100 }`

|29-3-129-3|
|`height`  
 integer, optional

|Height of the button, in pixels.

 Will be applied to each embedded button. Can be between 40 and 55 pixels. The default value is 44 pixels.

 Example: `40`

|29-3-1-129-3-1|
|`border_radius`  
 integer, optional

|Corner radius of the button, in pixels.

 Will be applied to each embedded button. Can be between 0 and 100 pixels. The default value is 4 pixels.

 Example: `100`

|29-3-1-229-3-1|
|`max_columns`  
 integer, optional

|The indicator of the layout option for the buttons embedded in the iframe element.

 The specified option is applied only when the width of the element where the buttons are embedded exceeds 1047 pixels. In all other cases, the value of this parameter will be ignored and only one button is displayed in one row.

 Can take one of the following values:

 -   `0`—as many buttons as possible are displayed in one row \(*flexible layout*; used by default\).
-   `1`—only one button is displayed in one row \(*strictly one-column layout*\).
-   `2`—if possible, two buttons are displayed in one row \(*two-column layout if possible*\).

 Example: `1`

|29-3-1-329-3-1|
|`shipping`  
 object, optional

|Shipping information.|29-3-229-3|
|`shipping_fields`  
 array, optional

|Shipping address information, to be collected on the Google Pay service side.

 An array with the list of required data, including:

 -   `phone`—the phone number of the shipment recipient
-   `name`—the first and last name of the shipment recipient
-   `shipping_address`—shipping address

 Example: `"shipping_fields":["shipping_address"]`

|29-3-2-129-3-2|
|`shipping_methods`  
 array, optional

|Information about available shipping options. The shipping option listed first is shown in the Google Pay service as a default one.|29-3-2-329-3-2|
|`label`  
 string, required\*

|The name of the shipping option to be shown to the customer.

 Must be specified when the `shipping_methods` array is passed.

 Example: `Warp drive shipping`

|29-3-2-3-129-3-2-3|
|`detail`  
 string, required\*

|Description of the shipping option to be shown to the customer.

 Must be specified when the `shipping_methods` array is passed.

 Example: `Instant shipping`

|29-3-2-3-229-3-2-3|
|`amount`  
 integer, required\*

|The cost of the shipping.

 Specified in the smallest unit of currency passed in the `payment_currency` parameter, without a decimal separator.

 Must be specified when the `shipping_methods` array is passed.

 Example: `2999` \(for the amount of 29.99 in the currency with two decimals\)

|29-3-2-3-329-3-2-3|
|`identifier`  
 string, required\*

|The identifier of the shipping option, assigned on the side of the web service.

 Must be specified when the `shipping_methods` array is passed.

 Example: `cosmo-shipping-012`

|29-3-2-3-429-3-2-3|
|`billing_contact_fields`  
 array, optional

|Customer billing address information to be collected on the Apple Pay or Google Pay service side.

 Represents an array with a list of requested information, which can include:

 -   `email`—the customer's email address
-   `name`—the customer's first and last name
-   `phone`—the customer's phone number
-   `postal_code`—the postal code from the customer's address
-   `billing_address`—the customer's billing address

 Example: `"billing_contact_fields":["email","phone"]`.

|29-3-329-3|
|`google_pay_host`  
 object, optional

|Additional information relevant for Google Pay payments.|29-2|
|`shipping`  
 object, optional

|Shipping information.|29-2-129-2|
|`allowed_country_codes`  
 array, optional

|Information about the countries where the shipping is available. If this information is not specified, the shipping is deemed available in all countries.

 An array with the list of country codes in ISO 3166-1 alpha-2.

 Example: `"allowed_country_codes":["GB","IE"]`

|29-2-1-229-2-1|
|`button`  
 object, optional

|Parameters customising the appearance of the button.

 Example: `"button":{"theme":"black","type":"checkout","border_type": "no_border" }`

|29-2-329-2|
|`border_type`  
 string, optional

|Indicator specifying the border type of the button \([details](https://developers.google.com/pay/api/web/guides/brand-guidelines#custom-button)\).

 Can take one of the following values:

 -   `default_border`—with the border
-   `no_border`—with the border removed

 The default value is `default_border`.

 Example: `no_border`

|29-2-3-129-2-3|
|`color`  
 string, optional

|Indicator specifying the colour of the button \([details](https://developers.google.com/pay/api/web/guides/brand-guidelines#custom-button)\).

 Can take one of the following values:

 -   `black`—for the dark style
-   `white`—for the light style

 The default style is dark.

 Example: `black`

|29-2-3-229-2-3|
|`type`  
 string, optional

|Indicator specifying the button's caption according to the Google Pay documentation \([details](https://developers.google.com/pay/api/web/guides/brand-guidelines#style)\).

 For example, if you pass `donate`, the button with caption **Donate with <Google Pay\>** will be displayed, to be used for collecting donations.

 Example: `checkout`

|29-2-3-329-2-3|
|`apple_pay_core`  
 object, optional

|Additional information relevant for Apple Pay payments.|29-1|
|`button`  
 object, optional

|Parameters customising the appearance of the button.

 Example: `"button":{"theme":"black","type":"buy" }`

|29-1-329-1|
|`theme`  
 string, optional

|Indicator specifying the colour of the button \([details](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Button-styles)\).

 Can take one of the following values:

 -   `black`—for the dark style without the button outline
-   `white`—for the light style without the button outline
-   `white-outline`—for the light style with the outline

 The default style is dark.

 Example: `black`

|29-1-3-129-1-3|
|`type`  
 string, optional

|Indicator specifying the button's caption according to the Apple Pay documentation \([details](https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype)\).

 For example, if you pass `contribute`, the button with caption **Contribute with <Apple Pay\>** will be displayed, to be used for collecting donations.

 Example: `buy`

|29-1-3-229-1-3|



---

# UX configuration {#en_pp_ux_configuration}

Articles about the primary workflows for the standard version of Payment Page, including options for opening it, handling redirects to third-party services and back to the web service, and managing these processes.

The information about various options of the payment form UX configuration:

-   [Options for opening Payment Page](en_PP_Integration.md)—about the ways of opening the form, including its opening in a separate tab, modal window, and an iframe object.
-   [Options for redirecting customers to third-party services](en_PP_pm_redirect_mode.md)—about the ways of opening auxiliary pageswhen working with different payment methods.
-   [Options for redirecting customers to the web service](en_PP_redirect_modes.md)—about the ways of redirecting customers from the payment form to the web service via the specified URLs.

-   **[Options for opening Payment Page](en_PP_Integration.md)**  
Articles about options for opening Payment Page: in a separate tab, a modal window, or an iframe.
-   **[Options for redirecting customers to third-party services](en_PP_pm_redirect_mode.md)**  
An article about options for opening third-party auxiliary pages across different payment methods.
-   **[Options for redirecting customers to the web service](en_PP_redirect_modes.md)**  
An article about options for redirecting customers from the payment form to the web service using the specified URLs.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# Options for opening Payment Page {#en_PP_Integration .concept}

Articles about options for opening Payment Page: in a separate tab, a modal window, or an iframe.

There are different options to open the Payment Page payment form on customers' devices: in a separate browser tab, in a modal window, and directly on the web service page—in an iframe element. These options are managed on the web service side, and when they are set up, various factors can be considered: for example, the payment form can be set up in such a way that on mobile devices it opens in a separate browser tab, while on other devices it opens in a modal window.

In order to configure the opening of Payment Page on the web service side in a way needed, address the general issues of [the interaction concepts](en_pp_interaction_organisation.md) and refer to the articles of this subsection.

-   [Opening Payment Page as a separate HTML page](en_PP_method_NewTab.md)
-   [Opening Payment Page in a modal window](en_PP_method_ModalWindow.md)
-   [Opening Payment Page in an iframe element of an HTML page](en_PP_method_Embedded.md)

-   **[Opening Payment Page as a separate HTML page](en_PP_method_NewTab.md)**  
An article about opening Payment Page as a separate HTML page with the use of the JavaScript library from Ecommpay and in-house solutions.
-   **[Opening Payment Page in a modal window](en_PP_method_ModalWindow.md)**  
An article about opening Payment Page in a modal window with the use of the JavaScript library from Ecommpay and in-house solutions.
-   **[Opening Payment Page in an iframe element of an HTML page](en_PP_method_Embedded.md)**  
An article about opening Payment Page in an iframe element with the use of the JavaScript library from Ecommpay and in-house solutions.

**Parent topic:**[UX configuration](en_pp_ux_configuration.md)



---

# Opening Payment Page as a separate HTML page {#en_PP_method_NewTab .concept}

An article about opening Payment Page as a separate HTML page with the use of the JavaScript library from Ecommpay and in-house solutions.

**Parent topic:**[Options for opening Payment Page](en_PP_Integration.md)

## Overview {#en_pp_opening_html_overview}

When opened as a separate HTML page, the Payment Page payment form is displayed to the customer in a separate browser tab.Depending on the browser operation setup, it can be an active tab, in which the web service page was opened, or a new tab—but in either case, the customer's interaction with the web service is interrupted and the customer is redirected to a different page, which focuses their attention on the purchase. After the purchase, the customer can be redirected back to the web service \([details](en_PP_redirect_modes.md)\).

![](images/ecommpay/en_pp_general_3.svg)

For opening the payment form as a separate page, the following should be performed on the web service side:

1.  Define the events upon which the payment form should open\(for example, the purchase button click\).
2.  Set up the payment form to open upon the required eventsby using your in-house solutions or the JavaScript library from Ecommpay available at `https://paymentpage.ecommpay.com/shared/merchant.js`. Among other capabilities, this library allows you to automatically use a certain option of Payment Page opening depending on a device. It means the form can be set to open as a separate page on mobile devices and in a modal window or in an iframe element on other devices.

## Opening Payment Page via in-house solutions {#en_pp_opening_html_via_in_house_solutions}

To open the payment form as a separate HTML page, redirect your customer to a URL of the following format:

```
https://paymentpage.ecommpay.com/payment?<parameters>
```

In this URL, `<parameters>` is a data string with the names and values of the parameters in pairs \(including the signature\) delimited by the ampersand character \(`&`\). The information about the parameters and signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

```
https://paymentpage.ecommpay.com/payment?project_id=42&customer_id=123&payment_id=4438&payment_amount=1000&payment_currency=EUR&signature=AE5hmtzdP0Dt7qGTg...
```

## Opening Payment Page via the Ecommpay JavaScript library {#en_pp_opening_html_via_javascript_library}

While the JavaScript library provided by Ecommpay is primarily intended to simplify opening of the payment form [in a modal window](en_PP_method_ModalWindow.md) and [in an iframe element](en_PP_method_Embedded.md), it can also be used for opening the form as a separate HTML page. For example, you can set the form to open as a separate page on mobile devices and in a modal window on other devices.

To open Payment Page as a separate page using the JavaScript library `merchant.js` from Ecommpay, link the library on the client side of the web service and use the corresponding calls to the `EPayWidget` object. Beside that, if you plan to use the JavaScript library for other options for the Payment Page opening, you should also link the CSS library available at `https://paymentpage.ecommpay.com/shared/merchant.css`.

**Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS library via the CDN \(Content Delivery Network\). Storing this library locally is not allowed.

In the calls to the `EPayWidget` object, the `configObj` object must contain one of the following parameters:

-   `redirect_on_mobile` with the value `true`—for opening the payment form as a separate HTML page on mobile devices only;
-   `redirect` with the value `true`—for opening the payment form as a separate HTML page on all devices.

If these parameters are not specified or not applicable for the device in use, the payment form opens either in a modal window or in an iframe element \(if this has been specified via the corresponding parameter `target_element`\).

**Note:** If the request for opening the payment form contains the parameters to open Payment Page in a separate tab and in an iframe element, opening the form in a separate tab is given the priority.

Apart from these aspects, the calls to the `EPayWidget` object for opening the form in a separate tab must be made according to the following general conditions that are also relevant for other options to open the payment form:

1.  Each call can be made via one of the two methods:
    -   `bind` \(`EPayWidget.bind`\)—if the payment form should be opened with a button click \(with the button identifier `<pay_button_id>` specified\).
    -   `run` \(`EPayWidget.run`\)—if the payment form should be opened upon any other event in the user interface.
2.  Each call must contain the JavaScript object `configObj`with the parameters of the payment form opening and the signature for these parameters.

    The information about the parameters used and signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

3.  If necessary, any call can also contain an HTTP request method \(`method`\)—POST or GET. If nothing is specified, the GET method is used by default.
4.  Additionally, any call can contain functions for handling the information about the customer's actions.

    The information about such handler functions is provided in the article [Handling events in Payment Page](en_pp_ui_monitoring.md).


```language-javascript
EPayWidget.bind('<pay_button_id>', configObj, method);

EPayWidget.run(configObj, method);
```

```language-json
EPayWidget.bind('pay_button_id', // Button identifier
    { project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code 
      redirect_on_mobile: true, // Indicator for opening the form as a separate HTML page
                              // on mobile devices
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

```language-json
EPayWidget.run(
    { project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code 
      redirect_on_mobile: true, // Indicator for opening the form as a separate HTML page
                              // on mobile devices
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

When either of the methods \(`bind` and `run`\) is used, the HTML code of the web service page looks as follows.

```language-xml
<html>
<head>
<!-- Adding Ecommpay libraries -->
  <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css">
  <script src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
  <script type="text/javascript">var EP_HOST = 'https://paymentpage.ecommpay.com';</script>
<!-- Other parts -->
</head>
<body>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">
      EPayWidget.run({ project_id: 42,
                       customer_id: '17008',
                       payment_id: '18641868',
                       payment_amount: 8855,
                       payment_currency: 'USD',
                       redirect_on_mobile: true,
                       signature: 'YWb6Z20ByxpQ30hfTI' });
  </script>
  <!-- Other parts -->
</body>
</html>
```



---

# Opening Payment Page in a modal window {#en_PP_method_ModalWindow .concept}

An article about opening Payment Page in a modal window with the use of the JavaScript library from Ecommpay and in-house solutions.

**Parent topic:**[Options for opening Payment Page](en_PP_Integration.md)

## Overview {#en_pp_opening_modal_overview}

When opened in a modal window, the Payment Page payment form is displayed to the customer over the merchant's web service page.This interrupts the customer's interaction with the web service but keeps them engaged and focuses the customer's attention on the purchase without redirecting them to another page.

![](images/ecommpay/en_pp_general_2.svg)

For opening the payment form in a modal window, the following should be performed on the web service side:

1.  Link the CSS library from Ecommpay on the client side of the web service for the payment form to be displayed correctly. This library is available at `https://paymentpage.ecommpay.com/shared/merchant.css`.

2.  Configure the Content Security Policy by specifying the source URLs required for the correct operation of the payment form in the `Content-Security-Policy` HTTP header \([details](en_pp_interaction_organisation.md#section_jth_vnh_qjc)\).

    ``` {#codeblock_ejr_n4k_mjc}
    Content-Security-Policy:
    script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com;
    style-src https://paymentpage.ecommpay.com;
    img-src https://applepay.cdn-apple.com;
    frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com
    ```

3.  Define the events that will trigger the opening of the payment form\(for example, the purchase button click\).
4.  Set up the payment form to open upon the required eventsby using your in house-solutions or the JavaScript library from Ecommpay available at `https://paymentpage.ecommpay.com/shared/merchant.js`.

**Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS library via the CDN \(Content Delivery Network\). Storing this library locally is not allowed.

When processing Apple Pay payments via Payment Page with the option to open the payment form in a modal window, register your merchant domains with the Apple Pay service \([learn more](en_dbl_projects.md)\).

## Opening Payment Page via in-house solutions {#en_pp_opening_modal_via_in_house_solutions}

To open Payment Page in a modal window with the help of the merchant's in-house solutions, prepare the corresponding script that will ensure the payment form opening with the required parameters specified and signed. The information about the parameters that can be used to open Payment Page and about the signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

## Opening Payment Page via the Ecommpay JavaScript library {#en_pp_opening_modal_via_javascript_library}

To open Payment Page in a modal window with the help of the JavaScript library `merchant.js` from Ecommpay, link this library on the client side of the web service and use the corresponding calls to the `EPayWidget` object.

Since this option to open the payment form is the default one for the `merchant.js` library,no special parameters are required in the calls to the `EPayWidget` objectand complying with the following general conditionsis enough:

1.  Each call can be made via one of the two methods:
    -   `bind` \(`EPayWidget.bind`\)—if the payment form should be opened with a button click \(with the button identifier `<pay_button_id>` specified\).
    -   `run` \(`EPayWidget.run`\)—if the payment form should be opened upon any other event in the user interface.
2.  Each call must contain the JavaScript object `configObj`with the parameters of the payment form opening and the signature for these parameters.

    The information about the parameters used and signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

3.  If necessary, any call can also contain an HTTP request method \(`method`\)—POST or GET. If nothing is specified, the GET method is used by default.
4.  Additionally, any call can contain functions to handle the information about customer's actions.

    The information about such handler functions is provided in the article [Handling events in Payment Page](en_pp_ui_monitoring.md).


```language-javascript
EPayWidget.bind('<pay_button_id>', configObj, method);

EPayWidget.run(configObj, method);
```

```language-json
EPayWidget.bind('pay_button_id', // Button identifier
    { project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

```language-json
EPayWidget.run(    
    { project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

When either of the methods \(`bind` and `run`\) is used, the HTML code of the web service page looks as follows.

```language-xml
<html>
<head>
<!-- Adding Ecommpay libraries -->
  <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css">
  <script src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
  <script type="text/javascript">var EP_HOST = 'https://paymentpage.ecommpay.com';</script>
<!-- Other parts -->
</head>
<body>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">
      EPayWidget.run({ project_id: 42,
                       customer_id: '17008',
                       payment_id: '18641868',
                       payment_amount: 8855,
                       payment_currency: 'USD',
                       signature: 'YWb6Z20ByxpQ30hfTI' });
  </script>
  <!-- Other parts -->
</body>
</html>
```

## Customising the size of third-party services' pages {#en_pp_opening_modal_customisation}

When the payment form opens in a modal window and the customer is redirected to third-party services—such as the services of banks, payment systems, and providers—the window size is automatically adjusted to the size of the displayed pages. Along with that, it is possible to customise the size the services' pages for various cases \(with regard to the size of the screens of customers' devices, as well\) by specifying the desired dimensions. With such customisation, the pages of third-party services are displayed with the specified dimensions unless they are opened as separate HTML pages.

To set up the dimensions of the pages used for customer redirection to third-party services, the request for opening the payment form should contain the `payment_methods_options` parameter with the required values of height and width of such pages. These values are defined as `redirect_window_height` and `redirect_window_width`. These parameters can be specified as follows:

-   Directly in the `payment_methods_options` parameter, for all third-party services unless specified otherwise.
-   As the parameters for separate payment methods, which are specified via the codes \(from [the reference](en_pm_codes.md)\), according to the structure in the example that follows.

``` {#codeblock_wyz_vyr_pyb .language-json}
payment_methods_options:"{
    "redirect_window_height":1200,
    "redirect_window_width":1200,
    "card":\{"redirect\_window\_height":600, "redirect\_window\_width":900\},
    "neteller-wallet":\{"redirect\_window\_height":900, "redirect\_window\_width":1200\}
\}"
```

In the provided example, you can see the dimensions that should be used for all third-party services by default and the dimensions for separate payment methods. These dimensions are applied as follows:

-   For all methods except `card`and `neteller-wallet`, the height and width are 1200 pixels each.
-   For the `card` method, the height and width are 600 and 900 pixels accordingly.
-   For the `neteller-wallet` method, the height and width are 900 and 1200 accordingly.



---

# Opening Payment Page in an iframe element of an HTML page {#en_PP_method_Embedded .concept}

An article about opening Payment Page in an iframe element with the use of the JavaScript library from Ecommpay and in-house solutions.

**Parent topic:**[Options for opening Payment Page](en_PP_Integration.md)

## Overview {#en_pp_opening_iframe_overview}

When opened in an iframe element, the Payment Page payment form is embedded in the merchant's web service HTML page.This option may not necessarily focus the customer's attention on the purchase but keeps the customer in the context of the web service, without interrupting their interaction with it and redirecting them to a different page.

![](images/ecommpay/en_pp_general_1.svg)

**Note:** For the payment form to be displayed correctly, the minimum dimensions of the iframe element should be 320 and 600 pixels in width and height accordingly—if smaller dimensions are specified, the form does not fit into the element. For responsive display on desktop computers, the minimum width of the element should be 480 pixels. The restrictions on the maximum size are not imposed.

For opening the payment form in an iframe element, the following should be performed on the web service side:

1.  Link the CSS library from Ecommpay on the client side of the web service for the payment form to be displayed correctly. The library is available at `https://paymentpage.ecommpay.com/shared/merchant.css`.

2.  Configure the Content Security Policy by specifying the source URLs required for the correct operation of the payment form in the `Content-Security-Policy` HTTP header \([details](en_pp_interaction_organisation.md#section_jth_vnh_qjc)\).

    ``` {#codeblock_ejr_n4k_mjc}
    Content-Security-Policy:
    script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com;
    style-src https://paymentpage.ecommpay.com;
    img-src https://applepay.cdn-apple.com;
    frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com
    ```

3.  Define the events that will trigger the opening of the payment form\(for example, the purchase button click\).
4.  Set up the payment form to open upon the required eventsby using your in house-solutions or the JavaScript library from Ecommpay available at `https://paymentpage.ecommpay.com/shared/merchant.js`.

**Warning:** Keep in mind that to ensure correct behaviour of the payment form, you must link the Ecommpay CSS library via the CDN \(Content Delivery Network\). Storing this library locally is not allowed.

When processing Apple Pay payments via Payment Page with the option to open the payment form in an iframe element, register your merchant domains with the Apple Pay service \([learn more](en_dbl_projects.md)\).

## Opening Payment Page via in-house solutions {#en_pp_opening_iframe_via_in_house_solutions}

To open Payment Page in an iframe element with the help of the merchant's in-house solutions, prepare the corresponding script that will ensure the payment form opening with the required parameters specified and signed. The information about the parameters that can be used to open Payment Page and about the signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

## Opening Payment Page via the Ecommpay JavaScript library {#en_pp_opening_iframe_via_javascript_library}

To open Payment Page in an iframe element with the help of the JavaScript library `merchant.js` from Ecommpay, link this library on the client side of the web service and use the corresponding calls to the `EPayWidget` object.

In these calls, the identifier of the iframe element must be specified in the `target_element` parameter of the `configObj` object. Without this parameter, the payment form opens either in a modal window or as a separate HTML page \(if this has been set up via the `redirect` or `redirect_on_mobile` parameters\).

**Note:** If the request for opening the payment form contains the parameters to open Payment Page in a separate tab and in an iframe element, opening the form in a separate tab is given the priority.

Apart from these aspects, in case of opening the form in an iframe element via the `EPayWidget` object, the work with this object is carried out according to the following general conditions that are also relevant for other options to open the payment form:

1.  Each call can be made via one of the two methods:
    -   `bind` \(`EPayWidget.bind`\)—if the payment form should be opened with a button click \(with the button identifier `<pay_button_id>` specified\).
    -   `run` \(`EPayWidget.run`\)—if the payment form should be opened upon any other event in the user interface.
2.  Each call must contain the JavaScript object `configObj`with the parameters of the payment form opening and the signature for these parameters.

    The information about the parameters used and signature generation is provided in the following articles: [Payment Page API specification](en_PP_Parameters.md) and [Signature generation and verification](en_platform_signature.md).

3.  If necessary, any call can also contain an HTTP request method \(`method`\)—POST or GET. If nothing is specified, the GET method is used by default.
4.  Additionally, any call can contain functions to handle the information about customer's actions.

    The information about such handler functions is provided in the article [Handling events in Payment Page](en_pp_ui_monitoring.md).


```language-javascript
EPayWidget.bind('<pay_button_id>', configObj, method);

EPayWidget.run(configObj, method);
```

```language-json
EPayWidget.bind('pay_button_id', // Button identifier
    { target_element: 'widget-container', // Element identifier
      project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

```language-json
EPayWidget.run(    
    { target_element: 'widget-container', // Element identifier
      project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
```

When either of the methods \(`bind` and `run`\) is used, the HTML code of the web service page looks as follows.

```language-xml
<html>
<head>
<!-- Adding Ecommpay libraries -->
  <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css">
  <script src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
  <script type="text/javascript">var EP_HOST = 'https://paymentpage.ecommpay.com';</script>
<!-- Other parts -->
</head>
<body>
  <!-- HTML Web page code to add the Payment Page widget -->
  <div class="container">
      <div class="cart-info">...</div><div id="widget-container"></div>
  </div>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">
      EPayWidget.run({ target_element: 'widget-container',
                       project_id: 42,
                       customer_id: '17008',
                       payment_id: '18641868',
                       payment_amount: 8855,
                       payment_currency: 'USD',
                       signature: 'YWb6Z20ByxpQ30hfTI' });
 <!-- Other parts -->
 </script>
</body>
</html>
```

## Customising the size of third-party services' pages {#en_pp_opening_iframe_customisation}

To set up the dimensions of the pages used for customer redirection to third-party services, the request for opening the payment form should contain the `payment_methods_options` parameter with the required values of height and width of such pages. These values are defined as `redirect_window_height` and `redirect_window_width`. These parameters can be specified as follows:

-   Directly in the `payment_methods_options` parameter, for all third-party services unless specified otherwise.
-   As the parameters for separate payment methods, which are specified via the codes \(from [the reference](en_pm_codes.md)\), according to the structure in the example below.

Note that the specified parameters are not applied when the pages of third-party services are opened in separate tabs.

```language-json
payment_methods_options:"{
    "redirect_window_height":1200,
    "redirect_window_width":1200,
    "card":\{"redirect\_window\_height":600, "redirect\_window\_width":900\},
    "neteller-wallet":\{"redirect\_window\_height":900, "redirect\_window\_width":1200\}
\}"
```

In the provided example, you can see the dimensions that should be used for all third-party services by default and the dimensions for separate payment methods. These dimensions are applied as follows:

-   For all methods except `card`and `neteller-wallet`, the height and width are 1200 pixels each.
-   For the `card` method, the height and width are 600 and 900 pixels accordingly.
-   For the `neteller-wallet` method, the height and width are 900 and 1200 accordingly.



---

# Options for redirecting customers to third-party services {#en_PP_pm_redirect_mode}

An article about options for opening third-party auxiliary pages across different payment methods.

## Overview {#section_hhm_xvb_qkb .section}

During payment processing, customer redirection from the payment form pages to the services of third parties, such as banks, payment systems, and providers, can be required. This can be necessary for customer authentication, payment confirmation by customers, and other actions.Customer redirection can look as follows.

![](images/ecommpay/en_pp_pm_redirect_mode_1.svg "Automatic redirection")

![](images/ecommpay/en_pp_pm_redirect_mode_2.svg "Click redirection")

In the Ecommpay payment platform, various options for such redirections are supported: with the pages of the third-party services openedin an iframe object, in the current or in a new browser tab\(a new tab can be opened automatically or by the click of the button, with the forced redirection once the specified time period expires\).Depending on a payment methodand considering the special aspects of its use, one of these options is applied in the payment platform by default. At the same time, when setting up a method within a certain project, the merchant can coordinate the application of another option\(from the available ones\) with the technical support specialists. Finally, for individual payments, it is possible to select the option of redirection in a separate tab by using the parameters for opening Payment Page.

## Request format {#section_u3x_xxc_25b .section}

If for a separate payment, it is required to specify the option of opening the page of a third-party service in a new browser tab, disregarding the option specified for the method in general, the request should contain the boolean parameter `force_acs_new_window` with the value `1`.\(Using this parameter with the value `0` does not affect the redirection options.\)

In the following example of a request for purchase processing, the preselected method is Open Banking in Romania and the page of the bank Banca Comerciala Romana, which supports the purchase by using this method, is set to open in a separate tab.

```language-json
{
      payment_id: "X03936", 
      payment_amount: 1000, 
      payment_currency: "EUR", 
      project_id: 123,
      customer_id: "customer1",
      force_payment_method: "online-romanian-banks",
      payment_methods_option:
        {
            "online_romanian_banks":
                {
                    "banks_id": [55941]
                }
        },
      force_acs_new_window: 1,    // the option of opening the bank page      
      signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg=="
    }
```

```language-json
{
      payment_id: "X03936", 
      payment_amount: 1000, 
      payment_currency: "EUR", 
      project_id: 123,
      customer_id: "customer1",
      force_payment_method: "online-romanian-banks",
      payment_methods_option:
        {
            "online_romanian_banks":
                {
                    "banks_id": [55941]
                }
        },
      force_acs_new_window: 1,    // the option of opening the bank page      
      signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg=="
    }
```

## Related topics {#section_vvp_gyc_25b .section}

When working with various customer redirections, the following articles can come in handy:

-   [Options for redirecting customers to the web service](en_PP_redirect_modes.md)—with the information about customer redirections from the payment form pages to the web service.
-   [Methods](en_pm_about.md)—with the information about payment methods and the work with them.
-   [Payment Page API specification](en_PP_Parameters.md)—with the descriptions of parameters that can be used in requests for opening Payment Page.

**Parent topic:**[UX configuration](en_pp_ux_configuration.md)



---

# Options for redirecting customers to the web service {#en_PP_redirect_modes .concept}

An article about options for redirecting customers from the payment form to the web service using the specified URLs.

**Parent topic:**[UX configuration](en_pp_ux_configuration.md)

## Overview {#en_pp_redirect_modes_overview}

After the payment form opens, different variants of customer redirection to the web service can be relevant. Within the work with Payment Page, there are three such variants:

-   *preliminary redirection from the payment form*—when the customer needs to return to the web service before confirming the payment in the payment form; then the customer can go back to the form to continue working with it;
-   *intermediate redirection from third-party services*—when the customer needs to return to the web service after confirming the payment in the payment form and being redirected to a third-party service, without completing the required actions in that service;
-   *final redirection*—when the customer needs to return to the web service after performing all actions required for payment processing.

The merchant can provide customers with various capabilities for redirection\(using only the necessary variants or none of them\) and combine them with the payment form customised design \([details](en_PP__design_customisation.md)\) and with different options for opening web service pages when redirection to the web service is performed.This provides flexibility in adjusting to the nature of the business and various payment scenarios.

## Redirection options {#en_pp_redirect_modes_options}

### Preliminary redirection from the payment form {#en_pp_redirect_modes_before_payment}

#### Overview {#section_jl3_ksn_m5b .section}

Customer preliminary redirection to the web servicefrom the payment form pages is performed with the use of a link which is set up in the parameters of opening the form and is displayed as an additional element of the form.

![](images/ecommpay/en_pp_redirect_modes_1.svg)

If during Payment Page opening the capability of customer preliminary redirection from the payment form is set up, then the following options are applied for redirection by default:

-   If Payment Page opens in a separate browser tab, redirection is performed in the same tab.
-   If Payment Page opens in a modal window, this modal window closes.
-   If Payment Page opens in an iframe object, redirection is not performed, at the same time, interface events handling is available on the web service side \([details](en_pp_ui_monitoring.md)\).

In case if other redirection options are required, the corresponding parameters can be used on the web service side. These parameters are described in the section [Managing redirection availability and options](en_PP_redirect_modes.md) of this article.

When using the capability of redirecting customersfrom the payment form pages, also consider the following aspects:

-   The customer can return to the web service using the displayed link only before they confirm the payment in the payment form\(by choosing a method and specifying the required information\). After payment confirmation, the link is not displayed in the form, since the payment is then processed in the platform and the chosen payment system, and this payment processing can require customer's involvement.
-   If the time of working with the payment form is limited\([details](en_pp_time_limit.md)\), the countdown begins from the initial opening of the form and does not stop in case of redirection to the web service.

#### Request format {#section_ml3_ksn_m5b .section}

The URL for customer preliminary redirectionfrom the payment form pages to the web service is specified in the requests for opening Payment Page as the value of the `merchant_return_url` parameter.

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",
    
   // URL for preliminary redirection
   "merchant_return_url": "https://example.com", 

   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
}
```

### Intermediate redirection from third-party services {#en_pp_redirect_modes_intermediate}

#### Overview {#section_cyq_gvn_m5b .section}

Customer redirection to the web service from the pages of third-party services, such as banksor payment systems, is possible only when this redirection is supported by these services. Besides, such functionality can be implemented differently, depending on a service, and sometimes can include only one-way redirection \(that is, not providing customer's return to the third-party service page\). Considering these aspects and the potential negative impact they may have on payment acceptance, the implementation of customer redirection from the pages of third-party services should be discussed and coordinated with the Ecommpay account manager.

![](images/ecommpay/en_pp_redirect_modes_2.svg)

The URLs for intermediate customer redirection can be specified in the requests for opening Payment Page after the capability has been coordinated and set up.Otherwise, the URLs are ignored.

#### Request format {#section_dyq_gvn_m5b .section}

The URL for redirecting customers to the web servicefrom the pages of third-party services is specified in the requests for opening Payment Page as the value of the `redirect_return_url` parameter.

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

   // URL for intermediate redirection
   "redirect_return_url": "https://your/bank/example.com",

   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
}
```

### Final redirection {#en_pp_redirect_modes_final}

#### Overview {#section_lbc_qtr_stb .section}

During the work with Payment Page, final customer redirection to the web service—after payment processing—can be performed *by the customer's decision*, when the customer clicks the corresponding button on the final page of the payment form, and *automatically*, without the final page used and with the purchase result information displayed on the web service side. With automatic redirection, the capability of purchase retry attempts \([details](en_PP_Try_Again.md)\) cannot be provided to the customer.If you do not need to redirect the customer after payment processing, you can display the final page of the payment form without the button for redirection to the web service.

![](images/ecommpay/en_pp_redirect_modes_3.svg "Final redirection performed by the customer's decision")

![](images/ecommpay/en_pp_redirect_modes_4.svg "Final redirection performed automatically")

![](images/ecommpay/en_pp_redirect_modes_5.svg "Payment confirmation process without final redirection available")

The URLs and options for final customer redirection after payment processing can be specified for all payments within the project in general and individually for separate payments. General URLs and options should be specified via the Dashboard interface \(and the tools in the **Redirect URLs** tab of the **Projects** section\), individual URLs and options should be specified via the parameters of the requests for opening Payment Page \(these parameters are described further, in the [Request format](en_PP_redirect_modes.md#section_jcb_bqs_m5b) paragraph of this section and in the [Managing redirection availability and options](en_PP_redirect_modes.md) section of this article\).

With final redirection set up, the following redirection options are applied by default:

-   *Redirection by the customer's decision* is performed in the current browser tab, and if the payment form has been opened in a modal window, this window closes.
-   *Automatic redirection* is performed in the same interface element in which the payment form has been opened.That is, if the form has been opened in a separate browser tab, the redirection is performed in this tab, and if the form has been opened in a modal window or in an iframe object, the redirection is performed in this window or object.

#### Request format {#section_jcb_bqs_m5b .section}

*For redirection by the customer's decision*, the URLs can be specified as the values of the following parameters:

-   `merchant_success_url`—for customer redirection after the purchase has been completed,
-   `merchant_fail_url`—for customer redirection after the purchase has been declined.

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

   // URLs for final customer redirection performed by customer's decision
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_fail_url": "https://example.com/complete-redirect?id=decline", 
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
```

*For automatic redirection*, the URLs can be specified as the values of the following parameters:

-   `redirect_success_url`—for customer redirection after the purchase has been completed,
-   `redirect_fail_url`—for customer redirection after the purchase has been declined,
-   `redirect_tokenize_url`—for customer redirection after the payment data token has been generated in the `card_tokenize` mode \([details](en_pp_token.md)\).

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": "131970",
   "customer_id": "customer_12",

   // URLs for final customer redirection performed automatically
   "redirect_success_url": "https://example.com/complete-redirect?id=success", 
   "redirect_fail_url": "https://example.com/complete-redirect?id=decline", 
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
```

## Managing redirection availability and options {#en_pp_redirect_modes_opening_pages}

When preliminary and final customer redirections from the payment form to the web service are set up, you can manage the availability and options of these redirections for separate Payment Page openings. For this, the parameters of the `enabled` and `mode` groups are used.

-   `merchant_return_enabled`—the availability of preliminary redirection from the payment form pages,
-   `merchant_success_enabled`—the availability of final redirection after the purchase has been completed,
-   `merchant_fail_enabled`—the availability of final redirection after the purchase has been declined.

For each of these parameters, the following values can be used:

-   `0`—redirection is unavailable.
-   `1`—redirection is partially available; that is, if Payment Page is opened in an iframe object or a modal window, the customer is not redirected to the web service, and if Payment Page is opened in a separate browser tab, the option of opening the web service page is identified via the parameter of the `mode` group.
-   `2`—redirection is available, used by default, and compatible with the option of opening the web service page specified in the parameter of the `mode` group.

-   `merchant_return_redirect_mode`—the option for preliminary redirection from the payment form pages,
-   `merchant_success_redirect_mode`—the option for final redirection performed by the customer's decision after the purchase has been completed,
-   `merchant_fail_redirect_mode`—the option for final redirection performed by the customer's decision when the purchase has been declined,
-   `redirect_success_mode`—the option for final redirection performed automatically after the purchase has been completed,
-   `redirect_fail_mode`—the option for final redirection performed automatically after the purchase has been declined.

For each of these parameters, the following values can be used:

-   `iframe`—the page opens in an iframe object \(this works if the payment form is opened in an iframe object or a modal window; if the payment form is opened in a separate browser tab, the page opens in the same tab\).
-   `parent_page`—the page opens in the currently used tab.
-   `blank_page`—the page opens in a new tab.

The following examples contain the data from the requests for opening Payment Page according to which the customer redirection to the web service should be performed in different ways.

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

// URL of the web service page
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_success_redirect_mode": "blank_page",    // page opening option
   "merchant_success_enabled": 2,    // redirection availability
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
```

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

// URL of the web service page
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_success_redirect_mode": "parent_page",    //  page opening option
   "merchant_success_enabled": 1,    // redirection availability
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
```

The questions about working with these parameters as well as any other questions about the options for customer redirection to the web service can be directed to the Ecommpay technical support specialists.



---

# Basic actions {#en_pp_basic_actions}

Articles about the core actions that can be performed via the payment form, with the description of user scenarios and relevant request and callback formats for standard card payments.

The information about the basic actions that can be performed via the payment form, with the description of logical models, user scenarios, as well as the request and callback formats:

-   [Payment processing](en_platform_payment_model.md)—about the types of the payments that can be processed via Payment Page, payment workflows, as well as possible payment and operation statuses.
-   [Purchase processing](en_pp_purchase.md)—about processing purchases that result in immediate debiting of funds.
-   [Authorisation hold](en_pp_purchase_auth.md)—about placing a hold on funds within a two-step purchase.
-   [COF purchase registration](en_pp_recurring.md)—about registering purchases followed by a series of recurring debitis.
-   [Performing payouts](en_pp_payout.md)—about issuing payouts.
-   [Payment instrument verification](en_pp_account_verification.md)—about debiting of a zero amount or placing a hold on funds for validating the payment instrument.
-   [Tokenization](en_pp_token.md)—about opening the payment form for registering payment data and forming a token for this data.

-   **[Purchase processing](en_pp_purchase.md)**  
An article about processing via Payment Page one-time purchases with immediate debiting of funds.
-   **[Authorisation hold](en_pp_purchase_auth.md)**  
An article about placing a hold on funds via Payment Page as part of processing two-step purchases with subsequent debitings.
-   **[COF purchase registration](en_pp_recurring.md)**  
An article about registering via Payment Page purchases followed by a series of recurring debits.
-   **[Performing payouts](en_pp_payout.md)**  
An article about processing payouts via Payment Page.
-   **[Payment instrument verification](en_pp_account_verification.md)**  
An article about verifying a payment instrument via Payment Page by debiting a zero amount or placing a hold on funds.
-   **[Tokenization](en_pp_token.md)**  
An article about opening the payment form for registering payment data and generating a token for this data.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# Purchase processing {#en_pp_purchase}

An article about processing via Payment Page one-time purchases with immediate debiting of funds.

**Note:** This article covers processing one-time one-step purchases via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time one-step purchases:

-   [One-time one-step purchase](en_platform_sms_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing one-time one-step purchases in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing one-time one-step purchases via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

## General information {#section_adl_53h_2mb .section}

*One-step purchase*, or *one-time one-step purchase*, is a payment type which uses only one request to make a one-time transfer of funds from customer to merchant.

Payment Page allows you to process one-step purchases by using payment cardsor alternative payment instruments including MO/TO \(Mail Order/Telephone Order\) purchases in which user submits card details through mail, phone, or any other means of communication. When adding a new payment card for purchase processing, its payment data is saved and a token associated with this card is generated if this option is available in the merchant project \(for more details, see [Tokenization](en_pp_token.md)\). These operations are performed in the Purchase operation mode of the payment form.

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` parameter containing information about the start and end dates of the booked service \([details](en_pp_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

In terms of processing one-time one-step purchases using Payment Page, the basic steps that the customer performs may be selecting payment instrument, specifying its details and waiting for notification about the payment processing result.

![](images/ecommpay/en_pp_purchase_1.svg)

When processing one-time one-step purchases by using Payment Page, payment information can be specified as follows:

-   *On the payment form, by completing the fields.* In this case the customer completes all the fields on the payment form.

    In case of card payments, it is possible to make the field with the cardholder name optional instead of required. Note it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\).

-   *On the payment form, with an option to use saved payment information.* If the customer's identifier is specified in the request for opening Payment Page, the customer can either choose one of the saved payment instruments or enter new payment information; the new payment instrument can also be saved for subsequent purchases.

    In addition to selecting payment information, for some payment instruments entering verification code is required \(such as CVC, CVV or CID for card payments\).

-   *Outside the payment form, with an option to use saved payment information.* In this case the customer selects specific card in the web service, the token of this card is specified in the request for opening the payment form, and, when the payment form is opened, it already contains all required payment information, except for verification code \(CVC, CVV, CID\) which the customer is required to enter on the payment form.

![](images/ecommpay/en_pp_purchase_2.svg)

*Different options of specifying payment information on Payment Page: by completing the fields on the form, by selecting the saved payment instrument on the form and by selecting saved payment instrument before opening the payment form respectively.*

## Workflow {#section_bk5_1jh_2mb .section}

In terms of processing one-step purchases by using Payment Page, the merchant web service is required to do the following:

1.  Create and send a request for opening Payment Page to the payment platform.
2.  Receive callback with the result of the request processing from the payment platform.

One-step purchase processing may involve auxiliary procedures:

-   *3‑D Secure authentication*—the customer is forwarded to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed \(while issuer confirms authentication with no customer effort required\).
-   *Customer authentication on merchant's request*, in terms of which an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account. This type of authentication can be used instead of 3‑D Secure authentication or in addition to it.
-   *Submission of additional payment information*, in terms of which a notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when processing purchases by using payment cards. For more information about request and callback formats to use when processing purchases by using alternative payment methods, see [Methods](en_pm_about.md).

## Request format {#section_iqm_pxh_2mb .section}

The format of the request for opening Payment Page to process one-step payments using payment cards is the same as the request format described in the [Request format](en_pp_interaction_organisation.md) section. When creating request, you should consider the following:

1.  The request body must contain the following required parameters:
    -   `project_id`—the project ID obtained from Ecommpay.
    -   `payment_id`—the payment ID unique within the project.
    -   `customer_id`—the customer ID unique within the project.
    -   `payment_amount`—payment amount in minor currency units.
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format.
    -   `signature`—the signature that is created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
2.  When performing one-step purchase in a project that by default requires authorisation hold, you must additionally use the `operation_type`\([details](en_PP_Parameters.md)\) parameter set to `sale`; note that this parameter is not required in other operations.
3.  To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented \([details](en_PP_Gathering_customer_data.md)\), pass at least one of the following parameters in the request: `customer_email` or `customer_phone`.
4.  If you need to have the payment form displayed with the payment card selected, specify the `account_token` parameter in the request for opening the payment form. In this parameter you need to specify token of the payment card associated with the payment information of the card on the side of the payment platform.
5.  To display Payment Page in a required language, you need to additionally specify in the request the `language_code` parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default—[learn more](en_PP_WigetLanguages.md)\).
6.  To add description of the payment, you need to specify in the request the `payment_description` parameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard and in a callback with information about the payment result.
7.  To perform an MO \(Mail Order\) purchase, you must use the `moto_type` parameter set to `1`; for a TO \(Telephone Order\) purchase, you must add the `moto_type` parameter set to `2`.
8.  If needed, you can also add any other additional parameters supported by Payment Page in the Purchase operation mode. The full list of parameters for opening Payment Page is provided in the [Payment Page API specification](en_PP_Parameters.md) section.

Thus, a correct request for processing card payment must include project, customer and payment IDs, payment currency and amount and signature. Other parameters can also be specified in the request, but they are optional.

```language-json
{
   "project_id": "42",
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": "131970",
   "customer_id": "customer_12",
   "customer\_phone": "44991234567",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

// when processing payment using preselected card:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}

```

```language-json
https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&customer_id=customer_12&project_id=42&payment_amount=131970&payment_id=456789&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB...
```

## Callback format {#section_d42_ql3_2mb .section}

The format of the callback to notify the merchant about the result of processing one-step purchase is the same as the format described in the [Handling callbacks](en_platform_callbacks.md) section.

The following is an example of callback with an information about successful `1 319,70 USD` purchase made by the customer `customer_12` using the payment card with the card number `431422******0056` in the project `42`.

```language-json
{
    "account": {
        "number": "431422******0056 ",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2019-01-11T13:02:42+0000",
        "created_date": "2019-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2019-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

The following is the example of a callback with information about one-step purchase declined due to incorrect card data input.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "431422******0056 ",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 13300000004505,
        "type": "sale",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "created_date": "2019-01-11T14:11:00+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# Authorisation hold {#en_pp_purchase_auth}

An article about placing a hold on funds via Payment Page as part of processing two-step purchases with subsequent debitings.

**Note:** This article covers placing an authorisation hold via Payment Page as part of processing one-time two-step purchases and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time two-step purchases:

-   [One-time two-step purchase](en_platform_dms_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing one-time two-step purchases in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing one-time two-step purchases via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

## General information {#section_zsg_zr3_2mb .section}

*Two-step purchase*, or *one-time two-step purchase*, is a payment type which uses two steps to make a one-time transfer of funds from customer to merchant. On the first step, merchant initiates an authorisation hold—in other words, the purchase amount is deducted from the credit limit of customer's card account. On the second step, the purchase amount is “captured,” or, in other words, it is transferred to the merchant account based on the merchant request or after specific time lag.

**Note:** If the payment form is opened for initiating an authorisation hold \(with `auth` specified in the `operation_type` parameter\), the customer will be shown only those payment methods that support two-step purchases \([details](en_pm_about.md)\).

Payment Page allows you to apply authorisation hold which in fact is the first step of this purchase type; authorisation hold is also available for MO/TO \(Mail Order/Telephone Order\) purchases. To apply an authorisation hold, you use the Purchase operation mode.

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` parameter containing information about the start and end dates of the booked service \([details](en_pp_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

In terms of performing the first step of the one-time two-step purchase using Payment Page, the basic steps that the customer performs may be selecting payment instrument, specifying payment details and waiting for notification about payment processing result.

![](images/ecommpay/en_pp_purchase_auth_1.svg)

To perform the second step \(withdrawal or release of funds\), the merchant needs to use [Gate](en_gate_payment_auth.md)or [Dashboard](en_dbl_about.md) or configure automatic performance of this step after a specific time lag. In order to configure automatic withdrawal or release of funds, contact Ecommpay technical support \([support@ecommpay.com](mailto:support@ecommpay.com)\).

In terms of performing authorisation hold, payment information can be specified as follows:

-   *On the payment form, by completing the fields.* In this case the customer completes all the fields on the payment form.

    In case of card payments, it is possible to make the field with the cardholder name optional instead of required. Note it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\).

-   *On the payment form, with an option to use saved payment information.* If the customer's identifier is specified in the request for opening Payment Page, the customer can either choose one of the saved payment instruments or enter new payment information; the new payment instrument can also be saved for subsequent purchases.

    In addition to selecting payment instrument, for some payment instruments entering verification code is required \(such as CVC, CVV, or CID for card payments\).

-   *Outside the payment form, with an option to use saved payment information.* In this case the customer selects specific card in the web service, the token of this card is specified in the request for opening the payment form, and, when the payment form is opened, it already contains all required payment information, except for verification code \(CVC, CVV, CID\) which the customer is required to enter on the payment form.

![](images/ecommpay/en_pp_purchase_auth_2.svg)

*Different options of specifying payment information on Payment Page: by completing the fields on the form, by selecting the saved payment instrument on the form and by selecting saved payment instrument before opening the payment form respectively.*

## Time limit for authorisation hold {#section_hgy_djl_ylb .section}

According to the requirements of Visa, Mastercard, and American Express, the time lag for holding funds is limited. For different types of cards the maximum allowed time lag is defined according to the following terms:

-   Visa cards:
    1.  If authorisation hold is performed as a part of COF purchase processing, the maximum allowed time lag is 5 days.
    2.  If authorisation hold is performed not as a part of COF purchase processing or COF purchase registration, and the merchant's Merchant Category Code \(MCC\) corresponds to one of the numbers: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513, the maximum allowed time lag is 30 days.
    3.  In other cases the maximum allowed time lag is 10 days.
-   Maestro and Cirrus cards: the maximum allowed time lag is 6 days.
-   OtherMastercard cards: the maximum allowed time lag is 28 days.
-   American Express cards:
    1.  If merchant MCC is associated with hotel industry, car rental, or cruise lines the allowed time lag may extend to the entire duration of stay at a hotel, car rent duration or cruise duration, accordingly.
    2.  In other cases the maximum allowed time lag is 7 days.

The maximum allowed time lag for holding funds is calculated starting from the moment the `auth` operation is created in the Ecommpay payment platform. 30 minutes before the time lag expires, depending on the parameters specified by the Ecommpay employees, one of the following operations is performed automatically: a withdrawal \(`capture`\) or a release \(`cancel`\) of the held funds, after that a callback is sent to the web service. For more information and configuration of the operation type you can refer to your Ecommpay key account manager.There is an exception for American Express cards for which the maximum allowed time lag is limited by the entire duration of stay at a hotel, car rent duration or cruise duration—automatic withdrawal is not available for such cards.

If the time lag specified by the merchant for automatic withdrawal or release of funds exceeds the maximum allowed time lag, withdrawal or release of funds is performed according to the maximum allowed time lag.For instance, if the merchant configures automatic release of the held funds upon the expiration of 10 days and authorisation hold is performed by using Maestro card \(the maximum allowed time lag for Maestro card is 6 days\), automatic release of funds is performed upon the expiration of 6 days.

## Workflow {#section_msm_c1h_2mb .section}

In terms of authorisation hold by using Payment Page, the merchant web service is required to do the following:

1.  Create and send a request for opening Payment Page to the payment platform.
2.  Receive a callback with information about the result of the request processing from the payment platform.

Authorisation hold performing may involve additional procedures:

-   *3‑D Secure authentication*, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed \(while issuer confirms authentication with no customer effort required\).
-   *Customer authentication on merchant's request*, in terms of which an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account. This type of authentication can be used instead of 3‑D Secure authentication or in addition to it.
-   *Submission of additional payment information*, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

The following sections cover information about request and callback formats to use when performing authorisation hold using payment cards. For information about request and notification formats when performing authorisation hold using alternative payment methods, see [Methods](en_pm_about.md).

## Request format {#section_pyb_xph_2mb .section}

The format of the request for opening Payment Page to perform authorisation hold is the same as the request format described in the [Request format](en_pp_interaction_organisation.md) section. When creating request, you should consider the following:

1.  The request must contain the following required parameters:
    -   `operation_type`—operation type for payment processing\([details](en_PP_Parameters.md)\). The parameter value must be set to *auth*, if purchases for the project are enabled by merchant request.
    -   `project_id`—the project ID obtained from Ecommpay.
    -   `payment_id`—the payment ID unique within the project.
    -   `payment_amount`—payment amount in minor currency units.
    -   `payment_currency`—payment currency code according to ISO-4217 alpha-3.
    -   `customer_id`—the customer ID unique within the project.
    -   `signature`—the signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
2.  To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented \([details](en_PP_Gathering_customer_data.md)\), pass at least one of the following parameters in the request: `customer_email` or `customer_phone`.
3.  If you need to have the payment form displayed with the payment card selected, specify the `account_token` parameter in the request for opening the payment form. In this parameter you need to specify token of the payment card associated with the payment information of the card on the side of the payment platform.
4.  To display Payment Page in a required language, you need to additionally specify in the request the `language_code` parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default—[learn more](en_PP_WigetLanguages.md)\).
5.  To add description of the payment, you need to specify in the request the `paymentDescription`parameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard and in a callback with information about the payment result.
6.  To perform an MO \(Mail Order\) purchase, you must use the `moto_type` parameter set to `1`; for a TO \(Telephone Order\) purchase, add the `moto_type` parameter set to `2`.
7.  If needed, you can also add any other additional parameters supported by Payment Page in the Purchase operation mode. The full list of parameters for opening Payment Page is provided in the [Payment Page API specification](en_PP_Parameters.md) section.

Thus, a correct payment request must include project, customer and payment IDs, language code, currency and the amount of a payment in the appropriate currency, the `auth` operation type and signature. Other parameters can also be specified in the request, but they are optional.

```language-json
{
   "operation_type": "auth",
   "project_id": 42,
   "payment_id": "456789",
   "customer_id": "customer_12",
   "payment_currency": "USD",
   "payment_amount": "2000",
   "customer\_phone": "44991234567",
   "signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF...",

// when processing payment using preselected card:
    "account_token":"959c664ad64b8caa54bb7836ddc737fd1a679242a039..."

}

```

```language-json
https://https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&project_id=42&payment_amount=2000&payment_id=456789&operation_type=auth&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhZLxEzkgcoZr...
```

## Callback format {#section_j4p_lh3_2mb .section}

The format of the callback to notify the merchant about the result of performing authorisation hold is the same as the format described in the [Handling callbacks](en_platform_callbacks.md) section.

The following is an example of callback with an information about successful authorisation hold of `2 000,00 USD` made for the customer `customer_12` using the payment card with the card number `541333******0019` in terms of the project `42`.

```language-json
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2019-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 2777000002350,
        "type": "auth",
        "status": "success",
        "date": "2020-01-11T13:00:40+0000",
        "created_date": "2020-01-11T13:00:37+0000",
        "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "224750650",
            "date": "2020-01-11T13:00:39+0000",
            "result_code": "000",
            "result_message": "Approved",
            "auth_code": "505050",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success",
        "description": "SUCCESS",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

The following is the example of a callback with information about authorisation hold declined due to incorrect input of the expiration date of the payment card.

```language-json
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2020-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 6304000002973,
        "type": "auth",
        "status": "decline",
        "date": "2020-01-11T13:00:40+0000",
        "created_date": "2019-01-11T13:00:34+0000",
        "request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239689120",
            "date": "2020-01-11T13:00:36+0000",
            "result_code": "101",
            "result_message": "Decline, expired card",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "10106",
        "message": "Card expired",
        "description": "Bank cards. Operation was declined due to incorrect card expiry date entry",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

The following is an example of callback with an information about withdrawal of the held `2 000,00 USD` from the payment card with the card number `541333******0019` of the customer `customer_12` in terms of the project `42`.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 7178000006597,
        "type": "capture",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2020-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

The following is an example of callback with an information about cancelling authorisation hold of `2 000,00 USD` for the payment card with the card number `541333******0019` of the customer `customer_12` in terms of the project `42`.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "canceled",
        "date": "2020-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 18289000007021,
        "type": "cancel",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2020-01-11T15:54:40+0000",
        "request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239672146",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

The following is the example of a callback with information about authorisation hold declined due to incorrect card data input.

```language-json
 {
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2020-01-11T15:54:40+0000",
        "id": "456789",
        "method": "card",
        "status": "decline",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 18397000002376,
        "type": "cancel",
        "status": "decline",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2020-01-11T15:54:35+0000",
        "request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "248013808",
            "date": "2020-01-10T22:37:10+0000",
            "auth_code": "876856",
            "endpoint_id": 120
        },
        "code": "10102",
        "message": "Incorrect data entered"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
```

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# COF purchase registration {#en_pp_recurring}

An article about registering via Payment Page purchases followed by a series of recurring debits.

**Note:** This article that covers registering COF purchases via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing COF purchases:

-   articles [On-demand COF purchase](en_platform_recurring_model.md) and [COF purchase with automatic debiting](en_platform_sheduled_recurring_model.md) in the section [Payment processing](en_platform_payment_model.md) that provide a general description of processing COF purchases in the Ecommpay payment platform and cover information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of COF purchase registration via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

## General information {#section_bcf_1x3_2mb .section}

The Ecommpay payment platform allows you to register COF purchases in a variety of ways by processing payments via Payment Page, Gate \([details](en_gate_payment_recurring_registration.md)\), and Dashboard \([details](en_dbl_payments.md)\)as well as by migrating information about COF purchases and payment card tokens \([details](en_gate_data_migration.md)\). This article covers information about registering COF purchases via Payment Page by performing one-time purchases and payment instrument verification.

*Recurring purchase* is a payment type which uses only one request to make one \(recurring\) transfer of funds from customer to merchant. Recurring payments are processed by using previously stored payment credentials with no need for validation of the payment instrument \(such as card validation code, or CVC\).

Support for COF purchases processing may be convenient when building lasting customer relationships when you would like to offer your customers an option to make purchases with no extra effort on their side.

**Note:** If the payment form is opened for registering a COF purchase, the customer is shown only the payment methods that support registration of COF purchases \([details](en_pm_about.md)\).

In terms of processing COF purchase registration using Payment Page, the basic steps that the customer performs may be selecting payment instrument, specifying its details and waiting for notification about the payment processing result.

![](images/ecommpay/en_pp_recurring.svg)

The payment platform supports the following COF purchase types:

-   *OneClick purchases* are initiated by the customer and do not depend on any schedule or predetermined payment amount. For instance, the customer can make a one-click purchase in order to watch a movie online.
-   *Autopurchases* are initiated by merchant and do not depend on any schedule or predetermined payment amount. For example, when customer's mobile phone account balance falls below specific threshold, merchant may automatically top up the account.
-   *Regular purchases* are initiated by the merchant and are based on specific schedule and fixed amount. The schedule may be stored either on the payment platform side or in your web service. For instance, weekly payment for online subscription may be regularly debited to customer's account.

Registration of any type of COF purchase requires customer's consent for storage of their payment information and its usage on certain terms.

COF purchase is registered by using the Purchase and Card Verify operation modes. To initiate COF purchase processing, change its terms, cancel it, or to issue a refund, the merchant can use [Gate](en_Gate__payments_on_saved_data.md) \(for all types of COF purchases\) and [Dashboard](en_dbl_payments.md) \(for regular COF purchases\).

If there are changes in the payment provider's service settings, you may need to register COF purchase again. In such cases, the merchant receives an email from the Ecommpay technical support with a list of IDs of COF purchases that should be re-registered. For this registration, merchant must notify customers of the termination of previous debits and the need to initiate new ones by unlinking the saved card, and then initiate registration in the platform. Each newly registered COF purchase receives a new ID, which is sent to the merchant in the callback with information on successful registration.

## Workflow {#section_mgc_c2j_2mb .section}

COF purchase registration by using Payment Page requires the merchant web service to do the following:

1.  Create and send a request for opening Payment Page to the payment platform.
2.  Receive callback with the result of the request processing from the payment platform.

COF purchase registration may involve auxiliary procedures:

-   *3‑D Secure authentication*, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed \(while issuer confirms authentication with no user input required\).
-   *Customer authentication on merchant's request*, in terms of which an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account. This type of authentication can be used instead of 3‑D Secure authentication or in addition to it.
-   *Submission of additional payment information*, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when registering COF purchases by using payment cards.For more information about request and callback formats to use when registering COF purchases by using alternative payment methods, see [Methods](en_pm_about.md).

## Request format {#section_hh4_ffj_2mb .section}

The format of the request for opening Payment Page to register COF purchases is the same as the format described in the [Request format](en_pp_interaction_organisation.md). When creating request, you should consider the following:

1.  The basic minimum of parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay
    -   `payment_id`—payment identifier unique within the project
    -   `customer_id`—customer identifier unique within the project
    -   `payment_amount`—payment amount in the smallest currency unit \(to register COF purchases in terms of payment instrument verification, you need to specify the `0` value\)
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `signature`—request signature generated after all required parameters were specified \(for more information, see the section [Signature generation and verification](en_platform_signature.md)\)
2.  For registering a COF purchase along with payment instrument verification, the `mode` parameter should be additionally specified. This parameter indicates the Payment Page operation mode and should have the `card_verify` value.
3.  For specifying the properties of a COF purchase, the request should contain the `recurring` parameter as a JSON object—if the payment form is opened via the JavaScript library of Ecommpay—or as a string generated as a result of URL encoding—if the payment form is opened via another method. The `recurring` parameter must contain the main details about COF purchase registration:
    -   `register`, boolean—indicator that specifies whether a COF purchase should be registered.
    -   `type`, string—type of the COF purchase to register, possible values:
        -   `C`—one-click purchase
        -   `U`—autopurchase
        -   `R`—regular purchase
    -   `period`, string—frequency of debits \(for a regular COF purchase\), possible values:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
        -   `Q`—quarterly
        -   `Y`—annually
    -   `time`, string—time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.
    -   `interval`, integer—multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter and should be assigned a numeric value from `1` to `100`.
4.  For specifying the properties of a regular purchase, the `recurring` parameter can also contain other details:
    -   `amount`, integer—fixed amount of subsequent debits in the smallest currency unit.
    -   `start_date`, string—date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.
    -   `expiry_day`, integer orstring—calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_month`, integer orstring—month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_year`, integer—year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).

        **Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

        -   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
        -   For other available methods—the corresponding parameter value is determined as follows:
            -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
            -   Month—the month in which the COF purchase was registered.
            -   Year—the year that is 10 years after the year in which the COF purchase was registered.
        Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

    -   `scheduled_payment_id`, string—identifier assigned to the payment within which scheduled debits are performed. It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project. Also, not to be confused with the debiting series record identifier specified in the `id` parameter of the `recurring` object that is passed in the callback with the COF purchase registration information.

        **Warning:** If the identifier that should be assigned to the COF purchase \(`scheduled_payment_id`\) matches the identifier of the payment made to register a COF purchase \(`payment_id`\), the request to register a COF purchase is declined.

5.  To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented \([details](en_PP_Gathering_customer_data.md)\), pass at least one of the following parameters in the request: `customer_email` or `customer_phone`.
6.  For displaying the payment form to the customer in a specified language, the `language_code` parameter should be used with the language code specified in the ISO 639-1 alpha-2 format. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default—[learn more](en_PP_WigetLanguages.md)\).
7.  For adding a payment description, the `payment_description` parameter can be used. The value of this parameter is a string displayed to the customer on the page with the information about the operation result and to the merchant in the Dashboard interface and sent to the merchant in the callback with information about the payment result.
8.  Additionally, it is possible to use any other parameters available for the Purchase and Card Verify modes of the Payment Page operation. The full list of parameters for opening Payment Page is provided in the [Payment Page API specification](en_PP_Parameters.md) section.

Thus, a request for COF purchases registration must include:

-   in terms of payment instrument verification—parameters for opening Payment Page for payment instrument verification and the `recurring` parameter with information about COF purchase registration.
-   in terms of purchase processing—parameters for opening Payment Page for processing a purchase and the `recurring` parameter with information about COF purchase registration.

``` {#codeblock_d5j_vjb_d2c .language-json}
{
    "register": true,     //COF purchase registration
    "type": "R",          //regular purchase registrartion
    "amount": 400,
    "expiry_day": 1,
    "expiry_month": 8,
    "expiry_year": 2025,  //last payment is scheduled for August 1, 2025
    "interval": 10,
    "period": "D",        //debiting every 10 days
    "time": "10:00:00",   //debiting at 10:00:00
    "start_date": "14-05-2019",
    "scheduled_payment_id": "A2323"
}
```

``` {#codeblock_kcs_vjb_d2c}
"recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22
                 expiry_day%22%3A1%2C%22expiry_month%22%3A8%2C%22expiry_year%
                 22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%
                 22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%
                 22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D"
```

```
EPayWidget.run(
    { payment_id: '567890',
      payment_amount: '400',
      customer_id: 'customer1',
      customer\_phone: '44991234567',
      payment_currency: 'USD',
      project_id: 42,
      force_payment_method: 'card',
      recurring: '{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}',
      signature: 'qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...' },
    'post')
```

```language-json
https://paymentpage.ecommpay.com/payment?signature=qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...&payment_id=567890&payment_amount=400&payment_currency=USD&project_id=42&customer_id=customer_1&customer_phone=44991234567&force_payment_method=card&recurring=%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry\_day%22%3A1%2C%22expiry\_month%22%3A8%2C%22expiry_year%22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D
```

## Callback formats {#section_ys1_njj_2mb .section}

The format of the callback to notify the merchant about the result of purchase processing or payment instrument verification with COF purchase registration is the same as the format described in the [Handling callbacks](en_platform_callbacks.md) section.

The following is an example of a callback with information about successful registration of COF purchase using the card `431422******0056`; COF purchase is registered for the customer `customer_10` in terms of the project `42`.

```language-json
{  
  "project_id": 42,
  "payment":{  
    "id": "567890",
    "type": "purchase",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "method": "card",
    "sum":{  
      "amount": 400,
      "currency": "USD"
    },
    "description": ""
  },
  "account":{  
    "number": "431422******0056",
    "token": "d927d3f006008edf5c07661",
    "type": "visa",
    "card_holder": "JUDY DOE",
    "expiry_month": "08",
    "expiry_year": "2025"
  },
  "customer":{  
    "id": "customer_1"
  },
  "recurring":{  
    "id": 1001648059,    // ID of the record about a range of withdrawals
    "currency": "USD",
    "valid_thru": "2019-05-20T00:00:00+0000"
  },
  "scheme\_id":"MCS38A0790706",
  "operation":{
    "id": 22136002040,
    "type": "sale",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "created_date": "2019-05-14T12:52:42+0000",
    "request_id": "8c77279053d011-1160421d51e11f87d2c",
    "sum_initial":{  
      "amount": 400,
      "currency": "USD"
    },
    "sum_converted":{  
      "amount": 400,
      "currency": "USD"
    },
    "provider":{  
      "id": 414,
      "payment_id": "00200011764",
      "date": "2019-05-14T12:52:55+0000",
      "auth_code": "231567",
      "endpoint_id": 414
    },
    "code": "0",
    "message": "Success",
    "eci": "07"
  },
  "signature": "v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm..."
}
```

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# Performing payouts {#en_pp_payout}

An article about processing payouts via Payment Page.

## Overview {#section_l4s_bhz_dbc .section}

The Ecommpay payment platform supports the capability to issue payouts to card accounts with the use of Payment Page. Each payout is at first registered via the Gate API and then the payment form is opened in the Payout operation mode.Along with that, payouts via Payment Page can originate both from the merchant and from a physical person, while their processing can involve Mastercard MoneySend and Visa Direct services.

**Note:** Performing payouts is available only for the 5th generation Payment Page.

To register a payout, send a corresponding request to the platform via the Gate API and receive a callback about the registration result.If the payout has been registered, the callback contains a special identifier \(`uuid`\) that must be specified in the request for opening Payment Page. Keep in mind that this identifier is valid for 30 minutes and the time that remains for confirming the payout is displayed on the payment form pages. In case if the customer does not confirm the payout until the allocated time expires, a corresponding notification is displayed to this customer and, for the payout to be processed, it has to be re-registeredwith a new payment identifier \(`payment_id`\) specified.

A payout via Payment Page is made upon the customer's confirmation with the use of a confirmation code. Such codes are sent from the payment platform to the customer's email address provided during the payout registration.

![](images/ecommpay/en_pp_payout_code.svg "Example of an email with a confirmation code")

When the customer requests a payout with the use of Payment Page, they select a payment instrument, specify the instrument credentials, then enter the confirmation code, and receive a notification about the result. The payment instrument credentials can be specified in one of the following ways:

-   *On the payment form, by completing the fields.*In this case, the customer completes all required fields on the payment form.
-   *On the payment form, by completing the fields or selecting saved payment information.*In this case, the customer can either select one of the saved payment instruments or enter new payment information. The new payment instrument can also be saved for subsequent payment processing.
-   *Outside the payment form, by selecting previously saved payment information.*In this case, the customer selects a specific card in the web service, the token associated with this card is specified in the request for opening Payment Page, and once the payment form is opened, it already contains all required payment information.

Payout processing can be finalised with the generation of payment card tokens. It is applicable when card details have not been saved before, and this capability has been set up for the merchant's project in use \([details](en_pp_token.md)\).

## Customer payout scenario {#section_rxt_bhz_dbc .section}

Suppose that the customer Prostetnik Jeltz has won the third place in the Millstone Jennings Poetry competition with the prize of 70 EUR.To receive the funds, the customer specifies their payment instrument details, first name, and last name, then confirms the payout and waits for its result.

![](images/ecommpay/en_pp_payout_1.svg "Specifying payment data")

![](images/ecommpay/en_pp_payout_2.svg "Entering a confirmation code")

## Restrictions {#section_jt5_bhz_dbc .section}

The following restrictions apply to processing payouts via Payment Page:

-   You have to make sure that this capability has been added and set up for the project in use.

    When the payment form is opened in the Payout operation mode within the project without the integrated payouts functionality, a callback with the `317` error code is sent from the payment platform to the web service \([details](en_platform_payment_info_codes.md)\).

-   To send requests for payouts registration, use the IP addresses that you provided to the Ecommpay technical support specialists who subsequently added them to the whitelist.

    If a request is sent from an IP address that is not whitelisted, a response with the `403` error code is sent from the payment platform to the web service \([details](en_gate_interaction_organisation.md)\).

-   The limits set for the payout recipient's payment card must be complied with. These limits include the number of payouts, their amount in total, and the amount of a one-time transfer of funds.

    If any of these limits is exceeded, the payout is declined, the customer is shown a page with the message that the payment has been declined, and a callback with the relevant error code is sent to the web service.

-   The merchant's account balance must contain enough funds for issuing a payout.

    If there are insufficient funds, the payout is declined, the customer is shown a page with the message that the payment has been declined, and a callback with the relevant error code is sent to the web service. Balance information can be monitored via Dashboard \([details](en_dbl_balances.md)\) and retrieved via the Data API \([details](en_dbl_api_protocol.md)\). If you have any questions, contact your Ecommpay account manager.

-   You must comply with requirements imposed by global card networks and programs within which payouts are issued as well as requirements and rules that are specific to particular regions, payment systems, and providers.

    Depending on the program, for example, there are different requirements as to what information about the payout sender or recipient should be provided in the requests for opening Payment Page.

    **Note:**

    These requirements may have to do with such cases as follows:

    -   For payouts performed as part of the Mastercard MoneySend service when the payout sender is a physical person, it is required that the first name and the last name of the payout recipient as well as the first name and the last name, the payment instrument identifier and the address of the payout sender are specified—if this data is not specified, the payout is declined.
    -   For payouts performed as part of the Visa Direct Money Transfer program, in case of a payout to a card issued in Canada, it is required that the payout recipient's address is specified—if this data is not specified, an additional page with fields to fill in with the details is displayed to the customer.
    For more in-depth understanding of performing payouts depending on different conditions, refer to your account manager.

-   When opening the payment form, the capability of limiting the time for working with it must not be used \([details](en_pp_time_limit.md)\). The time of working with the payment form is limited by default and equals the validity period of the `uuid` identifier.

    If the request for opening the payment form contains the date and time limiting the work with the form, the customer is shown the payment form page with the error message.


## Setup {#section_emv_bhz_dbc .section}

To have the capability of processing payouts with the use of Payment Page set up, merchants should complete the following steps:

1.  Discuss with the Ecommpay account manager and agree on the capability setup steps, the need for testing the capability, and the application of restrictions in each particular case.
2.  If it was agreed that testing is required, wait to be notified by the Ecommpay specialists when the functionality is ready, then test the payment form workflow with the new capability. After that, inform the account manager that you are ready to launch the functionality in your production environment.
3.  Receive a notification about the completion of the capability setup from the Ecommpay specialists.

## Workflow {#section_w2w_bhz_dbc .section}

To perform a payout via Payment Page, the web service is required to do the following:

1.  Generate the request for registering a payout and send it to the payment platform.
2.  Receive a callback with information about payout registration from the platform.
3.  Generate and send a request for opening Payment Page in the Payout operation mode.
4.  Receive a callback with information about the payment processing result from the payment platform.

It may be needed to carry out an additional procedure of the *payment information submission* when processing payouts.The customer will be shown a message and additional fields to be completed on the payment form. This procedure is performed without the merchant's web service involved, but it does require the participation of the customer.

![UML-scheme](images/ecommpay/en_payout_pp_uml.svg)

1.  A customer initiates a payout in the web service.
2.  The web service sends the request for payout registration by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity\([details](en_gate_interaction_organisation.md)\).
6.  The request is processed on the payment platform side.
7.  The payment platform sends the callback with the payout identifier\(`uuid`\) to the web service.
8.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
9.  The request for opening Payment Page is sent to the payment platform.
10. The payment platform receives the requestand validates the required parameters and signature.
11. Payment Page is generatedbased on the project and request parameters.
12. Payment Pagewith an indicator that shows the time remaining for working with the form is displayed to the customer.
13. The customer performs required actions and confirms the payout.
14. The payment platform receives the request for processing the payout.
15. The payment platform processes the request and sends it to the payment environment.
16. The request is processed on the payment environment side.
17. The payment environment sends the payout result information to the payment platform.
18. The payment platform sends a callback with the payout result information to the web service.
19. The payment platform sends the information about the payout result to Payment Page.
20. The payout result information is displayed to the customer on Payment Page.

## Format of request for payout registration {#section_bxw_bhz_dbc .section}

There are several things you should consider when sending a request for payout registration:

1.  In every case of payout registration, send a separate POST request to the  endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general identification information of the request:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer's identifierunique within the project
        -   `email`—customer's email address
        -   `phone`—customer's phone number
        -   `ip_address`—customer's IP addressrelevant for the payout being registered

Thus, a correct request for payout registration must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

```language-json

  "general": {
    "project_id": 91348,
    "payment_id": "cosmoshop_payout_1323",
    "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer": {
    "id": "16061314",
    "email": "p.jeltz@mail.com",
    "phone": "44991234567",   
    "ip_address": "93.47.230.225"
  },
  "payment": {
    "amount": 7000,
    "currency": "EUR"
  }
}
```

## Format of callback with the payout registration result {#section_a1k_dhz_dbc .section}

During the processing of a payout with the use of Payment Page, on the web service side it is required to receive an intermediate callback with information about the payout registration result from the payment platform and use the identifier submitted in the `uuid` parameter. The format of such callbacks is standard \([details](en_platform_callbacks.md)\).

The following is an example of a callback indicating that a payout has been registered in the `91348` project for the `16061314` customer.

```language-json

{
    "general": {
        "project_id": "91348",
        "payment_id": "cosmoshop_payout_1323",
        "signature": "V2mxcUcGUcCtAE51lgesBefZgfG9NHpQEbfdI2X1Q=="
    },
    "request_id": "50715",
    "payment": {
        "id": "cosmoshop_payout_1323",
        "type": "payout",
        "status": "awaiting_payout_completion",
     },
    "operation": {
        "id": "500359719",
        "type": "payout",
        "status": "awaiting_payout_completion"
    },
    "customer": {
        "id": "16061314"
    },
    "sum_request":
    {
        "amount": "7000",
        "currency": "EUR"
    },
    "transaction": {
        "type": "payout"
    },
    "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==",
    "uuid_expired_at": "2024-04-24T13:50:37+0000"
}
```

## Format of request for opening the payment form {#section_umk_dhz_dbc .section}

The format of request for opening Payment Page to process card payouts is the same as the one described in the [Interaction concepts](en_pp_interaction_organisation.md) section. When generating such requests, you should consider the following:

1.  The following parameters must be specified in the request:
    -   `mode`—the indicator of the Payment Page operation mode. The value must be `payout`.
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier specified in the request for payout registration and unique within the project

        **Warning:** Payment identifiers \(`payment_id`\) specified in the request for payout registration and the request for opening the payment form must match. If the identifiers do not match, the payment form will not open and the customer will be shown an error message.

    -   `uuid`—payout identifier received in a callback with information about the payout registration result
    -   `customer_id`—customer's identifier specified in the request for payout registration and unique within the project
    -   `customer_email`—customer's email address specified in the request for payout registration
    -   `payment_amount`—payment amount specified in the request for payout registration, in the smallest currency unit
    -   `payment_currency`—payment currency code specified in the request for payout registration, in the ISO-4217 alpha-3 format
    -   `signature`— the request signature generated after all required parameters have been specified \(for more information, see [Signature generation and verification](en_platform_signature.md)\).
2.  To use a token of the payment card that the customer has selected in the web service, specify this token as a value of the `account_token` parameter.
3.  To provide information about the payout sender, specify the following parameters in the request:
    -   `sender_wallet_id`—sender's wallet number
    -   `sender_first_name`—sender's first name
    -   `sender_last_name`—sender's last name
    -   `sender_country`—sender's country code in ISO 3166-1 alpha-2
    -   `sender_state`—the sender's country subdivision code \(state, province, region, or territory\). The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. For example, `ON` for the province of Ontario in Canada \(with `CA-ON` being the complete code for the subdivision\)
    -   `sender_city`—sender's city
    -   `sender_address`—sender's street address
    -   `sender_zip`—sender’s postal code
4.  To provide information about the payout recipient, specify the following parameters in the request:

    -   `recipient_first_name`—recipient's first name
    -   `recipient_last_name`—recipient's last name
    -   `recipient_country`—recipient's country code in ISO 3166-1 alpha-2
    -   `recipient_state`—the recipient’s country subdivision code \(state, province, region, or territory\). The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. For example, `ON` for the province of Ontario in Canada \(with `CA-ON` being the complete code for the subdivision\)
    -   `recipient_city`—recipient's city
    -   `recipient_address`—recipient's street address
    In the case of payout to a Visa card issued in Canada, the request must contain the payout recipient's address data: the country code \(`recipient_country`\), the city \(`recipient_city`\), the street address \(`recipient_address`\) and, if the recipient's country code is [CA](references/en/countries/CA.md) or [US](references/en/countries/US.md), the code of the state, province, or territory \(`recipient_state`\).

5.  To display Payment Page in a required language, you need to additionally specify the `language_code` parameter. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser settings or by default—[details](en_PP_WigetLanguages.md)\).
6.  To add a description of the payment, you need to specify the `payment_description` parameter. The value of this parameter is shown to the customer on the page with information about the payout result and is available to the merchant's employees in Dashboard and in callbacks.
7.  Additionally, any other parameters supported by Payment Page in the Payout operation mode can be used in requests. The full list of parameters for opening Payment Page is provided in the article [Payment Page API specification](en_PP_Parameters.md).

Thus, a correct request for payout must include project, payment, and customer identifiers, the identifier from the callback with information about the payout registration, the email address of the customer, signature, payment currency and amount. Along with that, other parameters can be used in requests.

```language-json
{
   "project_id": "91348",
   "payment_id": "cosmoshop_payout_1323",
   "payment_currency": "EUR",
   "payment_amount": "7000",
   "customer_id": "16061314",
   "customer_email": "p.jeltz@mail.com",  
   "mode": "payout",
   "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5...",
   "signature": "xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB..."

// when processing payment using preselected card:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}

```

## Format of callback of payout processing result {#section_d21_b4z_dbc .section}

The format of callbacks used to communicate the results of processing card payouts is the same as the one described in the [Handling callbacks](en_platform_callbacks.md) section.

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# Payment instrument verification {#en_pp_account_verification}

An article about verifying a payment instrument via Payment Page by debiting a zero amount or placing a hold on funds.

**Note:** This article covers payment instrument verification via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of payment instrument verification:

-   [Payment instrument verification](en_platform_account_verification_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of performing payment instrument verification in the Ecommpay payment platform and covers information about statuses that can be used in the process.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of payment instrument verification via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

To find out whether you can use payment instrument verification, refer to your Ecommpay account manager.

## General information {#section_w3f_5qf_dmb .section}

*Payment instrument verification* is a payment type in which the customer card or account is validated by either transferring a dummy \(zero\) amount from customer to merchant or by authorizing a specific amount \(non-zero\) on the customer cardor account and then voiding the transfer or the authorization. Authorization amount can be changed on merchant's request. The authorized amount can be held up to 45 days. This option may be convenient for validating a payment instrument without withdrawing funds instantly, for example, before performing a payout orwhen registering in a service that offers a free trial period followed by subsequent withdrawals of funds \(for more information about such cases, see the article [COF purchase registration](en_pp_recurring.md)\).

For performing payment instrument verification on Payment Page, the Card Verify operation mode of the payment form is used. During the work with this mode, it is possible to specify card details the customers submitted via the means of communication\(Mail Order / Telephone Order; MO/TO\) and save the provided card details in the platform.

In terms of performing payment instrument verification using Payment Page, the basic steps that the customer performs may be specifying payment information, saving the payment information for subsequent payments processing and waiting for notification about the result.

![](images/ecommpay/en_pp_account_verification.svg)

## Workflow {#section_zvb_r3l_dmb .section}

Payment instrument verification by using Payment Page requires the merchant web service to do the following:

1.  Create and send a request for opening Payment Page to the payment platform.
2.  Receive callback with the result of the request processing from the payment platform.

Payment instrument verification may involve auxiliary procedures:

-   *3‑D Secure authentication*, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed \(while issuer confirms authentication with no customer effort required\).
-   *Submission of additional payment information*, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when performing payment cards verification.

## Request format {#section_acq_2pl_dmb .section}

The format of the request for opening Payment Page to perform payment instrument verification is the same as the request format described in the [Request format](en_pp_interaction_organisation.md) section. When creating request, you should consider the following:

1.  The following required parameters must be used:
    -   `mode`—the indicator of the Payment Page operation mode. The value must be `card_verify`.
    -   `project_id`—the project ID obtained from Ecommpay.
    -   `payment_id`—the payment ID unique within the project.
    -   `payment_amount`—payment amount in minor currency units, the `0` value must be specified.
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format.
    -   `signature`—the signature that is created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
2.  In order to register a COF purchase, you need to additionally specify the `recurring` parameter with information about this COF purchase \(for more information, see [COF purchase registration](en_pp_recurring.md)\).
3.  To save payment instrument details, you need to additionally specify the `customer_id` parameter and the customer ID in merchant's web service as its value.
4.  To perform verification on the instrument token, specify the `account_token` parameter—the token received from Ecommpay.
5.  To display Payment Page in a required language, you need to additionally specify the `language_code` parameter. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default—[learn more](en_PP_WigetLanguages.md)\).
6.  To add description of the payment, you need to specify the `payment_description` parameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard and in a callback with information about the payment result.
7.  To specify card details submitted by customers via the means of communication, you must use the `moto_type` parameter with the value `1`, for mail communication \(Mail Order\), or `2`, for telephone communication \(Telephone Order\).
8.  If needed, you can also add any other additional parameters supported by Payment Page in the Card Verify operation mode. The full list of parameters for opening Payment Page is provided in the [Payment Page API specification](en_PP_Parameters.md) section.

Thus, a correct request for payment instrument verification must include Payment Page operation mode indicator, project and payment IDs, signature, payment currency and amount. In order to save the payment information, you also need to specify `customer_id`, and in order to register COF purchase, you also need to specify a string which contains set of corresponding parameters.

```language-json
{
   "mode": "card_verify",
   "project_id": 874,
   "payment_id": "15538406111",
   "payment_currency": "EUR",
   "payment_amount": 0,
   "signature": "TSzdE5rJpfXriFf82MxF...",

// saving payment information:
    "customer_id": "customer_10",

// verification by card token:
   "account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021",

// registering COF purchase:
   "recurring": {
        "register": "true",
        "type": "R",
        ...
   }

}
```

```language-json
https://paymentpage.ecommpay.com/payment?payment_currency=EUR&language_code=en&mode=card_verify&project_id=874&payment_amount=0&payment_id=15538406111&css_modal_wrap=standart&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...
```

## Callback format {#section_l5r_5mm_dmb .section}

To notify the merchant about the result of payment instrument verification, the standard callback format is used. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is an example of a callback with information about successful verification of the card with the card number `431422******0056` of the customer `customer_10` and successful registration of the card for subsequent COF purchases.

```language-json
{
  "project_id": 874,
  "payment": {
    "id": "15538406111",
    "type": "account_verification",
    "status": "success",
    "date": "2020-06-10T13:45:59+0000",
    "method": "card",
    "sum":{
      "amount": 0,
      "currency": "EUR"
    },
    "description": "Add the card"
  },
  "account":{
    "number": "431422******0056 ",
    "token": "844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type": "visa",
    "card_holder": "JOHN SMITH",
    "id": 8861226,
    "expiry_month": "09",
    "expiry_year": "2025"
  },
  "customer":{
    "id":"customer_10"
  },
  "recurring":{
    "register": "true",
    "type": "R"
  },
  "operation":{
    "id": 42209000002431,
    "type": "account verification",
    "status": "success",
    "date": "2020-06-10T13:45:59+0000",
    "created_date": "2020-06-10T13:45:57+0000",
    "request_id": "5cb898347e62b2c1-52dac6c8c",
    "sum_initial":{
      "amount": 0,
      "currency": "EUR"
    },
    "sum_converted":{
      "amount": 0,
      "currency": "EUR"
    },
    "provider":{
      "id": 120,
      "payment_id": "306449667",
      "date": "2020-06-10T13:45:59+0000",
      "auth_code": "188591",
      "endpoint_id": 120
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "P9g0U+eF2QWs2A..."
}
```

The following is an example of a callback with information about declined payment instrument verification with no decline reason specified.

```language-json
{
  "project_id": 874,
  "payment":{
    "id": "15538406111",
    "type": "account_verification",
    "status": "decline",
    "date": "2020-06-16T06:06:53+0000",
    "method": "card",
    "sum":{
      "amount": 0,
      "currency": "EUR"
    },
    "description": "Add the card"
  },
  "account":{
    "number": "431422******0056 ",
    "type": "visa",
    "card_holder": "JOHN SMITH",
    "expiry_month": "09",
    "expiry_year": "2025"
  },
  "customer":{
    "id": "customer_10"
  },
  "operation":{
    "id": 40975000002863,
    "type": "account verification",
    "status": "decline",
    "date": "2020-06-16T06:06:53+0000",
    "created_date": "2020-06-16T06:06:47+0000",
    "request_id": "9120271eb02-83e0e70fc0a0a3c1b4d",
    "sum_initial":{
      "amount": 0,
      "currency": "EUR"
    },
    "sum_converted":{
      "amount": 0,
      "currency": "EUR"
    },
    "provider":{
      "id": 120,
      "payment_id": "308822001",
      "date": "2020-06-16T06:06:49+0000",
      "auth_code": "",
      "endpoint_id": 120
    },
    "code": "10100",
    "message": "Declined by external provider"
  },
  "signature": "P9g0U+eaZ9EeNiWiaQWs2A..."
}
```

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# Tokenization {#en_pp_token}

An article about opening the payment form for registering payment data and generating a token for this data.

## General information {#section_stq_mw3_2mb .section}

Payment Page allows creating tokens. Tokens are stored on the merchant web service side and can be used for purchase processing by using Payment Pageand Gate and for payout processing by using Gate.

*Token* is a unique, random sequence of 64 characters associated in terms of the payment platform with a specific payment card.

Token is created based on customer payment information, such as payment card number, name and surname of cardholder and card expiration date. Tokenization can be performed in the following cases:

-   Payment Page is opened in the Card Tokenize mode.
-   purchase processing with saving payment information in the Purchase mode completes successfully.
-   the first purchase or payoutprocessing using payment card completes successfully—if this option is available to merchant project. In order to configure automatic tokenization using this option, contact Ecommpay technical support \([support@ecommpay.com](mailto:support@ecommpay.com)\).

In each case for a particular payment card one token is created with the expiration date equal to the expiration date of the payment card, and the status of the token is `active`. Once the token expires, the status is set to `expiry`. If the token is deleted on request from the web service, the status is set to `revoke`. In both cases \(`expiry` and `revoke`\) payment processing using this token is unavailable.

To delete token or obtain payment information related to the token, you need to use Gate.For more information, see [Using tokens](en_Gate_Token.md).

When tokenization is used via Payment Page, basic steps that the customer performs include specifying card details and waiting for notification about the result.Following the successful generation of the payment card token, the details of this card are shown on the saved payment instruments list of the payment method selection page.

![](images/ecommpay/en_pp_token.svg)

This section covers information about tokenization performed by using Payment Page in the Card Tokenize mode. For information about tokenization performed during purchase processing, see [Purchase processing](en_pp_purchase.md).

## Workflow {#section_hcr_1g4_2mb .section}

In terms of performing tokenization by using Payment Page, the merchant web service is required to do the following:

1.  Create and send a request for opening Payment Page to the payment platform.
2.  Receive the callback with the result of the request processing from the payment platform.

## Request format {#section_rgv_yr2_plb .section}

The format of the request for opening Payment Page to perform tokenization is the same as the request format described in the [Request format](en_pp_interaction_organisation.md) section. When creating request, you should consider the following:

1.  The request must contain the following required parameters:
    -   `mode`—the indicator of the Payment Page operation mode. The value must be `card_tokenize`.
    -   `project_id`—the project ID obtained from Ecommpay.
    -   `customer_id`—the customer ID unique within the project.
    -   `signature`—the signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
2.  To display Payment Page in a required language, you need to additionally specify in the request the `language_code`parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified, the payment form is displayed in the language selected automatically \(by the browser language or by default—[learn more](en_PP_WigetLanguages.md)\).
3.  If needed, you can also add any other additional parameters supported by Payment Page in the Card Tokenize mode. The full list of parameters for opening Payment Page is provided in the [Payment Page API specification](en_PP_Parameters.md) section.

Thus, a correct payment request must include identifier of the Payment Page operation mode, project and customer IDs and signature.

```language-json

{
   "mode": "card_tokenize",
   "project_id": 112,
   "customer_id": "cust_123",
   "signature": "TSzdE5rJZaA9VyJtnfRI362oGpfXriFf82MxF..."
}

```

```language-json
https://paymentpage.ecommpay.com/payment?signature=A%2Fqqxsl59tRrtACreixy8sieSfxR%2BC...&mode=card_tokenize&project_id=112&customer_id=cust_123&region_code=EU&language_code=en
```

## Callback format {#section_x3c_5zd_plb .section}

The format of the callback to notify the merchant about token creation is the same as the format described in the [Handling callbacks](en_platform_callbacks.md) section.

The following is an example of a token \(`token`\) created for the customer `cust_123` in terms of the project `112`. Date and time of token creation \(`token_created_at`\) as well as the current status of the token \(`token_status`\) are also specified.

```language-json
{
    "general": {
        "project_id": 112,
        "customer_id": "cust_123",
        "signature": "mTHcy5wvpOYkl9S5eLJZ..."
    },
    "request": {
        "id": "3c7f53fdbb5b8c96f9707457d75f",
         "action": "tokenize",
         "status": "success"
     },
    "token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
    "token_created_at":"2020-03-28 13:30:57",
    "token_status":"active"
}

```

**Parent topic:**[Basic actions](en_pp_basic_actions.md)



---

# Auxiliary procedures and additional capabilities {#en_PP_Additional .concept}

Articles about auxiliary procedures and additional capabilities of Payment Page for boosting payment acceptance rates, customer convenience, and the quality of the provided services.

This subsection provides the information about various *procedures* and *capabilities*. While the procedures can be run automatically during the Payment Page operation for processing separate payments and affect user scenarios, the capabilities can be implemented upon the merchant request for improving the provided service.

## Boosting payment acceptance rates {#section_pv1_qq1_dtb .section}

The procedures and capabilities that can help to ensure high acceptance rates:

-   [3‑D Secure authentication](en_pp_3ds.md)—about the procedure of performing customer authentication for processing card payments.
-   [Checking with Address Verification Service](en_PP_avs.md)—about the procedure of specifying customers' postal codes and addresses for processing payments with the use of the cards American Express,Mastercard, and Visa.
-   [Submission of additional payment information](en_pp_clarification.md)—about the procedure of specifying additional data that can be requested by payment systems in certain cases.
-   [Payment retries](en_PP_Try_Again.md)—about the capability of providing the customers with additional payment attempts \(in case of other attempts failure\), including the capability of changing the payment method.
-   [Cascade payment processing](en_pp_cascading.md)—about the capability of making additional payment processing attempts \(when relevant\), without changing the payment method.
-   [Collecting customer data](en_PP_Gathering_customer_data.md)—about the capability of obtaining and providing customer additional information. This can help to avoid the implementation of some auxiliary procedures.

## Improving customer experience {#section_zdq_tjf_dtb .section}

The capabilities that can be used for adjusting payment scenarios to different situations:

-   [Interface language support](en_PP_WigetLanguages.md)—about the capabilities of specifying the language used when the payment form is displayed.
-   [Preselecting payment methods](en_PP__PreselectingPS.md)—about the capability of specifying a certain payment method when opening the payment form.
-   [Managing payment methods availability](en_pp_methods_availability.md)—about the capability of displaying to the customers not all but only the relevant payment methods from the ones available for the project.
-   [Arranging payment methods on the page](en_pp_methods_order.md)—about the capability of arranging payment methods to be presented to the customer in the optimal order.
-   [Saving customer payment data](en_PP_saved_data.md)—about the capabilities of saving and using the customer payment data when working with the payment form.
-   [Payments by using tokens](en_PP_Payment_by_token.md)—about the capability of using payment data tokens for shortening the customer payment scenarios.
-   [Currency conversion](en_pp_currency_conversion.md)—about the capability of processing payments in different currencies with currency conversion.
-   [Currency choice in Payment Page](en_pp_currency_choice.md)—about the capability of enabling customers to choose payment currency that fits their needs.
-   [Supporting sustainable payments](en_pp_ekko_earth.md)—about the capability of making financial contributions to environmental projects via the specialised partner service of the [ekko](https://ekko.earth/) platform.

## Supporting specific scenarios of working with the form {#section_w5j_ftf_dtb .section}

The capabilities of adapting the payment form to different industries, types of business, and particular cases:

-   [Debt repayment](en_PP_debt_repayments.md)—about the capability of using the payment form for accepting loan and credit repayments.
-   [Limiting time for working with payment form](en_pp_time_limit.md)—about the capability of setting the time limit for making a purchase.
-   [Specifying extended purchase data for subsequent merchant use](en_pp_additional_data.md)—about the capability of passing relevant purchase information to be used by merchants at their discretion.

## Monitoring payment form usage {#section_src_3zf_dtb .section}

The capabilities of obtaining and processing the information about various interface events related to the payment form and customer actions in this form—[Handling events in Payment Page](en_pp_ui_monitoring.md).

## Informing customers {#section_dyv_q1g_dtb .section}

The information about the capabilities that can be used for informing customers:

-   [Using dynamic merchant descriptor](en_pp_descriptor.md)—about the capability of providing customers with information about merchants via issuer services.
-   [Sending receipts and notifications to customer](en_PP_receipt_data.md)—about the capability of informing customers about payment processing and related events via email notifications.

-   **[3‑D Secure authentication](en_pp_3ds.md)**  
An article about the procedure of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Payment Page.
-   **[Checking with Address Verification Service](en_PP_avs.md)**  
An article about the procedure of verifying customers' postal codes and addresses for processing American Express, Mastercard, and Visa payments via Payment Page.
-   **[Submission of additional payment information](en_pp_clarification.md)**  
An article about the procedure of specifying additional data that can be requested by payment systems during payment processing via Payment Page.
-   **[Payment retries](en_PP_Try_Again.md)**  
An article about the capability of providing customers with additional payment attempts via Payment Page if the previous attempt to pay has failed, with the option to select the payment method.
-   **[Cascade payment processing](en_pp_cascading.md)**  
An article about the capability of making additional attempts to process a payment via Payment Page if the previous attempt has failed, without changing the payment method initially selected.
-   **[Collecting customer data](en_PP_Gathering_customer_data.md)**  
An article about the capability of obtaining and using additional customer information during payment processing via Payment Page to minimise the need for auxiliary procedures.
-   **[Interface language support](en_PP_WigetLanguages.md)**  
An article about the capabilities of specifying the language used when the payment form is displayed.
-   **[Preselecting payment methods](en_PP__PreselectingPS.md)**  
An article about the capability of preselecting a specific payment method when invoking the payment form.
-   **[Managing payment methods availability](en_pp_methods_availability.md)**  
An article about the capability of configuring payment method selections relevant to each payment form invocation.
-   **[Arranging payment methods on the page](en_pp_methods_order.md)**  
An article about the capability of arranging payment methods on the form to be presented to the customer in the optimal order.
-   **[Saving customer payment data](en_PP_saved_data.md)**  
An article about the capabilities of saving and using the customer payment data when working with the payment form.
-   **[Payments by using tokens](en_PP_Payment_by_token.md)**  
An article about the capability of using payment data tokens to reduce the number of steps in customer payment scenarios.
-   **[Currency conversion](en_pp_currency_conversion.md)**  
An article about the capability of processing payments via Payment Page in different currencies with currency conversion.
-   **[Currency choice in Payment Page](en_pp_currency_choice.md)**  
An article about the capability of letting customers choose payment currency that fits their needs in the payment form.
-   **[Supporting sustainable payments](en_pp_ekko_earth.md)**  
An article about the capability of adding the option to payment form workflows that allows contributing to environmental projects via the ekko partner service.
-   **[Debt repayment](en_PP_debt_repayments.md)**  
An article about the capability of using the payment form to accept loan repayments.
-   **[Limiting time for working with payment form](en_pp_time_limit.md)**  
An article about the capability of setting the time limit for making a purchase within a single payment form invocation.
-   **[Specifying extended purchase data for subsequent merchant use](en_pp_additional_data.md)**  
An article about the capability of capturing relevant purchase information via Payment Page for internal merchant use.
-   **[Handling events in Payment Page](en_pp_ui_monitoring.md)**  
An article about the capabilities of obtaining and processing the information about various interface events related to the payment form and customer actions in this form.
-   **[Using dynamic merchant descriptor](en_pp_descriptor.md)**  
An article about the capability of providing customers with information about merchants via issuer services.
-   **[Sending receipts and notifications to customer](en_PP_receipt_data.md)**  
An article about the capability of informing customers about payment processing and related events via email notifications.

**Parent topic:**[Payment Page](en_PP_about.md)



---

# 3‑D Secure authentication {#en_pp_3ds}

An article about the procedure of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Payment Page.

## Overview {#section_kwv_pln_njc .section}

3‑D Secure \(Three-Domain Secure\) customer authentication is aimed to increase secure processing of online card payments. This authentication procedure is essential for processing standard card purchases and can be carried out in a variety of ways: the customer may be required to perform certain actions to confirm their identity or their involvement can be bypassed altogether.

**Note:** Global card networks such as American Express, Mastercard, and Visa as well as Ecommpay currently support the second version of the 3‑D Secure protocol, 3‑D Secure 2. The article contains the information about working with this protocol version.

3‑D Secure supports the following authentication flows:

-   *Challenge flow*—authentication that requires the customer to perform certain actions in order to confirm their identity. Customers can be authenticated with the use of one-time code or biometric data if this capability is supported by the issuer, for example.
-   *Frictionless flow*—authentication that does not involve interaction with the customer. Customers are authenticated with the use of data that the issuer already has.

![](images/3ds2_flow.svg)

The merchant cannot select the authentication flow. While the merchant can indicate which flow selection is preferable, the final decision is made by the issuer. In addition to specifying the preferred flow, the merchant can pass a range of optional parameters in the payment request which increases the possibility of the frictionless flow selection and thereby helps increase acceptance rates and enhances customer experience. Information about these and other parameters can be found [below](en_pp_3ds.md).

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Special aspects {#en_pp_3ds_special_aspects}

### Out of scope payments {#section_lbk_jcl_njc .section}

As a rule, the 3‑D Secure authentication is mandatory for card payments. It is dictated by the requirements of the Payment Services Directive 2 \(PSD2\) that includes the requirement of Strong Customer Authentication \(SCA\) to be applied to such payments.

Payments that do not fall under the scope of the SCA mandated by PSD2 include:

-   Payments made with cards issued in a country that is not located in the European Economic Area.
-   Payments made with anonymous prepaid cards: for example, a gift card or a prepaid virtual card.
-   MO/TO \(Mail Order/Telephone Order\) payments.
-   Merchant-initiated transactions \(MIT\). In the Ecommpay payment platform such payments include autopurchases and regular purchases \(`recurring` payment type\)as well as operations to change the authorised amount \(`incremental` operation type\).
-   Most alternative payments.

The payment platform supports the capability to identify payments that belong to any of the aforementioned categories. As a result, they are not subject to 3‑D Secure.

### Exemptions {#section_grf_ncl_njc .section}

Under PSD2, there are several exemptions to SCA when the authentication is deemed not necessary by the issuer. The exempt payments can be categorised as follows:

-   Low value payments \(Low value exemption\)—if it is a payment for an amount below 25 [GBP](references/en/currencies/GBP.md) \(within Great Britain\) or 30 [EUR](references/en/currencies/EUR.md) \(within the EEA\). Along with that, there should be no more than five payments since the most recent successful authentication attempt, and the total amount of these payments should not exceed 85 [GBP](references/en/currencies/GBP.md) or 100 [EUR](references/en/currencies/EUR.md) respectively.
-   Low risk payments \(Transaction Risk Analysis exemption\)—if it is a payment processed by an acquirer with the fraud rates that fall below the thresholds defined in PSD2.
-   Payments to trusted merchants \(Trusted beneficiaries exemption\)—if it is a payment to a merchant that was added by the cardholder \(or with the cardholder's consent\) to a trusted list.
-   Secure corporate payments \(Corporate payments exemption\)—if it is a payment initiated by a company with the use of procedures and protocols that ensure high level of fraud protection \(such as Electronic Banking Internet Communication Standard, EBICS\).

The Ecommpay payment platform supports working with the SCA exemptions for Mastercard and Visa payments of the first two categories: low value and low risk.

### Working with the SCA exemptions {#section_ubm_4cl_njc .section}

Applying exemptions may keep the customer payment experience seamless and increase the payment acceptance rates. However, the merchant is held liable for possible fraud in case of exempt payments.

If this capability is enabled, the relevant exemptions are applied automatically with the exception of the specific payments for which the merchant indicates that the authentication is necessary. At the same time, keep in mind that should the issuer deem it necessary, the exempt payment can still be processed with the authentication. In this case, the issuer can respond with a soft decline which means the authentication is required. Following a soft decline, standard authentication without exemptions is performed, and as a rule, the challenge flow is used. Moreover, exemptions do not apply in case of the COF purchase registration for which 3‑D Secure is mandatory.

Information about applied exemptions is passed in the payment result callbacks and shown in the payment information tabs in Dashboard. If you have any questions about setting up and working with the SCA exemptions, refer to your Ecommpay account manager.

## User scenarios {#en_pp_3ds_user_scenarios}

The following are the steps the customer takes when making a purchase that involves the 3‑D Secure authentication.

1.  The customer selects the option to make a purchase on the side of the merchant's web service.
2.  The payment form is displayed to the customer in accordance with the parameters passed in the request. The customer performs the required actions and confirms the purchase following which they are shown the Payment Page preloader.
3.  If the issuer selects the challenge flow, the customer is shown the authentication page \(ACS\). The customer completes the required steps and is shown the Payment Page preloader.
4.  The customer is shown the page with the payment result information.

![](images/ecommpay/en_pp_3ds.svg)

## Implementation {#en_pp_3ds_implementation}

3‑D Secure is implemented when the Ecommpay specialists add card payments to the merchant's project. Other than that, the merchant is not required to take any additional steps.

## Data formats {#en_pp_3ds_data_formats}

### Required parameters {#section_gym_sbv_yvb .section}

In requests for processing payments that will be subject to 3‑D Secure \(with the exception of payment instrument verification requests when the payment form is opened in the Card Verify operation mode\), pass the required parameters for the specific payment type and additionally include one of the following parameters.

|Parameters|Description|
|----------|-----------|
|`customer_email`  
 string

|Customer's email. Required if the customer's phone number is not passed.|
|`customer_phone`  
 string

|Customer's phone number. Required if the customer's email is not passed.|

### Recommended parameters {#section_ecf_2qr_ndc .section}

In requests for processing payments that will be subject to 3‑D Secure, you are recommended to specify parameters listed below because it can increase the possibility of frictionless flow selection that bypasses interaction with the customer. Such data can include the indication of the preferred authentication flow, the selected shipping method, the customer's billing address and contact information. This information can be collected in whatever way is deemed most convenient, including via the payment form \(using the capability of [collecting additional customer data](en_PP_Gathering_customer_data.md)\), and passed in the following parameters:

|Parameter|Description|tree|
|---------|-----------|----|
|`payment_merchant_risk`  
 string

|Details of the customer's purchase and the indication of the preferred authentication flow.

 A Base64 string converted from the `payment` JSON object with the relevant objects and parameters.

 ``` {#codeblock_k1s_h3b_d2c .language-json}
{ 
  "payment":{ 
    "reorder":"01",
    "preorder_purchase":"01",
    "preorder_date":"11-10-2022",
    "challenge_indicator":"01",
    "challenge_window":"01",
    "gift_card":{ 
      "amount":12345,
      "currency":"USD",
      "count":1
    }
  }
}
```

 ``` {#codeblock_osx_h3b_d2c}
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==
```

|2|
|`challenge_indicator`  
 string

|Indicates whether the challenge flow is preferred. Possible values:-   `01`—no preferences
-   `02`—not using the challenge flow is preferred
-   `03`—using the challenge flow is preferred
-   `04`—using the challenge flow is required
-   `05`—do not use the challenge flow, the merchant has performed the risk analysis
-   `06`—do not use the challenge flow, use the Data Only flow
-   `07`—do not use the challenge flow, Strong Customer Authentication has been applied otherwise
-   `08`—do not use the challenge flow, the merchant is included in cardholder's trusted beneficiaries list
-   `09`—using the challenge flow is required, prompt the cardholder to add the merchant to the trusted beneficiaries list

|2-12|
|`challenge_window`  
 string

|The dimensions of a window in which the authentication page opens. Possible values:-   `01`—250 x 400 px
-   `02`—390 x 400 px
-   `03`—500 x 600 px
-   `04`—600 x 400 px
-   `05`—full screen

|2-22|
|`preorder_date`  
 string

|The date the preordered merchandise or service will be available in the `DD-MM-YYYY` format.|2-32|
|`preorder_purchase`  
 string

|Indicates whether the purchase is a preorder. Possible values:-   `01`—not a preorder
-   `02`—a preorder

|2-42|
|`reorder`  
 string

|Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:-   `01`—first-time purchase
-   `02`—repeat purchase

|2-52|
|`gift_card`  
 object

|Object with information about a purchase made with a prepaid or gift card.|2-62|
|`amount`  
 integer

|The amount of the purchase made with a prepaid or gift card in the smallest units of currency.|2-6-12-6|
|`currency`  
 string

|Currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format \(for example, [GBP](references/en/currencies/GBP.md)\).|2-6-22-6|
|`count`  
 integer

|Total number of prepaid or gift cards used for making a purchase.|2-6-32-6|
|`customer_account_info`  
 string

|Customer's account details and contact information kept on file on the side of the web service.

 A Base64 string converted from the `customer` JSON object with the relevant objects and parameters.

 ``` {#codeblock_q4h_pgb_d2c .language-json}
{ 
  "customer":{ 
    "address_match":"Y",
    "home_phone":"442055526608",
    "work_phone":"442055537709",
    "account":{ 
      "additional":"gamer12345",
      "age_indicator":"01",
      "date":"01-10-2022",
      "change_indicator":"01",
      "change_date":"01-10-2022",
      "pass_change_indicator":"01",
      "pass_change_date":"01-10-2022",
      "purchase_number":12,
      "provision_attempts":16,
      "activity_day":22,
      "activity_year":222,
      "payment_age_indicator":"01",
      "payment_age":"01-10-2022",
      "suspicious_activity":"01",
      "auth_method":"01",
      "auth_time":"01-10-202213:12",
      "auth_data":"login_0102"
    }
  }
}
```

 ``` {#codeblock_rv4_pgb_d2c}
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====
```

|3|
|`address_match`  
 string

|Indicates whether the customer's billing address matches the address specified in the `shipping` object.

 Possible values:

-   `Y`—addresses match
-   `N`—addresses do not match

|3-13|
|`home_phone`  
 string

|Customer's home phone number, contains between 4 and 24 digits \(for example, `44991234567`\).|3-23|
|`work_phone`  
 string

|Customer's work phone number, contains between 4 and 24 digits \(for example, `44997654321`\).|3-33|
|`account`  
 object

|Object with the customer's account information kept on file by the merchant.|3-43|
|`additional`  
 string

|Additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters.|3-4-13-4|
|`activity_day`  
 integer

|Number of payment attempts in the last 24 hours, 3 characters maximum \(`999`\).|3-4-23-4|
|`activity_year`  
 integer

|Number of payment attempts in the last 365 days, 3 characters maximum \(`999`\).|3-4-33-4|
|`age_indicator`  
 string

|Number of days since the customer account was created. Possible values:-   `01`—guest checkout
-   `02`—the account was created at the moment of making a payment
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|3-4-43-4|
|`auth_data`  
 string

|Additional login information in free text, can contain up to 255 characters.|3-4-53-4|
|`auth_method`  
 string

|Indicates how the customer was authenticated during their most recent login to the web service. Possible values:-   `01`—no authentication
-   `02`—logging in with authentication data kept on file by the merchant
-   `03`—logging in with the federated identity credentials\(for example, Google Account or Facebook ID\)
-   `04`—logging in with the use of FIDO authenticator \(Fast Identity Online\)

|3-4-63-4|
|`auth_time`  
 string

|Date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format.|3-4-73-4|
|`date`  
 string

|Account creation date in the `DD-MM-YYYY` format.|3-4-83-4|
|`change_date`  
 string

|Date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format.|3-4-93-4|
|`change_indicator`  
 string

|Number of days since the most recent change to the account, except for the password change or password reset. Possible values:-   `01`—the account was updated on the day when the payment was made
-   `02`—fewer than 30 days
-   `03`—between 30 and 60 days
-   `04`—more than 60 days

|3-4-103-4|
|`pass_change_date`  
 string

|Date of the most recent password change or reset in the `DD-MM-YYYY` format.|3-4-113-4|
|`pass_change_indicator`  
 string

|Number of days since the most recent password change or reset. Possible values:-   `01`—password was not changed or reset
-   `02`—password was changed or reset on the day when the payment was made
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|3-4-123-4|
|`payment_age`  
 string

|Card record creation date in the `DD-MM-YYYY` format.|3-4-133-4|
|`payment_age_indicator`  
 string

|Number of days since the payment card details were saved to a customer's account. Possible values:-   `01`—guest checkout
-   `02`—card details were saved on the day when the payment was made
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|3-4-143-4|
|`provision_attempts`  
 integer

|Number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum \(`999`\).|3-4-153-4|
|`purchase_number`  
 integer

|Number of purchases made via the customer's account in the last 6 months, 4 characters maximum \(`9999`\).|3-4-163-4|
|`suspicious_activity`  
 string

|Indicates the presence of suspicious activity. Possible values:-   `01`—no suspicious activity detected
-   `02`—suspicious activity detected

|3-4-173-4|
|`customer_shipping`  
 string

|Purchase shipping information.

 A Base64 string converted from the `customer` JSON object with the relevant objects and parameters.

 ``` {#codeblock_s1v_bhb_d2c .language-json}
{ 
  "customer":{ 
    "shipping":{ 
      "type":"01",
      "delivery_time":"01",
      "delivery_email":"test@gmail.com",
      "address_usage_indicator":"01",
      "address_usage":"01-10-2022",
      "city":"London",
      "country":"GB",
      "address":"Blackheath Ave",
      "postal":"SE10 8XJ",
      "region":"Vilnius County",
      "region_code":"LND",
      "name_indicator":"01"
    }
  }
}
```

 ``` {#codeblock_fwb_chb_d2c}
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTG9uZG9uIiwKICAgICAgImNvdW50cnkiOiJHQiIsCiAgICAgICJhZGRyZXNzIjoiQmxhY2toZWF0aCBBdmUiLAogICAgICAicG9zdGFsIjoiU0UxMCA4WEoiLAogICAgICAicmVnaW9uX2NvZGUiOiJMTkQiLAogICAgICAibmFtZV9pbmRpY2F0b3IiOiIwMSIKICAgIH0KICB9Cn0==
```

|4|
|`shipping`  
 object

|Object with shipping details.|4-14|
|`address`  
 string

|Shipping address, can contain up to 150 characters.|4-1-14-1|
|`address_usage`  
 string

|Date when the specified shipping address was used for the first time, in the `DD-MM-YYYY` format.|4-1-24-1|
|`address_usage_indicator`  
 string

|Number of days since the specified shipping address was used for the first time. Possible values:-   `01`—first-time use
-   `02`—fewer than 30 days
-   `03`—between 30 and 60 days
-   `04`—more than 60 days

|4-1-34-1|
|`city`  
 string

|Shipping city, can contain up to 50 characters.|4-1-44-1|
|`country`  
 string

|Shipping country code in the ISO 3166-1 alpha-2 format \(for example, `GB`\).|4-1-54-1|
|`delivery_email`  
 string

|The email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters.|4-1-64-1|
|`delivery_time`  
 string

|Delivery time. Possible values:-   `01`—digital same day delivery
-   `02`—same day delivery
-   `03`—next day delivery
-   `04`—delivery more than one day after the purchase was made

|4-1-74-1|
|`name_indicator`  
 string

|Indicates whether the customer's name matches the recipient's name. Possible values:-   `01`—names match
-   `02`—names do not match

|4-1-84-1|
|`postal`  
 string

|Shipping postal code, can contain up to 16 characters.|4-1-94-1|
|`region_code`  
 string

|State, province, or region code in the ISO 3166-2 format, for example, `DOR` for Dorset.If you specify this parameter, you also need to specify and populate the `country` parameter in the `shipping` object.

|4-1-104-1|
|`type`  
 string

|Delivery option selected by the customer. Possible values:-   `01`—delivery to the cardholder's billing address
-   `02`—delivery to a different verified address
-   `03`—delivery to the address that is not verified and does not match the billing address
-   `04`—store delivery
-   `05`—digital delivery
-   `06`—no delivery needed \(for example, event ticket purchase\)
-   `07`—other

|4-1-114-1|
|`customer_mpi_result`  
 string

|Information about the previous authentication attempt of the customer.

 A Base64 string converted from the `customer` JSON object with the `mpi_result` object and other relevant objects and parameters.

 ``` {#codeblock_l5q_wgb_d2c .language-json}
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
```

 ``` {#codeblock_nsx_wgb_d2c}
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0===
```

|5|
|`mpi_result`  
 object

|Object that contains information about the previous authentication attempt of the customer.|5-15|
|`acs_operation_id`  
 string

|The identifier that the issuer assigned to the previous operation of the customer and returned in the `acs_operation_id` parameter of the callback with payment processing result. Can contain up to 36 characters.|5-1-15-1|
|`authentication_flow`  
 string

|The flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the `authentication_flow` parameter returned in the callback with payment processing result.

 Possible values:

 -   `01`—frictionless flow
-   `02`—challenge flow

|5-1-25-1|
|`authentication_timestamp`  
 string

|Date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result.|5-1-35-1|
|`billing_address`  
 string

|Street of the customer's billing address.|6|
|`billing_city`  
 string

|City of the customer's billing address.|7|
|`billing_country`  
 string

|Country of the customer's billing address in the ISO 3166-1 alpha-2 format.|8|
|`billing_postal`  
 string

|Postal code of the customer's billing address.|9|
|`billing_region_code`  
 string

|State, province, or region code in the ISO 3166-2 format, for example, `DEV` for Devon.If you specify this parameter, you also need to specify and populate the `billing_country` parameter.

|10|
|`customer_email`  
 string

|Customer's email.|11|
|`customer_phone`  
 string

|Customer's phone number, contains between 4 and 24 digits.|12|



---

# Checking with Address Verification Service {#en_PP_avs .concept}

An article about the procedure of verifying customers' postal codes and addresses for processing American Express, Mastercard, and Visa payments via Payment Page.

## General information {#section_ofb_dcx_ydb .section}

**Address Verification Service** \(AVS\) is a service that allows you to check whether a customer who makes a payment by a bank card is the actual cardholder. The AVS check is performed by matching the address specified by a customer while performing a payment with the cardholder address according to the bank card Issuer.

AVS verification is mandatory for payments with Visa and Mastercard cards performed in the UK, and optional in the USA, Australia, Canada and New Zealand. For American Express, AVS verification is mandatory in the USA and Canada and optional in other countries.Therefore, it may be required additional mandatory parameters in the request for payment: the postal code `avs_post_code` and the address `avs_street_address` of a customer, for more information, see [Submission of additional payment information](en_pp_clarification.md). If the data does not passed, not pass validation or empty, you receive the appropriate decline code and message. The result of the AVS check is sent in the callback parameter `avs_result`.

**Note:** The requirement to provide AVS parameters persists even if the payment is made by a token or a saved bank card.

## Results of checking with AVS {#section_gq3_n12_pfb .section}

Possible codes with additional information and descriptions can be found below.

|Code|Additional information|Description|
|----|----------------------|-----------|
|W, Z|Partial match|Post code matches, but street address does not|
|A|Partial match|Street address matches, but post code does not|
|X, Y|Exact match|Address and post code match|
|N|No match|Street address and post code do not match|
|S, U|Address information unavailable.|Address information is unavailable for this account or an issuing bank does not support the AVS|
|R|System unavailable|System is unavailable at the moment, retry|

|VISA|A, N, R, U, Y, Z|
|MasterCard|A, N, R, S, U, W, X, Y, Z|
|American Express|A, N, R, S, U, Y, Z|

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Submission of additional payment information {#en_pp_clarification .concept}

An article about the procedure of specifying additional data that can be requested by payment systems during payment processing via Payment Page.

## General information {#section_vgn_22h_nmb .section}

Mandatory parameters specified in the request for opening Payment Page usually provide enough information for payment processing. However, a payment systemor a payment provider may require some additional data that otherwise is not required, this may be due to regional or country-specific requirements, additional fraud testing procedures or other conditions. Payment Page allows you handling such cases as it supports *submission of additional payment information*. In terms of this procedure, the customer is notified about the need to submit additional data, the required data is collected and the payment is processed considering the provided data.

Submission of additional payment information does not require extra effort of the merchant, as the procedure is performed through interaction between the customer and the payment platform. Nevertheless, in order to avoid the need of submitting additional data, you can specify in the request for opening Payment Page data that may be required by payment systemsor payment providers for processing payments, including optional parameters.

The requested data generally concerns the customer and their payment instrument, and for payments by using alternative payment methods it is the data provided in any optional parameters supported by Payment Page for initial request for payment processing.

The information that the customer may be requested to provide may include the following:

-   `customer_first_name`—first name
-   `customer_last_name`—last name
-   `customer_middle_name`—middle name
-   `customer_day_of_birth`—birth date
-   `customer_email`—email address
-   `customer_address`—the name of the street and the house number \(including any additional parts of the address such as building indicators and apartment numbers\) in the customer's address
-   `customer_city`—city of residence
-   `customer_country`—code of the country
-   `customer_street`—street of residence
-   `customer_zip`—postal code

**Note:** The final set of the requested data depends on the requirements of a particular provider orpayment system and may vary.To precise the set of the data that may be requested depending on the payment method, you may contact your Ecommpay key account manager.

Payment processing continues only after the customer specifies requested data and confirm the purchase. The following sections provide information about steps that the customer performs when submitting additional payment information.

## Usage scenario {#section_hbw_wjh_nmb .section}

The basic usage scenario of submitting additional payment information can be described as follows:

1.  On the merchant web service side, the customer confirms the purchase of the order and is redirected to the payment form.

    If the option of time limit for using the payment form is enabled, the remaining time is also displayed on Payment Page.

2.  The customer enters the payment details.
3.  As the need for additional payment information is identified, a notification and additional fields for entering the data are displayed on Payment Page. The customer enters additional data, confirms the purchase and receives the result information.

![](images/ecommpay/en_pp_clarification_1.svg "1 — Opening payment form")

![](images/ecommpay/en_pp_clarification_2.svg "2 — Entering payment details")

![](images/ecommpay/en_pp_clarification_3.svg "3 — Entering additional data")

## The workflow {#section_gd4_gkh_nmb .section}

The following diagram illustrated the procedure of submitting additional payment information.

![](images/eng_pp_clarification_uml.svg)

1.  When the need for additional payment information is identified, the set of the data to be requested is formed in the payment platform and redirected to Payment Page.
2.  The page for entering the requested data is displayed to the customer.
3.  The customer enters the requested data.
4.  The data specified by the customer is transferred to the payment platform.
5.  The received data is processed in the payment platform, and after that payment processing continues in its ordinary way.

## Usage specifics {#section_vmd_mjd_4mb .section}

When configuring time limit for using Payment Page, you should take into account that the time for submitting additional payment information is included in the common time for using the payment form.Hence, when you configure the time limit for using the payment form, you need to take into consideration the time of possible submission of additional data. If the restriction is not set, waiting time for submitting additional payment information is set by default, it is 30 minutes starting from the moment of identifying the need for additional data. In both cases, if the additional information is not provided before the remaining time expires, payment is automatically declined.

To monitor payments that involve submission of additional information, you can use notifications and information provided in the payment information tabs in Dashboard \(for more information, see [Monitoring and performing payments](en_dbl_payments.md)\). Intermediate and final notificationssent from the payment platform contain the set of data requested from the customer in terms of submitting additional payment information. Intermediate notifications also contain the status of the payment \(`awaiting_clarification`\), which remain until the customer payment data is received.

The following is an example of a callback with the request of additional data \(customer address\) required for continuation of card payment processing.

```language-json

{
   "project_id": 1173,
   "payment": {
      "id": "15557465346",
      "type": "purchase",
      "status": "awaiting clarification",    // payment status
      "date": "2020-07-30T10:20:58+0000",
      "method": "card",
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2023"
   },
   "customer": {
      "id": "3b6d6827-8cdd-4040-aaf6-0a8f81b95c31"
   },
   "clarification_fields": {     // the requested data
      "avs\_data": \[
         "avs\_address"
      \]
   },
   "operation": {
      "id": 72658000000461,
      "type": "sale",
      "status": "awaiting clarification",
      "date": "2020-07-30T10:20:58+0000",
      "created_date": "2020-07-30T10:20:58+0000",
      "request_id": "c0f65543b97c062cf172cf04df239ee16ae27b34-9b1943e6454385d28d4f975bfd397aef6aa55a71-00072659",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "9999",
      "message": "Awaiting processing",
      "eci": "00",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oFcRanmZ5FrWt8zQWqHM15PPWKV5eAfIErQXBS/1uMwzF1..."
}
```

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Payment retries {#en_PP_Try_Again .concept}

An article about the capability of providing customers with additional payment attempts via Payment Page if the previous attempt to pay has failed, with the option to select the payment method.

## Overview {#section_ovx_sqn_smb .section}

When making payments using Payment Page, customers usually need one attempt to complete the payment, but sometimes they have to repeat the procedure—for example, when there are insufficient funds on the payment card the customer is using to make the purchase. In such cases, the Ecommpay payment platform provides the capability of retry attempts to make one payment \(a payment with the same identifier\) during a single session on Payment Page.

Generally, if the payment has been declined, the final page of the payment form with an error message is displayed to the customer. In this case, without the functionality of payment retries, the Payment Page session is completed, and, to repeat the attempt, the customer has to go back to the web service to initiate a new payment. With the capability of retry attempts set up, if the payment fails, it can be attempted again within a single session; in this case, the error message and the button for retrying the payment are displayed on the final page of the payment form.

||

**Note:** Cookies are required for the emulator to function properly. The emulator will not load without cookies.

Since all retry attempts are made within a single Payment Page session, the parameters specified in the request for opening Payment Page remain unchanged for all subsequent attempts.This also applies to cases when [payment methods or method groups are preselected](en_PP__PreselectingPS.md).

Overall, when the payment retries functionality is used, the options of payment method selection are determined as follows.

|Preselected payment method or method group|First attempt|Each retry attempt|
|------------------------------------------|-------------|------------------|
|–\(none\)

|any payment method available|depending on the action performed during the first attempt:-   processing a purchase—any of the payment methods available for making a purchase
-   placing an authorisation hold—any of the payment methods available for performing an `auth` operation

|
|card payments|card payments|card payments or \(if agreed upon and set up\) Apple Pay or Google Pay|
|alternative payment method\(group of methods\)

|specified method\(group of methods\)

|specified method\(group of methods\)

|

**Note:** Keep in mind the following considerations for payment method selection when using the functionality:

-   If the payment method has not been preselected, should the customer decide to retry the payment, they can choose one of the payment methods that support the type of the operation performed during the first attempt. For example, if the first attempt involved placing an authorisation hold as part of performing a two-step purchase \(`auth`\), then for every subsequent attempt the customer can select the method for which two-step purchases are supported, so that the authorisation hold is performed instead of the withdrawal of funds \(`sale`\).
-   If card payments are preselected and such option has been set up for the project, the customer can choose to retry the payment not only with the card but also with Apple Pay or Google Pay. This option is set up separately, upon agreement with your Ecommpay account manager.
-   If you specify one of the alternative payment methods in a payment request, all subsequent retry attempts are performed with the use of this method. Another payment method cannot be selected.
-   If you provide a payment card token in a payment request, all subsequent retry attempts are performed with the use of this token. Another payment method or payment instrument cannot be selected.

The number of attempts and the time allocated for executing these attempts are limited. These restrictions can be configured upon coordination with your account managerand apply to all payments within a project for which the functionality of payment retries is set up.

## Usage scenario {#section_ehh_2rn_smb .section}

The following steps present the customer procedure of making a purchase with the capability of retry attempts:

1.  The customer confirms the purchase in the merchant web service.
2.  The customer is redirected to Payment Pagewhich is generated according to the parameters specified in the request for opening Payment Page. The customer performs the required actions and waits for the purchase result.
3.  After the purchase has failed, the final page of the payment form with the button for retrying the payment is displayed to the customer.Upon clicking the button, the customer is redirected to step 2.
4.  After the payment has been completed, the information is displayed on the standard final page of the payment form\(without the button for retrying the payment\).

## Special aspects {#section_ft3_qrn_smb .section}

If you want to set up the functionality of payment retries, consider the following aspects:

-   *The requirement to display the final page of the payment form.*With the functionality of payment retries, the final page with the payment result must be displayed to the customer. If automatic customer redirection to the web service is set up, the customer cannot retry the payment. For more information, see [Options for redirecting customers to the web service](en_PP_redirect_modes.md).
-   *Support for Payment Page customisation.* If the payment form design is implemented on the basis of another interface model \(not the basic one\), coordinate with the Ecommpay account manager the implementation of an additional element on the payment form—the button for redirecting the customer to a payment attempt—and, if necessary, provide the corresponding template layout to the technical support specialists.
-   *The time limit for repeating payment attempts.* The countdown for all retry attempts begins at the moment when the payment failure is registered in the payment platform for the first time. In this case, the timer is not displayed on Payment Page. However, if there is a time limit for making this payment via Payment Page \([details](en_pp_time_limit.md)\), the customer can see the timer counting down the amount of time allowed for this payment. At this point, the time restriction on the payment attempts is ignored.In any of the above cases, ifthere have been no successful retry attempts over the time allocated for using Payment Page, the payment is declined, and the final page with the corresponding notification is displayed on the payment form.

## Setup {#section_mly_s5s_hpb .section}

To have the capability of retry attempts set up, merchants should complete the following steps:

1.  Coordinate the process with your Ecommpay account manager: discuss the setup procedure and whether it is necessary to test the functionality. Also consider the restrictions on the number of attempts and the time allocated for making the attempts.These limits apply to all payments within the project and can be configured by the Ecommpay specialists according to the needs of merchants. Usually, such restrictions are set to 5 attempts that must be performed within 10 minutes.
2.  If it was agreed that testing is required, wait to be notified by the Ecommpay specialists when the functionality is ready, thentest the payment form workflow with the new capability.After that inform the account manager that you are ready to launch the functionality in your production environment.
3.  Receive the notification from the Ecommpay specialists about the completion of the capability setup.

## Workflow {#section_mlr_1vs_hpb .section}

The following diagram illustrates the payment retries workflow:

![](images/en_pp_try_again_uml.svg)

1.  If the purchase has not been completed with the debiting of fundsor authorisation hold, it is checked if retry attempts are available for making the purchase within the project.
2.  An intermediate callback with the information about the capability is sent from the payment platform to the web service.
3.  The information about the availability of payment retries is transmitted from the payment platform to Payment Page.
4.  The final page of the payment form is shown to the customer. It displays the message stating that the purchase has been declined. The page also contains the button for redirecting the customer to an additional payment attempt.
5.  The customer agrees to retry the payment and performs the required actions.
6.  After the customer payment data is transmitted to the payment platform, a retry is initiated with the use of this data.

When payment retries are processed, the payment status can vary:

-   `processing`—checking for the availability of retry attempts in case the purchase fails\(when step 1 on the diagram is performed\) or upon receiving payment data from the customer within the scope of the current retry attempt\(after step 6 is performed\).
-   `awaiting customer`—waiting for the customer actions. The status remains from the moment when the availability of retry attempts is identified within the payment platform\(at step 1\) and until the customer payment data is received \(after step 6 is performed\)or until the attempt time limit expires \(in this case, the payment gets the `decline` status\).
-   `success`—the required action has been completed \(one of the retries has resulted in the debiting of fundsor authorisation hold\).
-   `decline`—all the possible retries have failed \(none has led to the debiting of fundsor hold on funds\) or the time allowed for the attempts has expired. The same status is assigned when the customer declines to repeat the attempt.

All possible payment statuses used within the platform are described in [Payment processing](en_platform_payment_model.md).

## Callbacks {#section_kxm_2ws_hpb .section}

During the process of payment retries, intermediate and final callbacks are sent from the payment platform to the web service.

*Intermediate callbacks.* If the purchase has failed and the availability of retry attempts has been identified, an intermediate callback is sent from the payment platform to the web service. This callback contains information about the availability of retry attempts \(specified in the `is_new_attempts_available` parameter\) and the remaining time allowed for these attempts \(specified in the `timeout_attempts` parameter in seconds—`ss`\).

In the intermediate callbacks, the `is_new_attempts_available` parameter is set to `true`, which implies that all of the following conditions have been met:

-   None of the attempts has led to the completion of the payment.
-   There are available attempts.
-   The time for executing the attempts has not expired.

In the following example of the callback body, you can see that for the purchase with the identifier `100028024` repeating payment attempts is allowed \(`is_new_attempts_available = true`\) and the time limit for the attempts is set to ten minutes \(`attempts_timeout = 600`\).

```language-json
{
   "project_id": 212,
   "payment": {
      "id": "100028024",
      "type": "purchase",
      "status": "awaiting customer",    // payment status
      "date": "2020-07-21T17:51:04+0000",
      "method": "card",
      "is_new_attempts_available": true,    // availability of retry attempts
      "attempts_timeout": 600,    // remaining time
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2025"
   },
   "operation": {
      "id": 20759000013841,
      "type": "auth",
      "status": "decline",
      "date": "2020-07-21T17:51:04+0000",
      "created_date": "2020-07-21T17:20:55+0000",
      "request_id": "7ba0fb24436a717d3091f7b71007891696db6e-00020760",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "108",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oXlx8QWh3OC/YOqb2ib3C5jq/lHvisceI9Lqg/tRTuwcrNmj1zQ..."
}
```

*Final callbacks.* If the payment has been completed or cannot be completed within the session, a final callback is sent from the payment platform to the web service.In this case, the `is_new_attempts_available` parameter is set to `false` due to one of the following conditions:

-   The final attempt has led to the completion of the payment.
-   The customer has declined to repeat the attempt.
-   All the available payment attempts have been used up.
-   The time for making the attempts has expired.

In the following example of the callback body, you can see that the time for performing retries has expired and the purchase has been declined.

```language-json
{
   "project_id": 212,
   "payment": {
      "id": "100028024",
      "type": "purchase",
      "status": "decline",    // payment status
      "date": "2020-07-21T17:51:04+0000",
      "method": "card",
      "is_new_attempts_available": false,    // availability of retry attempts
      "attempts_timeout": 0,    // remaining time
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2025"
   },
   "operation": {
      "id": 20759000013841,
      "type": "auth",
      "status": "decline",
      "date": "2020-07-21T17:51:04+0000",
      "created_date": "2020-07-21T17:20:55+0000",
      "request_id": "7ba0fb24436a717d3091a2bdf7891696db6e-00020760",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "603",
      "message": "Auto decline",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oXlx8QWh3OC/YOqb2ib3C5VLPksceI9Lqg/tRTuwcrNmj1zQ..."
}
```

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Cascade payment processing {#en_pp_cascading}

An article about the capability of making additional attempts to process a payment via Payment Page if the previous attempt has failed, without changing the payment method initially selected.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Overview {#en_pp_cascading_info}

The Ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful. Enabled, the cascading option allows the payment that cannot be processed properly by a provider to be rerouted to an alternative provider with no change of the payment method.

In the payment platform, you can use the cascading option for both *card* payments \(with the direct use of payment cards\) and *alternative* payments \(with the use of alternative payment methods\). But there are some differences between workflows of these payments. In alternative payments, a customer may be charged more than once for the same payment, that's why it is the customer who is required to initiate a new additional attempt. In card payments, however, a customer may be charged only once for the same payment, that's why it is the payment platform which is required to initiate a new additional attempt.

The sections that follow discuss in more details the workflow of cascade payment processing for bothcard paymentsand payments by using alternative payment instruments. For more details on the cascading option and how to enable the option, contact your Ecommpay key account manager.

## Cascading optionwith card payments {#en_pp_cascading_cards}

### Overview {#section_rlm_rfp_qjb .section}

Payments could sometimes fail due to different reasons. For example, while a payment is being processed by a provider or a bank, technical issues may occur, or processing of the payment may take too long, or a customer's card limit may have been reached.

The Ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful. In any of the above cases, the cascading option enabled allows the payment that cannot be processed properly by a provider to be rerouted to an alternative providerwith no change of the payment method. In card payments, you can use the cascading option for both one-step and two-step purchases with authentication by using 3‑D Secure as well as without authentication.

In card payments, a customer may be charged only once for the same payment, that's why it is the payment platform which is required to initiate new additional attempts to process the payment.

Using the cascading option doesn't require to update the merchant web service because workflows of cascade payment processing and regular payment processing are the same for the merchant web service. The following section discusses in more details the workflow of cascade payment processing.

### Setup and configuration {#section_fpy_5hcgh_qjb .section}

To implement the cascading option in your web service you need to contact your Ecommpay key account manager and discuss the possibility of implementing the option, and then test and deploy cascade payment processing with the Ecommpay technical support.

### Workflow {#section_sb4_nvd_kkb .section}

Payments with the enabled cascading option are initiated in the same way as regular payments. Your web service is required to send a request for purchase to initiate an attempt to process the payment by using Payment Page. When the payment platform accepts the request, Payment Page is displaying to a customer for entering card details. The payment platform processes the initial attempt to process the payment, and in addition the 3‑D Secure authentication may be required. If the customer is charged for this attempt, the payment platform sends a callback with the payment results and the `success` payment status. If the customer isn't charged for the initial attempt, the payment platform keeps processing the payment that may contain one or more additional attempts to process it.

Until the customer is charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached, the payment platform initiates a new additional attempt. If the new additional attempt doesn't require 3‑D Secure authentication, there is no need any customer and web service involvement. If the 3‑D Secure authentication is required, Payment Page displays a page with customer card detailes, information about unsuccessfull attempt and **Retry** button. If the customer confirms one more additional attempt to process the payment, the payment platform keeps processing the new additional attempt with new 3‑D Secure authentication. The payment status is set to one of following ones: `awaiting_3ds_result`, `awaiting_redirect_result` or `processing`.

Payment processing with the enabled cascading option is completed in the same way as regular payment processing. The payment platform sends a callback with the `success` payment status, if the customer has been charged for one of processed additional attempts. The payment status is set to `decline`, if the customer hasn't been charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached.

The following diagram provides the detailed picture of a one-step purchase processing with the cascade option enabled and 3‑D Secure authentication included.

![](images/universal/cascade/en_pp_sale_cascading.svg)

\* Ecommpay may function as a provider.

1.  The payment platform performs the internal request processing and sends it to the provider.
2.  The provider processes the request and determines whether the 3‑D Secure authentication is required. If it's required, the provider sends customer redirection data. If it's not required, the provider forwards the request for purchase to an issuer.
3.  The payment platform sends the message with the customer redirection data to Payment Page.
4.  Payment Page interacts with the customer:
    -   If the authentication is required for the first time within the payment processing, Payment Page redirects the customer to the authentication page.
    -   If the authentication is required again, a page with customer card details, information about unsuccessful attempt and asking a customer to confirm one more 3‑D Secure authentication with the same card details is displayed to the customer. If the customer confirms, Payment Page redirects the customer to the authentication page.
5.  The authentication page is displayed to the customer.
6.  The issuer authenticates the customer.
7.  The issuer sends a message with the authentication results to the web service.
8.  The issuer redirects the customer to Payment Page.
9.  The preloaded page of Payment Page is displayed to the customer.
10. The payment platform sends the request for payment to the provider.
11. The provider processes the request. If the customer isn't charged, the provider sends information about declined payment, and then the payment platform initiates a new additional attempt to process the payment. If the customer is charged, the provider forwards the request to the issuer, and the payment platform keeps processing the payment in the same way as regular payment processing.

### Callback format {#section_bnh_qw4_rjb .section}

In card payments, payment processing with enabled cascading option uses the standard format for callbacks with payment results. For more information, see [Handling callbacks](en_platform_callbacks.md).

## Cascading option with payments by using alternative payment methods {#en_pp_cascading_apm}

### Overview {#section_xv1_cjb_nmb .section}

In payments by using alternative payment methods, payment processing usually requires a customer to complete the payment on a provider service. But while processing payment on a provider service, two types of factors influence the payment results: subjective one \(customer influence\) and objective one \(no customer influence\). For example, factors that payment processing may be interrupted by include:

-   Customer influence

    Basically, it happens after a customer has been redirected to a provider service in a separate window. The customer may close the window by accident or on purpose based on subjective evaluation or personal experience about payment processing on the provider service. For example, the customer doesn't trust the provider service and is afraid of entering account details, or the customer misunderstands the flow of payment completing on the provider service, or a form for entering data requires page refresh to load properly, or any other factors affect customer subjective evaluation.

-   No customer influence

    Basically, it happens because of technical issues occurred on a merchant web service side \(for example customer redirection has been failed\) or on a provider side, for example if OTP limit count has been reached, or a customer can't use OTP, or a provider service is temporarily unavailable, or internet connection was interrupted, or any other factors result technical issues.


For these cases the Ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful. In any of the above cases, the cascading option enabled allows a payment that cannot be processed properly by a provider to be rerouted to an alternative provider with no change of payment method. In payments by using alternative payment methods, you can use the cascading option only for one-step purchases.

In payments by using alternative payment methods, a customer may be charged more than once for the same payment, and that's why it is the customer who is required to initiate new additional attempts to process the payment. Until the customer confirms initiating a new additional attempt, the payment platform does nothing for a new attempt. Multiple charges for one purchase usually result from a combination of factors\(the section [Example of cascade payment processing](en_pp_cascading.md#section_u4m_bzj_clb) shows an example of a combination of these factors\). For example, common factors include:

-   A poor internet connection that any participant of payment processing may experience.
-   Incorrect customer opinions about issues caused while processing payment.
-   A lack of information about payment results. For example, a customer hasn’t received payment notifications from a bank, or a provider hasn't sent any payment results to the payment platform because technical issues occurred, or payment notifications may be turned off, or any other reasons. And other factors that result the multiple charges for one purchase.

To support the cascading option it is recommended to update the merchant web service because the workflow of cascade payment processing includes additional steps that are not included in the workflow of regular payment processing. The following section discusses in more details the workflow of cascade payment processing and how to integrate the option in your web service.

### Setup and configuration {#section_fpy_5hc_qjb .section}

To integrate and enable cascading option in your web service you need to do the following:

1.  Address the organisational interaction issue with Ecommpay.
    -   Contact your Ecommpay key account manager and discuss the possibility of implementing the option, as well as discuss what you should do if a customer is charged more than once for the same payment.
    -   Select payment methods that supports payment processing with the cascading option.

        For more information, see payment methods that are described in [Methods](en_pm_about.md) or contact your Ecommpay key account manager.

    -   If needed, contact your Ecommpay key account manager and discuss updates on the default text of notification that is displayed to ask a customer to confirm a new additional attempt. The default is "Should you experience any problems to finish payment, you may try to pay again. Note that banking delays are possible. To avoid double charging, first check your bank account history to make sure funds haven't been debited already." It's recommended to inform a customer that the customer may be charged more than once. In the example that is supplied with illustrations you can see the notification.
2.  Update your web service to support the cascading option.
    -   Update your web service to support payment processing with the cascading option.

        The payment platform may send a callback with payment results within the same payment more than once because the payment platform sends these callbacks for each attempt to process the payment when a customer is charged. That's why the time period for accepting callbacks shouldn’t expiry when the merchant web service accepts the first callback and may takes several days to get the final callback.

    -   Note, the enabled cascading option affects the payment status model.

        The payment platform keeps the payment in the `processing` status, an intermediate one, until the payment platform gets payment results of all attempts from all providers involved in processing. If the payment platform gets payment results of all attempts, the payment status is set to `decline` or `success`, a final status. In the example below you can see this case.

    -   Support payouts for payment methods that support ones. You may send request for payout in case of a customer is charged more than once for the same payment.
3.  Test and deploy cascade payment processing with the Ecommpay technical support.

### Workflow {#section_jlv_4wk_kjb .section}

Payments with the enabled cascading option are initiated in the same way as regular payments. Your web service is required to send a request for opening Payment Page. The payment platform accepts the request, and then Payment Page is displaying for a customer to choose a payment method and to confirm the payment, and the customer is redirecting to the provider service where the customer has to complete the payment. If payment processing doesn't take longer time than usual and the customer is charged for the initial attempt, payment processing with the enabled cascading option is completed in the same way as regular payment processing: the payment platform sends a callback with payment results and the `success` payment status. If the customer isn't charged for the initial attempt, the payment platform keeps processing the payment that may contain one or more additional attempts to process it.

Until the customer is charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached, the customer may initiate a new additional attempt to process the payment.

Note that unlike regular payment processing, payment processing with the enabled payment option is completed in another way: the payment platform may send a callback with payment results more than once for the same payment. It is because the payment platform sends a final callback for each attempt to process the payment that has been processed successfully. Some providers may take a long time to process the request and to send results to the payment platform that's why the time period for accepting callbacks shouldn’t expiry when the merchant web service accepts the first callback, it may takes several days to get the final callback. If the customer is charged more than once, it's recommended to make a refund.

The following diagram provides the detailed picture of payment processing with the enabled cascading option in one the Banks of South-East Asia method, and in this diagram technical issues on a provider side are the reason why the payment can be declined.

![](images/universal/cascade/en_pp_sale_cascading_aps.svg)

1.  If processing of the most recent attempt to process the payment isn't completed normally as in regular payment processing \(17–20\* on the diagram\) or took too longer on a provider side, a customer initiates a new additional attempt on the merchant's web service.
2.  The Payment Page sends the request for an additional attempt to the specified Ecommpay URL.
3.  The payment platform checks whether the limit on the number of allowed attempts has been reached and sends the results that include:
    -   Refusal for initiating a new attempt, if the limit has been reached. In this case on Payment Page the notification is displayed for asking the customer to be back to the merchant web service and initiate a new payment with a new payment identifier, as well as interaction with the customer is over within the purchase.
    -   The updated list of banks, if the limit hasn't been reached. In this case on Payment Page interaction with customer continues within this purchase.
4.  On Payment Page the updated list of banks that the alternative provider supports is displayed for the customer.
5.  The customer chooses one of banks displayed and submits required payment details.
6.  The notification is displayed to inform the customer that it's required to confirm the payment.
7.  The customer confirms the payment.
8.  The Payment Page sends the request for processing the purchase to the specified Ecommpay URL.
9.  The payment platform performs the request processing and redirects the request to the provider service.
10. The request is processed on the provider side.
11. The provider service sends the data for redirecting the customer to the provider service.
12. The payment platform sends the callback with redirection data.
13. The customer is redirected from Payment Page to the provider service.
14. The customer completes all the payment steps required on the provider side.
15. The payment is processed on the provider side.
16. The results of this attempt to process the payment is displayed to the customer on the provider service. If needed, the customer initiates a new additional attempt for the same payment, and the payment processing starts from the first step. If this attempt has been processed successfully and the customer has been charged, the payment processing is completed.
17. \* Providers involved in the payment processing send the payment results to the payment platform. Some providers my take a longer \(up to several days\) to process an attempt and to send payment results.
18. \* The payment platform sends callbacks with payment result to the web service. Note that the payment platform may send a callback with final payment status for each attempt that has been processed successfully. Some providers my take a longer \(up to several days\) to process an attempt and to send payment results.
19. \* The payment results is displayed for the customer on Payment Page.

### Callback format {#section_fv2_4sh_ckb .section}

In the Ecommpay payment platform, each attempt to process a payment within the payment is a separate operation, and the payment platform provides specific `operation_id` for each operation, meanwhile `payment_id` is the same for all of operations defined in the payment. Thus, callbacks may include information about both the payment and a separate operation.

In payments by using alternative payment methods, payment processing with the enabled cascading option uses the standard formats for both intermediate and final callbacks that is described in [Handling callbacks](en_platform_callbacks.md), and the information about each payment method that is described in [Methods](en_pm_about.md) includes examples of these callbacks. Parameters the payment platform sends in callbacks depends on a payment method and an involved provider.

Note that unlike regular payment processing, in this case in the final callback:

-   The payment amount includes total amount of all attempts that a customer has been charged for. Note, the payment platform considers only attempts that the platform has already got the payment results from providers about before the platform sends this callback.
-   The *payment* status is may be final or intermediate even the *operation* status is final. The payment platform may keep the payment in the `processing` status, an intermediate one, for several days or forever even a customer has been charged for one of attempts. If the payment platform gets the payment results of all attempts to process the payment from all providers involved in processing, the payment status is set to the final one:
-   -   `decline`, if all operations have the `decline` status
-   `success`, if at least one of operations has the `success` status.

The following section covers examples of a final callback.

### Example of cascade payment processing {#section_u4m_bzj_clb .section}

**Overview**

The following example should help you figure out how cascade payment processing works: what goes on the payment platform side, and what a customer may do while payment processing.

The example is structured in such a way that it represents a timeline which begins at the top and descends gradually to mark the sequence of interactions. Each interaction between a customer and a Payment Page has an illustration, and callbacks with payment results the payment platform sends to a merchant's web service are represented by code examples. Since final callbacks have different format, unlike in regular payment processing, comments used in the code examples indicate differences.

In this example, a customer has chosen the Banks of Malaysia payment method and initiated three attempts to process the purchase. Two of these attempts has been processed successfully and the customer has been charged twice.

**The initial attempt to process the purchase**

While processing the initial attempt, on Payment Page the customer chooses the Hong Leong Bank, a malaysian bank, is redirected to a provider service in a separate browser window, closes the window \(for example, the customer doesn't trust this provider service\), and confirms initiating a new additional attempt to process the purchase. Within the initial attempt, cascade payment processing includes:

1.  Initiating the purchase

    The customer confirms the purchase, and then the web service sends the request to open Payment Page. On Payment Page the customer selects the payment method and chooses the bank and confirms the payment.

    ![](images/universal/cascade/img_en_pp_1.png)

    ![](images/unimethods/cascade/img_en_pp_2.png)

    ![](images/unimethods/cascade/img_en_pp_3.png)

2.  Customer redirecting

    The Payment Page redirects the customer to the provider service in a separate browser window. In this example, the customer doesn't confirm the purchase, closes the window, and is back to the Payment Page.

    ![](images/unimethods/cascade/img_en_pp_4.png)

3.  Getting confirmation to initiate a new additional attempt to process the purchase

    In this example, since the payment platform doesn't receive a callback with payment results, Payment Page displays notification that asks the customer to initiate a new additional attempt. Then the customer clicks the **Retry** button to confirm a new attempt.

    ![](images/unimethods/cascade/img_en_pp_5.png)


**The second attempt to process the purchase**

Unlike in the initial attempt, the alternative provider is involved in processing this attempt. This provider requires to gather additional information about the customer and update the list of banks that includes Standard Chartered Bank the customer selects on Payment Page. Since the provider takes longer to process the attempt, the customer doesn't wait for a long time and closes the window. Then the customer is back to Payment Page and confirms the third attempt to process the purchase. While processing the next third attempt, the payment platform still doesn't get payment results of this second attempt from the provider. Within this second attempt, on the customer side cascade purchase processing includes:

1.  Choosing a bank

    The customer chooses the bank from the updated list of banks on Payment Page.

    ![](images/unimethods/cascade/img_en_pp_6.png)

2.  Gathering additional payment information

    On Payment Page the customer submits required information and confirms the payment. For more information about the procedure, see [Submission of additional payment information](en_pp_clarification.md).

    ![](images/unimethods/cascade/img_en_pp_7.png)

    ![](images/unimethods/cascade/img_en_pp_8.png)

3.  Customer redirecting

    Payment Page redirects the customer to the current provider service in a separate browser window. In this example, the customer confirm the purchase, doesn't wait for until the current provider process the attempt, closes the window, and is back to Payment Page.

    ![](images/universal/cascade/img_ga_9_pp_9.png)

    ![](images/unimethods/cascade/img_en_pp_10.png)

4.  Getting confirmation to initiate a new additional attempt to process the purchase

    In this example, since the payment platform doesn't receive a callback with payment results, Payment Page displays notification that asks the customer to initiate a new additional attempt. Then the customer clicks the **Retry** button to confirm a new attempt.

    ![](images/unimethods/cascade/img_en_pp_11.png)


**The third attempt to process the purchase**

Unlike in the previous attempts, another alternative provider is involved in processing this attempt. This provider also requires to update the list of banks that includes Hong Leong Bank the customer selects again on Payment Page. The customer gets payment results on the provider service and then is back to Payment Page. Within this third attempt, on the customer side cascade purchase processing includes:

1.  Choosing a bank

    The customer chooses the bank from the updated list of banks on Payment Page.

    ![](images/unimethods/cascade/img_en_pp_12.png)

2.  Customer redirecting

    Payment Page redirects the customer to the provider service in a separate browser window. In this example, the customer confirms the purchase, gets the payment results, closes the window, and is back to Payment Page.

    ![](images/universal/cascade/img_ga_14_pp_13.png)

    ![](images/universal/cascade/img_ga_15_pp_14.png)

    **Processing the payment results**

    The payment platform sends a callback with final payment status for each attempt that has been processed successfully.

    In this example, since the third attempt to process the purchase doesn't take more time than usual and a customer is charged for this attempt, the payment platform sends the callback with the payment results on time, and then the results is displayed to a customer on Payment Page. Then, for example, several hours later, when the provider that involved into the second attempt completed payment processing successfully and sends the payment results to the payment platform, the payment platform sends the callback with the payment results again. But unlike in the last callback, the payment amount includes total amount of both attempts that the customer has been charged for. In this case it's recommended to make a refund, if needed.

    On the merchant web service side processing the payment results includes:


1.  Receiving the callback with payment results for the third attempt

    The payment platform sends the callback with the successful payment results. Since the payment platform still doesn't get the results of the second attempt from the provider involved in processing this attempt, the payment platform keeps the payment in the `processing` status, an intermediate one, but the attempt \(operation\) status is `success`, the final one. The payment results is also displayed to the customer on Payment Page.

    ![](images/unimethods/cascade/img_en_pp_15.png)

    ```language-java
    {
            "customer": {
                "id": "653"
            },
            "project_id": 200,
            "payment": { // payment(purchase) information
                "payment_id": "cosmo_set_4589", // payment identifier, the same for all attempts
                "type": "purchase",
                "status": "processing", // payment status
                "date": "2020-07-20T04:37:57+0000",
                "method": "Malaysian banks",
                "sum": {
                    "amount": 131970, // payment amount includes amount of only one charge
                    "currency": "MYR"
                },
                "description": "Astronaut set" 
            },
            "operation": { // operation information (attempt to process the purchase) 
                "id": 003, // operation identifier defined in the payment platform            
                "type": "sale",
                "status": "success",
                "date": "2020-07-20T04:37:57+0000",
                "created_date": "2020-07-20T04:36:45+0000",
                "request_id": "cosmo_set_4589_request3", // the request identifier the payment platform sends in response 
                                                         // for the request for purchase (for the third attempt)
                "sum_initial": {
                    "amount": 131970, // amount for the third attempt
                    "currency": "MYR"
                },
                "sum_converted": {
                    "amount": 131970,
                    "currency": "MYR"
                },
                "code": "0",
                "message": "Success",
                "provider": { // information about provider involved in processing the thirst attempt
                    "id": 1256,
                    "payment_id": "064604207", // payment identifier defined on a provider side
                    "auth_code": "",
                    "date": "2020-07-20T04:36:51+0000"
                }
            },
            "signature": "n3zmkj5yG..."
        }
    ```

2.  Receiving the callback with payment results for the second attempt

    Several hours later the payment platform sends the callback with the payment results again. Since the payment platform gets the payment results of all attempts to process the payment from all providers involved in the processing and the customer has been charged for at least one of the attempts, the payment status is set to `success`, the final one, while the payment amount includes total amount of both attempts that the customer has been charged for.

    ```language-java
    {
            "customer": {
                "id": "653"
            },
            "project_id": 200,
            "payment": { // payment(purchase) information
                "payment_id": "cosmo_set_4589", // payment identifier, the same for all attempts
                "type": "purchase",
                "status": "success",// payment status
                "date": "2020-07-20T07:12:04+0000",
                "method": "Malaysian banks",
                "sum": {
                    "amount": 263940, // payment amount includes total amount of double charges
                    "currency": "MYR"
                },
                "description": "Astronaut set"
            },
            "operation":{ // operation information (attempt to process the purchase) 
                "id": 002, // operation identifier defined in the payment platform                  
                "type": "sale",
                "status": "success",
                "date": "2020-07-20T07:12:04+0000",
                "created_date": "2020-07-20T04:33:37+0000",
                "request_id": "cosmo_set_4589_request2", // the request identifier the payment platform sends in response 
                                                         // for the request for purchase (for the second attempt)
                "sum_initial": {
                    "amount": 131970, // amount for the second attempt
                    "currency": "MYR"
                },
                "sum_converted": {
                    "amount": 131970,
                    "currency": "MYR"
                },
                "code": "0",
                "message": "Success",
                "provider": { // information about provider involved in processing the thirs attempt
                    "id": 1589,
                    "payment_id": "0757821", // identifier of payment defined on a provider side
                    "auth_code": "",
                    "date": "2020-07-20T07:11:48+0000"
                }
            },
            "signature": "bYNjg..."
        }
    ```




---

# Collecting customer data {#en_PP_Gathering_customer_data .concept}

An article about the capability of obtaining and using additional customer information during payment processing via Payment Page to minimise the need for auxiliary procedures.

## Overview {#section_ivk_bpf_gdb .section}

In some cases, along with data mandatory for payment processing, you may need to collect additional information from your customers, for example, their phone numbers or email addresses. Collecting such data can be useful as it allows merchants to:

-   Provide an extra layer of payment security by collecting and verifying customer information.
-   Improve user scenarios by avoiding the necessity to submit additional payment information \(when it is requested by payment providers,payment systems, and banks during payment processing—[learn more](en_pp_clarification.md)\).

The capability of collecting additional data is supported directly in the Payment Page payment form and, for certain payment methods, in the associated payment services \(such as Apple Pay, for example\).Keep in mind that collecting additional data increases the number of actions required from the customer to make a payment and can negatively affect the payment form conversion. Therefore, this capability should be used only when it is clearly necessary. In most cases, the optimal solution is to submit previously collected information about customers in the requests for opening Payment Page.

To work with additional data provided by customers on the payment formor in the third-party services, you can use payment information tabs in the Dashboard interface and final callbacks with the information about operation processing. To set up passing customer data in callbacks, contact the Ecommpay technical support.

## User scenarios {#section_wks_zfs_jsb .section}

A number of fields can be used to collect additional customer data on the payment form. These fields can be displayed at all times or only when necessary and can be required or optional. Along with that, the placement of these fields can differ: they can be located on the page where customers enter payment information or on the separate page that follows \(depending on the total number of fields\).

The way each field is displayed depends on its specific properties and what data is submitted in the request for opening Payment Page. The following display options are available for each of the additional fields:

-   `1`—the field is displayed with the prefilled value that was specified in the request. The customer can change this value.
-   `2`—the field is displayed and is left blank, but contains a name of the field.
-   `3`—the field is not displayed. The field value can be submitted to the payment platform only via a request.

![](images/ecommpay/en_pp_gathering_customer_data.svg "Additional fields display options")

The field display option is determined as follows.

|This parameter is required|+|+|+|+|–|–|–|–|
|This field must be displayed|+|+|–|–|+|+|–|–|
|The field value is passed in the request|+|–|+|–|+|–|+|–|
|**Field display option**|**`1`**|**`2`**|**`3`**|**`2`**|**`1`**|**`2`**|**`3`**|**`3`**|

To collect additional data via third-party services such as Apple Pay and Google Pay, the interfaces provided by these services are used. Depending on their specifics, requesting customer data may involve, for example, using information previously saved by the customer or other special features of interaction. Note that all requested details must be provided and data requests can be configured both via project-level properties and through individual request parameters. For instance, you can set collecting customer email addresses as a default via project properties and collect other types of data when necessary through request parameters \(learn more in the articles on payment methods [Apple Pay](pm_applepay.md) and [Google Pay](pm_googlepay.md)\). The data collected thereby can be sent to the merchant's web service in the payment result callbacks. To enable this functionality, contact the Ecommpay technical support specialists.

## Setup {#section_ts1_3sf_gdb .section}

To have the capability of collecting customer data enabled, you should:

1.  Decide which projectsand which payment methods supported for these projects may warrant the collection of additional customer data. For each case, determine what data needs to be requested and define the properties of the fields in question. Additional customer data may include a range of parameters \(to learn more, [see below](en_PP_Gathering_customer_data.md#section_jdb_1qx_tdb)\) while the properties of each field are the following:
    -   The field can be required or optional to fill in and/or display.
    -   It is a text or dropdown input field.

        To use a dropdown input field, for example, to collect *the name of the country*, you should provide the support specialists with all possible values for this list or coordinate and approve the use of definitions from the reference sources provided by Ecommpay.

    -   Its name: by default standard names are provided by Ecommpay; however, customisation is available.

        If you would like to add customised field names, provide the support specialists with the translations into all languages used for the project.

2.  Make sure that the technical support specialists have all the details about customer data to be collected as well as the information whether any of these parameters specified by customers on the payment form should be passed in final callbacks.
3.  Get notified by the Ecommpay specialists that the requested functionality has been enabled and test the work of the payment form with this capability if necessary.

## Collected data {#section_jdb_1qx_tdb .section}

The following parameters can be used for collecting customer data.

|Parameter|Description|
|---------|-----------|
|customer\_address  
 string

|The name of the street and the house number \(including any additional parts of the address such as building indicators and apartment numbers\) in the customer's address, separated by a comma.  
 A string, must not exceed 255 characters.  
 Example: `29 Arlington Avenue, Islington`

|
|customer\_birthplace  
 string

|Customer's place of birth  
 A string, must not exceed 255 characters.  
 Example: `Cambridge`

|
|customer\_city  
 string

|Customer's city of residence.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|customer\_country  
 string

|Code of the customer's country in ISO 3166-1 alpha-2 format.  
 Example: `GB`

|
|customer\_day\_of\_birth  
 string

|Customer's date of birth in `DD-MM-YYYY` format.  
 Example: `11-03-1952`

|
|customer\_email  
 string

|Customer's email address.  
 A string, must not exceed 255 characters, must contain two parts: the username and the domain name separated by the @ symbol.  
 Example: `dna@douglasadams.com`

|
|customer\_first\_name  
 string

|Customer's first name.  
 A string, must not exceed 255 characters.  
 Example: `Douglas`

|
|customer\_last\_name  
 string

|Customer's last name.  
 A string, must not exceed 255 characters.  
 Example: `Adams`

|
|customer\_middle\_name  
 string

|Customer's middle name or patronymic.  
 A string, must not exceed 255 characters.  
 Example: `Noel`

|
|customer\_phone  
 string

|Customer's full phone number, with the country code.  
 Technically, the number must include from 4 to 24 digits, and if it is allowed within the project and payment method used, punctuation marks and special symbols may be used while specifying the number \(such cases are usually mentioned separately\).  
 Examples: `443031237300`

|
|customer\_ssn  
 integer

|Last four digits of the Social Security number used for taxpayer identification, income reporting, and record-keeping purposes in the USA.  
 Example: `4942`

|
|customer\_state  
 string

|Customer's region or state.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|customer\_zip  
 string

|Customer's postal code.  
 A string, must not exceed 10 characters.  
 Example: `N17BL`

|
|billing\_address  
 string

|Street of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `Arlington Avenue`

|
|billing\_city  
 string

|City of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|billing\_country  
 string

|Code of the country associated with the customer's billing address in ISO 3166-1 alpha-2 format.  
 Example: `GB`

|
|billing\_postal  
 string

|Postal code of the customer's billing address.  
 A string, must not exceed 16 characters.  
 Example: `N17BL`

|
|billing\_region  
 string

|Region or state of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|billing\_region\_code  
 string

|Code of the region associated with the customer's billing address in ISO 3166-2 format.  
 Example: `LND`

|

If you need to use parameters not listed in the table above, contact the Ecommpay specialists.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Interface language support {#en_PP_WigetLanguages .concept}

An article about the capabilities of specifying the language used when the payment form is displayed.

## Overview {#section_hjd_lgb_sqb .section}

The Payment Page text elements—various names \(including names of fields and other\), hints and messages \(including error messages\)—are the integral part of the payment form. These elements make the interface complete and clear and can have a significant impact on the user experience and the payment form conversion.

![](images/ecommpay/pp_wigetlanguages_1.svg)

## Capabilities {#section_zsf_pgb_sqb .section}

In order to ensure the effectiveness of the Payment Page texts, the Ecommpay specialists work thoroughly on the content localisation and provide the capability of using any of the Payment Page languages from the regularly expanded [basic set](en_PP_WigetLanguages.md#section_ajn_r3b_sqb), while in the form customers can select any of the available languages. Along with that, due to different business nuances and for a better adaptation of Payment Page to a specific project, the merchant can discuss with the Ecommpay account manager the possibility to augment the list of available languages and specify the language relevant to a specific invocation of the payment form\(using the customer's web service language preference, for example\).

![](images/ecommpay/pp_wigetlanguages_2.svg "Using the capability of changing the language")

In addition, it can be relevant to change the payment form design using the corresponding [design builder](en_PP__design_customisation.md).

## Workflow {#section_x4l_1hb_sqb .section}

Every time the payment form opens, the customer can change the language of its interface to any of the basic set. Along with that, the form opens in the following default language \(the options are provided in order of priority\):

1.  The language of the payment form interfacethat was specified in the request for opening the form\([details](en_PP_WigetLanguages.md#section_ivb_h3b_sqb)\)—this language is used if it is supported for the project, and if it is not supported, then the default language \(English\) is used.
2.  The customer’s browser language—this language is used if it has been identified\(via browser properties\) and is supported for the project.
3.  English \(used as a default language\).

## Specifying a language when opening the payment form {#section_ivb_h3b_sqb .section}

In order to localise the payment form for a particular session, submit the request for opening the payment form with the code of this language specified in the `language_code` parameter.Within the payment platform, the codes are passed in the alpha-2 format of the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard, the codes of the languages that are not covered by the standard are coordinated with the merchant.It should be noted that the language set for invoking the form will also be used to generate additional notifications regarding events related to the payment \(if this functionality is enabled in the project settings; see [this article](en_gate_receipts.md)\).

```language-json
{
   "project_id": 93211,
   "payment_id": "423289",
   "payment_currency": "EUR",
   "payment_amount": 131970,
   "customer_id": "customer_772",
   "language_code": "de",    // language code
   "signature": "TSzdE5rJZaA9TYAWEKoGpfXriFf82MxF..."
}
```

This method of specifying the language means that it will determine the language of the payment form interface and the language of [notifications and payment receipts](en_PP_receipt_data.md) \(if applicable\). However, if the specified language falls outside the project's supported language set, then English is used as the default.

## Basic set of languages {#section_ajn_r3b_sqb .section}

Ecommpay supports displaying the payment form in the following languages.

|Language|Language code|
|--------|-------------|
|English|`en`|
|Estonian|`et`|
|French|`fr`|
|German|`de`|
|Italian|`it`|
|Latvian|`lv`|
|Lithuanian|`lt`|
|Portuguese|`pt`|
|Spanish|`es`|
|Ukrainian|`uk`|

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Preselecting payment methods {#en_PP__PreselectingPS .concept}

An article about the capability of preselecting a specific payment method when invoking the payment form.

## Overview {#section_cf5_jxk_ymb .section}

By default, the customer's payment procedure on Payment Page begins at the step of selecting a payment method. However, in some cases, there is no need to display the payment form with the page for payment method selection. This may be the case when the customer selects a payment method in the merchant web service before opening Payment Page or when paying with a particular method is relevant for this merchant due to region- or customer-specific reasons and other factors.

The Ecommpay payment platform provides the capability of opening Payment Page with the payment method that has been preselected by the customer or the merchant.With this functionality configured, the page for selecting a payment method is not displayed to the customer on the payment form. For a payment method to be preselected, this method is specified in the request for opening Payment Page—no additional actions are required for setting up this functionality.

![](images/ecommpay/en_pp_preselectingps_1.svg "Standard scenario—the payment method is selected by the customer on the payment form")

![](images/ecommpay/en_pp_preselectingps_2.svg "Augmented scenario—the payment method is preselected before the payment form opens")

The functionality of preselecting a payment method can be accompanied by other possible capabilities, which are relevant for certain payment methods andaffect the Payment Page workflow. Here are some of such capabilities in particular:

-   *Displaying details of saved cards issued for a certain payment system.* With card payments, it is possible to limit the choice of cards that were previously saved by the customer. For this, the request for opening Payment Page should contain the identifier of the preferred payment system \(for example, Mastercard or Visa\). As a result, the customer payment procedure begins on the page with the list of the previously saved cards that were issued for the payment system specified in the request. If the customer has not saved the card data before or the list of saved cards does not contain the data the customer needs, the customer can specify the details of another card which can also be the card issued for a different payment system.

    ![](images/ecommpay/en_pp_preselectingps_3.svg)

-   *Preselecting banks for online banking payments*. When working with an online banking payment method\(for example, the [Indonesian Online Banking](pm_indonesia.md) method\), merchants can preselect a particular bank that works with the specified payment method. In this case, the customer is redirected straight to the bank website without being redirected to the pages for selecting a payment method and a bank.The information about such capability that is relevant for particular payment methods is provided in the [Methods](en_pm_about.md) section.
-   *Preselecting payment method groups*. Some methods, such as [Open Banking in Germany](pm_germany.md) are included in groups whose identifiers can be specified when sending for opening Payment Page. In this case, the customer is shown buttons for selecting only those methods that are included in the specified group and are available within the project being used.

Finally, besides preselecting a certain payment method, merchants can manage the availability of payment methods on Payment Page. For more information about this capability, see [Managing payment methods availability](en_pp_methods_availability.md).

## Special aspects {#section_a4b_vxk_ymb .section}

If you want to set up the functionality of preselecting a payment method, consider the following aspects:

-   Preselecting a payment method is supported only for the methods that are available within the current project, otherwise, the request for opening Payment Page is declined.
-   The customer cannot select a payment method different from the one that was specified in the request for opening Payment Page; this also applies to the procedure of [payment retries](en_PP_Try_Again.md)—with a payment method preselected, the customer cannot select a payment method when making additional payment attempts within a single Payment Page session.
-   If the request for opening Payment Page contains both a payment method and a token, the payment is processed with the use of this tokenand the information about the specified payment method is ignored.

## Request format {#section_km2_xxv_spb .section}

The preselected payment method should be specified in the request for opening Payment Page. For this, the code of this payment method should be specified in the `force_payment_method` parameter in the request, while to preselect a payment method group, specify the code of the group in the `force_payment_group` parameter. For more information about the codes of the supported payment methodsand groups, see [this reference](en_pm_codes.md).

The following example illustrates the parameters passed in the request for making a purchase with the Alipay payment method.

``` { .language-json .show_more}

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",
   "force_payment_method": "alipay",  // payment method code
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
 }

```

```language-json
{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",
   "force_payment_method": "alipay",  // payment method code
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
 }

```

If you need to specify a certain payment system for a card payment, the request for opening Payment Page should contain the following:

-   The `force_payment_method` parameter with the value `card` \(the code of the card payment method\) specified.
-   The `force_payment_method_subtype` parameter with the identifier of the payment system specified.

The list of the identifiers of the supported payment systems is provided in [Payment card codes](en_card_codes.md).

The following example illustrates the parameters passed in the request for making a payment with Mastercard specified as the preferred payment system.

``` { .language-json .show_more}

{
   "project_id": 43,
   "payment_id": "456790",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12", 
   "force_payment_method": "card",  // payment method code
   "force_payment_method_subtype": "mastercard",   // payment system identifier
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
 }

```

```language-json

{
   "project_id": 43,
   "payment_id": "456790",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12", 
   "force_payment_method": "card",  // payment method code
   "force_payment_method_subtype": "mastercard",   // payment system identifier
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
 }

```

## Related links {#section_e3z_tyv_spb .section}

-   [Payment method codes](en_pm_codes.md)—the reference section with the list of codes for the supported payment methods.
-   [Payment card codes](en_card_codes.md)—the reference section with the list of identifiers for the supported payment systems.
-   [Managing payment methods availability](en_pp_methods_availability.md)—the section with the information about limiting the list of payment methods for a particular payment.
-   [Methods](en_pm_about.md)—the section with the information about the payment methods that are supported within the platform.
-   [Payment Page API specification](en_PP_Parameters.md)—the section with the information about parameters that are used for opening Payment Page.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Managing payment methods availability {#en_pp_methods_availability}

An article about the capability of configuring payment method selections relevant to each payment form invocation.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Overview {#en_pp_availability_info}

When payments are processed via Payment Page, the customer can select any of the payment methods available within the current projectand that support performing the action that the customer needs. As a rule, relatively few payment methods are supported for one project, which means that their full list does not overload the payment form, and the customer can promptly choose the most convenient method to pay. In standard situations, this approach ensures comfortable user experience and high conversion rates.

However, in certain cases—due to the project's specifics and the payment methods and currencies used—improving user experience may involve managing payment method availability, so that the customer can select out of the smaller range of methods rather than all available.

![](images/ecommpay/en_pp_methods_availability_1.svg "Possible situations with choosing a payment method: in a typical case, with an abundance of enabled methods and when filtering methods")

To ensure flexibility in different situations, the platform supports the following options of managing payment method availability.

-   *Availability determined by the merchant* or *directive filtering*—when the web service indicates directly which methods should not be available for selection within the specific payment session. When this filtering option is used, the excluded methods are determined by the web service and are specified each time in the request for opening Payment Page \(as a value of the `hide` parameter\) while the platform processes the request and hides these methods from the selection.
-   *Availability determined by the platform* or *parametric filtering*—when the platform automatically excludes the methods that are not relevant for the customer's country or the currency of the specific payment. When this filtering option is used, the first step is to set the filtering parameters and the relevance of different methods for different countries within the specific project \(this configuration can be quite flexible since different projects allow for more specialised configuration\). After this functionality has been configured and implemented, the excluded methods are determined by the platform each time according to the algorithms of its work and the value of the selected parameter—the country or the currency.
-   *Combined approach*—with the use of both options. When this approach is used, the methods excluded out of all available are determined both with the help of automated filtering by a specified parameter and the values inflexibly specified in the request.

Each of these options can be useful in specific situations, in particular, when there is a need to avoid currency conversion and prevent declined payments in cases when the currency specified in the request is different from the currencies supported for the payment method selected by the customer. At the same time, it is important to keep in mind that overdoing the filtering \(excluding way too many methods\) can take away the customer's opportunity to pay with the method most convenient for them and may lead to decreasing conversion rates.

To avoid such issues and manage method availability efficiently, particularly in cases where it is the most applicable and relevant \(for example, when you work in specific regions or when you use specific processing scenarios\), discuss relevant business goals and filtering options with your Ecommpay account manager and carefully analyse preferences and challenges of your customers.In addition, together with these options or even instead of them, you can set up the capability [of arranging payment methods on the page](en_pp_methods_order.md).

## Methods availability determined by the merchant {#en_pp_directive_methods_avalability}

### General information {#en_pp_directive_methods_avalability_info}

*Directive filtering* allows you to hide those payment methods that are available within the current project but are not relevant for a particular paymentdue to region- or customer-specific reasons and other factors. With this filtering option, the page for selecting payment methods displays to the customer all available methods except for the hidden ones.

![](images/ecommpay/en_pp_methods_availability_2.svg "Possible situations with choosing a payment method: without filtering and with filtering")

However, if the payment is to be processed with the use of only one payment method or group, you might consider setting up the capability of preselecting payment methods and groups \([details](en_PP__PreselectingPS.md)\).

### Setup {#en_pp_directive_methods_availability_enable}

Directive filtering is enabled by default.No additional actions are required for setting up and using this functionality in test and production projects.

### Use {#en_pp_directive_methods_avalability_request}

If you need to filter out particular payment methods within a single Payment Page session, specify the `hide` parameter in the request for opening Payment Page. The value of this parameter is the code of the method to be hidden \(according [to the reference](en_pm_codes.md)\). If there is more than one method specified, the values should be separated by a comma. The codes are the same that are used for preselecting payment methods, but keep in mind that you cannot use the codes for preselecting payment method groups. Hiding groups of payment methods is only possible by specifying each method, not the group.

When using this filtering option, keep in mind the following special aspects and limitations:

-   If the project has only one available payment method and this method is specified in the `hide` parameter, the payment form will be displayed without filtering applied because the value of this parameter will be ignored to prevent errors.
-   If multiple payment methods are available for the project and all of them are listed in the `hide` parameter, the payment form will open with an error page, and the customer will not be able to select a payment method at all.
-   If the same payment method is specified both as hidden \(in the `hide` parameter\) and as preselected \(in the `force_payment_method` parameter, [learn more](en_PP__PreselectingPS.md)\), the payment form will open with an error page, and the customer will not be able to select a payment method at all.

In the following example, the WeChat and Alipay payment methods are excluded from the list of methods available for the customer within this payment.

``` {#codeblock_nlv_lb5_sdc .language-json}
{
   "project_id": 43,
   "payment_id": "456790",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12", 
   "hide": "wechat, alipay", // codes of the payment methods to be hidden
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
 }
```

## Methods availability determined by the platform {#en_pp_parameters_methods_availability}

### General information {#en_pp_parameters_methods_availability_info}

*Parametric filtering* ensures automatic hiding of those payment methods that are available within the current project but are not relevant for the country or currency of a particular payment. With this filtering option, the page for selecting payment methods displays to the customer only relevant payment methods with relevancy determined by the specific criteria.

For example, if within the current project payment method availability is determined by currency, and in general situations, standard card payments, [Blik](pm_blik.md), [Open Banking in the UK](pm_uk.md), and [Open Banking in Germany](pm_germany.md) are usually available, when the request for opening Payment Page specifies the currency of Polish zloty \(`PLN`\), then the customer will be shown the selection of standard card payments and the [Blik](pm_blik.md) payment methods.

![](images/ecommpay/en_pp_methods_availability_3.svg "Possible situations with choosing a payment method: without filtering and with filtering")

You can choose which parameter will be used for filtering \(country or currency\) and how to filter individual methods depending on their specific characteristics and the characteristics of the web service, following which filtering will be configured accordingly. Keep in mind that once set up, the option to filter payment methods by currency is applied each time when Payment Page is invoked. Other than the aforementioned considerations, no actions are required once this functionality is set up.

### Setup {#en_pp_parameters_methods_availability_enable}

To set up parametric filtering, proceed as follows:

1.  Determine the following: which projects require this functionality, which parameter will be used for filtering\(the customer's country or the payment currency\), and whether you need to configure exceptions or specific filtering rules for individual payment methods.

    If needed, consult with your Ecommpay account manager at this step.

2.  Pass your requirements for setting up this functionality to the Ecommpay technical support and agree upon the setup timeline and testing needs for this functionality.
3.  Receive from the Ecommpay specialists the notification that the functionality has been set up and, if necessary, test the work of the payment form with this functionality used.

### Use {#en_pp_parameters_methods_availability_use}

Once the functionality of filtering payment methods *by the currency* is set up, no actions by the web service are required since the payment currency \(passed in the `payment_currency` parameter\) is a required parameter for invoking Payment Page. Filtering by this parameter will be carried out automatically.

Once the functionality of filtering payment methods *by the country* is set up, the web service needs to be configured in order to pass in the requests for opening Payment Page relevant country codes \(the customer's country is specified in the `region_code` parameter\), according [to the reference](en_pm_codes.md). If the country code is specified in the request, filtering by this parameter will be carried out automatically. If not, payment methods will be filtered by the country associated with an IP-address of the customer's device.

## Related links {#en_pp_methods_avalability_add_info}

The following articles can be useful when you work with the functionality of filtering payment methods:

-   [Arranging payment methods on the page](en_pp_methods_order.md)—the article with the information about the capability of ranking payment methods.
-   [Preselecting payment methods](en_PP__PreselectingPS.md)—the article with the information about selecting a particular payment method when invoking Payment Page.
-   [Payment method codes](en_pm_codes.md)—the reference with the list of codes for the supported payment methods.
-   [Methods](en_pm_about.md)—the section with the information about the payment methods that are supported within the platform.
-   [Country codes](en_country_codes.md)—the reference with the list of short letter codes for country names.
-   [Payment Page API specification](en_PP_Parameters.md)—the parameter specification for invoking Payment Page.



---

# Arranging payment methods on the page {#en_pp_methods_order}

An article about the capability of arranging payment methods on the form to be presented to the customer in the optimal order.

## Overview {#section_rr3_3cy_txb .section}

When processing payments via Payment Page, *dynamic* or *static* ordering of the payment method buttons can be applied on the payment method selection page.

Dynamic ordering is used by default. It implies that payment methods are arranged on the page according to their relevance for the current session of opening the payment form. The following data are factored in when calculating relevance:

-   the customer's location
-   the merchant's business type
-   the frequency of various payment methods selection within the project

**Note:** It is also important to mention that when mSDKs are used, payment methods are sorted based on the data received from mobile devices while in all other cases it is the data received from all other devices but mobile.

At the same time, if needed, you can choose to have payment method buttons arranged in a fixed order\(for instance, alphabetically\) on the payment method selection page. To set up this option, contact the technical support.

## Use cases {#section_s54_3cy_txb .section}

Here are several examples to compare the options.

-   If a customer from Portugal places an order on the website of the merchant with business operations in Europe, then applying the option of dynamic ordering arranges the methods from more relevant in Portugal for the merchant's business type and specific project \(Multibanco and Open Banking in Portugal\) to less relevant \(Astropay and Open banking in France\).
-   If a customer from France places an order on the website of the same merchant, then the methods are arranged from more relevant in France for the merchant's business type and specific project \(Open banking in France, Google Pay\) to less relevant \(Astropay, Open banking in Portugal, Multibanco\).
-   If static ordering is applied, then for both cases described above payment methods are arranged in a fixed order.

![](images/ecommpay/pp_methods_order_1.svg "Dynamic ordering when the customer is in Portugal")

![](images/ecommpay/pp_methods_order_2.svg "Dynamic ordering when the customer is in France")

![](images/ecommpay/pp_methods_order_3.svg "Static ordering")

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Saving customer payment data {#en_PP_saved_data .concept}

An article about the capabilities of saving and using the customer payment data when working with the payment form.

To ensure convenience and efficiency of the Payment Page user scenarios, you can implement the capability of storing customer payment credentials for subsequent use without prompting the customer to provide this data again. Customer payment credentials can be saved when customers make purchases or when their payment instruments are verified.Saved payment credentials are shown on the payment method selection page together with the details of cards for which tokens were generated.

Payment Page supports the following options for saving payment data:

-   always save customer payment data
-   never save customer payment data
-   ask customers about saving payment data

Additionally, you can limit the maximum number of saved payment instruments per customer.

If necessary, the customer can delete saved payment instruments in Payment Page. In case when the customer deletes a saved card that was used to register a COF purchase, the debiting of funds continues to take place. For details on cancelling a COF purchase, see [COF purchase registration](en_pp_recurring.md).

**Note:** To enable and configure the service contact technical support by email [support@ecommpay.com](mailto:support@ecommpay.com).

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Payments by using tokens {#en_PP_Payment_by_token .concept}

An article about the capability of using payment data tokens to reduce the number of steps in customer payment scenarios.

Payment Page supports performing fast payments by using bank card tokens.

While requesting to open a payment page you specify the active token of a customer bank card. The generated payment page opens with the filled bank card details \(except CVV\). To make a payment, the customer enters only CVV and confirms the payment amount by clicking **Pay**.

**Note:** When performing a payment by using a token the customer will not be able to select any other bank cardor payment account.

![](images/ecommpay/en_pp_payment_by_token.svg "Payment page with preselected card when performing a payment by token")

**Note:** The functionality is available in the Purchase mode.

**Note:** To enable and configure the service contact technical support by email [support@ecommpay.com](mailto:support@ecommpay.com).

## Parameters to pass {#section_wpx_yfk_5bb .section}

To perform a payment by token, specify the token in the account\_token parameter and the ID of a customer in the customer\_id parameter in the object or the URL.

For the full list of the supported parameters see [Payment Page API specification](en_PP_Parameters.md).

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Currency conversion {#en_pp_currency_conversion}

An article about the capability of processing payments via Payment Page in different currencies with currency conversion.

## Introduction {#section_whs_hw2_ngc .section}

The Ecommpay payment platform supports payments in multiple currencies with automatic conversion\(when payment amounts are recalculated according to the exchange rate between two currencies\). You can configure the following optionsto make payments more flexible and convenient:

-   Setting up [balances](en_glossary.md) in different currencies.
-   Configuring [payment methods](en_glossary.md) and [channels](en_glossary.md) in different operating currencies.
-   Allowing your customers to select the currency of the purchase in your web service or directly in Payment Page \([details](en_pp_currency_choice.md)\).

Using each of the aforementioned options can be limited due to the specifics of the way partners and providers operate, regional specifics, and other factors. However, in most cases these options let you adapt this functionality to your business model and use both local and global currencies efficiently.

For information about setup and use, refer to this and other articles on the documentation portal, or contact your Ecommpay account manager.

## Conversion scenarios {#section_sxy_3y2_ngc .section}

Processing a payment via the Ecommpay platform can involve four kinds of currency:

-   *Requested payment currency*—the currency specified by the merchantin the initial payment request.
-   *Actual operational currency \(can also be referred to as settlement currency\)*—the currency used in the platformfor processing the payment and determined on the basis of various factors.
-   *Payment instrument currency*—the currency of the customer’s payment instrumentused for making a payment.
-   *Balance currency*—the currency of the merchant’s balanceassociated with the payment.

If all these currencies are the same, no conversion is required. If at least one differs, conversion is necessary, since the payment cannot be completed otherwise.

![conversion_scheme](images/en_pp_conversion_gbp.svg)

For example, a customer in Poland pays with a card denominated in Polish zloty \([PLN](references/en/currencies/PLN.md)\) for a service in Norway. By default, the available payment channel supports Norwegian krone \([NOK](references/en/currencies/NOK.md)\), while the merchant's balance is in pounds sterling \([GBP](references/en/currencies/GBP.md)\).

If the merchant's integration does not have additional options configured, the payment requires double conversion:

-   For the customer, the payment amount is converted from [PLN](references/en/currencies/PLN.md) to [NOK](references/en/currencies/NOK.md) by the issuer.
-   For the merchant, the payment amount is converted from [NOK](references/en/currencies/NOK.md) to [GBP](references/en/currencies/GBP.md) by Ecommpay.

However, if in this integration there is an available payment channel in British pounds, then this payment can be processed in pounds, without conversion from the operational currency to the balance currency. If there is an available payment channel in zloty, then this payment can be processed in pounds, without conversion from the payment instrument currency to the operational currency. Thus, supporting payment channels and balances in different currencies allows for greater flexibility in payment processing and can eliminate the need for additional steps with currency conversion. At the same time, in the Ecommpay platform, there are also practical considerations regarding the use of multiple balances and the constraints that come into play when different payment methods, channels, and balances are involved.

When payments are processed, the currency conversion is performed automatically, as deemed necessary.Keep in mind that the actual operational currency is determined in the platform each time based on the request parameters, customer's preference for the payment currency \(if applicable\), project and payment method settings\(including the preferences for currencies and channels indicated by the merchant\), and the availability of payment channels.

In addition, currency conversion can also be performed on the side of the web service before the request is sent to the payment platform, with the use of the merchant's exchange rates and under their own terms and conditions.

## Choosing the currency {#section_ndp_qbf_ngc .section}

When working via Payment Page, you can decide on the way your customers will select the currency of the payment, and the options are as follows.

-   *Choosing the currency in the web service*—customers choose the currency they prefer before Payment Page is opened.Conversion is performed on the web service side. The selected currency becomes the *requested payment currency* and is processed accordingly by the platform. This option is available by default for all payment methods and currencies.
-   *Choosing the currency in Payment Page*—customers choose the currency they prefer directly in Payment Page\([details](en_pp_currency_choice.md)\). Conversion is performed on the Ecommpay side. The currency specified in the request remains the initial *requested payment currency*, while the currency chosen by the customer becomes the *selected payment currency* and takes priority for processing. By default, it also acts as the *actual operational currency* for the payment.This option is available only for some payment methods and supported currencies for these methods.

## Monitoring payments with currency conversion {#section_c2b_gcf_ngc .section}

To monitor the use of various currencies and currency conversion during payment processing, you can rely on various tools including:

-   Payment result callbacks \([details](en_platform_callbacks.md)\).
-   Consolidated registers and payment information tabs in the Dashboard interface \([details](en_dbl_payments.md)\).
-   Information about operations retrieved via the Data API \([details](en_dbl_using_api.md)\).
-   Financial statements.

Note that when conversion is performed by the Ecommpay payment platform, the applied exchange rates are determined dynamically based on the market data provided by specialised partner organisations. For any questions regarding these rates, applicable fees, or the use of conversion in specific cases, please contact your Ecommpay account manager.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Currency choice in Payment Page {#en_pp_currency_choice}

An article about the capability of letting customers choose payment currency that fits their needs in the payment form.

## Overview {#section_v54_bdt_whc .section}

In certain cases you may find it useful to give your customers a possibility to choose the payment currency that fits their needs directly in the payment form. When accepting payments via Payment Page, you can set up payment processing workflows where this capability is integrated seamlessly, with support for a wide range of available currencies, flexible configuration, and automatic currency conversion when necessary.

![](images/ecommpay/en_pp_conversion_1.svg "Selecting currency out of all available when paying with a card")

![](images/ecommpay/en_pp_conversion_2.svg "Selecting out of relevant currencies when paying with a card")

![](images/ecommpay/en_pp_conversion_3.svg "Selecting out of available currencies when paying with Google Pay")

With this capability, the currency that was specified in the request to open Payment Page is always shown as preselected. However, the customer can choose to pay in one of the other available currencies, in which case the customer is then shown the recalculated payment amount in the currency they selected and are able to confirm the payment in the selected currency.

Choosing the currency in the payment form is supported, first and foremost, for the globally accepted payment methods: Apple Pay, Google Pay andstandard card payments. If you have any questions regarding the integration, setup, and use of this functionality, refer to your Ecommpay account manager.

## Special aspects and limitations {#section_jjt_zht_whc .section}

When integrating and using the functionality of choosing the currency in the payment form, consider the following special aspects and limitations:

-   *Payment methods that support currency choice must be available for selection by button on the payment method selection page.*

    For instance, in case of the Apple Pay and Google Pay payments, this option is supported if the buttons to select these methods are shown on the payment method selection page.Then the payment method can be either preselected, by your specifying its code in the payment request, or selected directly in the payment form by the customer, following which the customer can select the currency. If these buttons are shown on the page to enter card details, it means these methods serve in the interface as complementary options to a standard card purchase and cannot be selected separately from card payments, and this currency selection option is not available.

-   *The customer selects the currency only out of those that are available. You can manage the availability of currencies for selection.*

    In general, available currencies encompass all currencies supported as operational for the merchant's project in question and also available for performing conversion within the initiated payment session. For card payments, the currency availability can be limited by filtering all available currencies. The options are as follows:

    -   Selecting currency out of all available.

        This option is supported for Apple Pay, Google Pay, and standard card payments.

    -   Selecting currency out of those relevant for the country where the card was issued \(determined by the card number\) or, if relevant currencies are not available, out of the remaining available currencies.

        For example, if the customer uses the card issued in Brazil, and the Brazilian real is supported as an operational currency for the project in question, the available currencies can be the initial currency specified in the request and the Brazilian real.

        This option is supported only for standard card payments, and when it is used, the list of available currencies is shown to the customer only after the card number has been entered.

    -   Selecting currency out of those relevant for the country where the card was issued \(determined by the card number\) or, if relevant currencies are not available, the option to choose the currency can be removed and the payment request currency can be used instead.

        For example, if the customer uses the card issued in Brazil, and the Brazilian real is not supported as an operational currency for the project in question, only the payment request currency can be shown for selection.

        This option is supported only for standard card payments, and when it is used, the list of available currencies is shown to the customer only after the card number has been entered.

    You can compile lists of available currencies for each project and can also decide on the option of filtering the available currencies for card payments. Thus, the list of available currencies can differ depending on the project, payment method, and payment instrument.

-   *Dollars, euros, or pounds sterling can be used as balance currencies.*

    If the customer selects to pay in euros, US dollars, or pounds sterling, and the payment is processed in the selected currency and the balances in the relevant currencies have been configured, the merchant receives the funds in this currency. In all other cases, the merchant receives the funds in US dollars.

-   *Currency conversion is performed with the use of exchange rates set by Ecommpay.*

    These rates are calculated by Ecommpay according to the market data provided by the speciliased partner services.To monitor payments with conversion, you can use different interfaces of the payment platform \([details](en_platform_payment_information_overview.md)\). You can also contact your account manager to learn more about exchange rates and the specifics of how they are applied.


## Workflow {#section_crb_rvt_whc .section}

You do not need to update your web service to support payment currency selection by the customer\(as far as standard processing workflows for payments of a specific type are concerned\). The following is a workflow of a one-step purchase that requires conversion to the currency selected by the customer.

![](images/en_pp_uml_conversion.svg)

1.  Payment Page sends to the payment platform the request to obtain informationabout available currencies and exchange rates required for currency conversion.
2.  The payment platform processes the request.
3.  The payment platform sends the information required for currency conversion to Payment Page.
4.  Payment Page displays the list of available currencies.
5.  The customer selects the currency and enters necessary details.
6.  Payment Page sends to the payment platform the request for paymentdenominated in the currency that the customer selected.

When the currency selected by the customer differs from the one specified in the payment request, payment result callbacks can contain \(if it has been configured\)the `sum_customer` object with the following parameters:

-   `amount`—the operation amount in the smallest units of the currency selected by the customer
-   `currency`—the code of the currency selected by the customer in ISO-4217 alpha-3

This information is used as complementary to the data about the amount and currency passed in the `operation` object:

-   `sum_initial`—the initial amount and currency of the request
-   `sum_converted`—the converted amount and currency that were actually used to perform the operation

The following is an example of the payment with a conversion operation in which `10.00 USD` are converted into `57.60 BRL` as the customer selected to pay in `BRL`, and the amount the customer actually paid is equal to `57.60 BRL`.

```language-json
{
    "payment":{
        "method":"card",
        "sum":{
            "amount":1000, // payment amount in the requested payment currency  
            "currency":"USD" // code of the requested payment currency
        },
        "id":"11006",
        "type":"purchase",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000",
        "description":""
    },
    "customer":{
        "id":"12"
    },
    "sum_customer":{
        "amount":5760, // amount in the customer selected currency
        "currency":"BRL" // code of the customer selected currency
    },
    "account":{
        "number":"541333******0019"
    },
    "project_id":42,
    "operation":{
        "created_date":"2022-06-23T13:32:02+0000",
        "request_id":"a23962a836e8e4-db4f1981d9-0006",
        "sum_initial":{
            "amount":1000, // operation amount in the requested payment currency
            "currency":"USD" // code of the requested payment currency
        },
        "sum_converted":{
            "amount":5760, // operation amount in the actual operational currency
            "currency":"BRL" // code of the actual operational currency
        },
        "code":"0",
        "message":"Success",
        "eci":"05",
        "provider":{
            "id":6,
            "payment_id":"1629803",
            "auth_code":"563253",
            "endpoint_id":6,
            "date":"2022-06-23T10:32:09+0000"
        },
        "id":682400942,
        "type":"sale",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000"
    },
    "signature":"BsGd0vcBQjd+aFl8ehEPRjf/eQUABow+VO+/xSG+lqKo6xHQ=="
}
```

## Setup {#section_fwh_jzt_whc .section}

To set up the functionality of currency conversion when the customer chooses the currency:

1.  With your Ecommpay account manager, discuss adding and setting up this functionality.Agree upon:
    -   which projects, payment methods, and relevant currencies are required.
    -   Whether you need the option to filter available currencies by the customer's card country.
    -   Whether testing is necessary.
2.  If you need testing, once you get notified by the Ecommpay specialists that the payment form is ready for being used in test mode, test this functionality, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the functionality has been added and fully set up.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Supporting sustainable payments {#en_pp_ekko_earth}

An article about the capability of adding the option to payment form workflows that allows contributing to environmental projects via the ekko partner service.

## Overview {#section_fgl_3d1_1gc .section}

When working via Payment Page, you can extend checkout scenarios by adding the option to make financial contributions to environmental projects via the specialised partner service of the [ekko](https://ekko.earth/) platform—right after the standard payment scenario steps have been completed. This capability empowers customers to make sustainable choices aimed at protecting the planet alongside their purchases and allows merchants to demonstrate their commitment to sustainability and generating positive environmental impact within their services.

![](images/ecommpay/en_pp_ekko_earth.svg "Including the carbon tracking option on the final page of the payment form")

While using this capability does not require you to expend any additional technical effort or pay any extra fees, it allows you to participate in environmental initiatives and helps increase customer loyalty and brand value.

## Special aspects and limitations {#section_i25_xt1_1gc .section}

When working with the sustainable payments capability, consider the following special aspects and limitations:

-   The functionality is supported only for the 5th generation Payment Page.
-   The functionality is available to customers at checkout if the initial payment is [a purchase](en_pp_purchase.md) or such action as [an authorisation hold](en_pp_purchase_auth.md) or [a registration of a COF payment](en_pp_recurring.md).
-   Customers can contribute to environmental initiatives using the payment methods supported both by Ecommpay and by the ekko service, regardless of which payment methods are available within the merchant’s project. Methods that can be used for sustainability payments include [standard card payments](en_pm_card_payments.md), [Apple Pay](pm_applepay.md), and [Google Pay](pm_googlepay.md).
-   Each contribution is processed as a separate payment—in the same currency used for the initial payment that was processed before the customer was redirected to the ekko service and outside the project through which the initial payment was made. This approach allows utilising the payment methods supported for sustainable payments and prevents merchant services from getting overloaded with additional data related to these contributions.
-   A sustainable payment is processed within a separate Payment Page session, with the payment form custom design by Ecommpay and ekko. In addition, the parameters of the project within which the initial payment was made do not apply to processing a subsequent contribution.
-   Customers receive notifications about processing of their contributions directly from the ekko service. If they have any questions about their sustainable payments, they can also be referred to ekko for more details.

To learn more about the specifics of working with this functionality, contact your Ecommpay account manager.

## Processing scenario {#section_y54_zt1_1gc .section}

Below is a user scenario of making a sustainable payment enabled by ekko via Payment Page.

1.  On the final page of the payment form, alongside the confirmation that the initial payment or action has been completed successfully, an additional panel is displayed to the customer with the option to proceed to the ekko service in order to make a contribution.
2.  The customer is redirected to the ekko service.
3.  The customer selects the desired contribution amount and is redirected to the payment form \(a new Payment Page session is initiated\).
4.  The customer is shown the payment form \(with custom design by Ecommpay and ekko\).
5.  The customer selects the payment method, enters the required details, and confirms making a contribution.
6.  The customer is shown the preloader page and then the payment complete page.
7.  The customer is redirected to the ekko service page showing the contribution confirmation and offering the option to enter an email address for an additional receipt.
8.  The customer receives a receipt at the provided email.

As with other payment scenarios, making a sustainable payment may require additional procedures such as the 3‑D Secure authentication \([details](en_PP_Additional.md)\). However, execution of these procedures does not require the merchant's web service to perform any further actions outside of the already established scope.

## Setup {#section_qsp_251_1gc .section}

To set up the functionality of sustainable payments:

1.  With your Ecommpay account manager, discuss and agree upon setting up this functionality for specific projects and whether testing is necessary.
2.  If you need testing, get notified by the Ecommpay specialists that the payment form is ready for being used in test mode, test this functionality, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the functionality has been added and fully set up.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Debt repayment {#en_PP_debt_repayments}

An article about the capability of using the payment form to accept loan repayments.

## General information {#section_knc_3mq_4mb .section}

*Debt repayment* is a type of purchase from the customer's card intended for payment of a loan or debt. This type of payment is available for merchants providing microfinance services with the category code `6012` or `6051`, and is also mandatory for MFIs that are registered in the United Kingdom \(for Mastercard payments\) or the European Union \(for Visa payments\).

Debt repayment can be made as a one-time purchase, registration of a COF payment, or card verification operation. If an MFI is registered in the United Kingdom \(for Mastercard payments\) or in the European region according to Visa regulations \(for Visa payments\) in addition to the required objects and parameters, the MFI account number and additional customer data must be specified in the request:

-   debt\_account—the merchant account number for debiting funds from the customer's card in order to repay the debt. Latin letters and numbers are allowed, the maximum length is 10 characters
-   customer\_first\_name—first name
-   customer\_last\_name—last name
-   customer\_day\_of\_birth—date of birth, in the DD-MM-YYYY format
-   customer\_zip—postal address code \(mandatory for the UK\).

This functionality is not available for payments with American Express cards.

If the parameter is not specified in the request, a callback containing this parameter is sent for additional payment information submission \(for more details, see [Submission of additional payment information](en_pp_clarification.md)\).

```language-xml
EPayWidget.run(
    { payment_id: '3936', 
      payment_amount: 1000, 
      payment_currency: 'EUR', 
      project_id: 200,
      debt_repayment: '897896541,
      customer_first_name: 'John',
      customer_last_name: 'Johnson',
      customer_zip: 'SW1W 0NY,
      customer_day_of_birth: '12-05-1990',
      customer_id: '1',
      signature: "PJkV8ej\/UG0Di8NN5...=="
    }
)
```

If the debt repayment is made by the registration of a COF payment—you do not need to pass additional parameters in requests for payment processing—they will be taken from the initial request for registration.

For more information about this functionality and how to enable it, refer to the Ecommpay key account manager.

## Mastercard restrictions {#section_jzh_kmq_4mb .section}

According to Mastercard requirements, this functionality is available to merchants from the United Kingdom only with the category code `6012`. For all other countries both `6012` or `6051` codes are available. It is prohibited to repay debts from credit and prepaid cards if the country of issue of the card and registration of the merchant is the United Kingdom.

## Visa restrictions {#section_gb2_lmq_4mb .section}

According to Visa requirements, merchants from the United Kingdom who accept payment of overdue debts must have the category code `6051`. In other cases and for all other countries both `6012` or `6051` codes are available. It is prohibited to repay debts from credit cards.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Limiting time for working with payment form {#en_pp_time_limit}

An article about the capability of setting the time limit for making a purchase within a single payment form invocation.

## Overview {#section_pk4_rgg_nmb .section}

During the work with Payment Page, it is possible to specify the date and time until which the customer can work with the paymentformto confirm the targeted action. This capability allows to control providing services to customers with regard to time and can be especially relevant in sales of tickets or clearance sales of goods.

The date and time allocated for working with the payment form are specified in requests for opening Payment Page, and for setting up this capability, there are no additional actions required. If the restriction is set, the Payment Page pages contain an additional information panel that displays:

-   the information about the time when the work with the form is set to be completed, in the format of `hh:mm`;
-   the information about the time that remains until the completion of the work with the form, with the use of the timer `mm:ss`;
-   the indicator that counts down the final five minutes of the whole time allocated for working with Payment Page.

**Note:** Note that the time allocated for working with the form cannot exceed 30 days from the moment when the request for opening Payment Page was sent. Otherwise the date and time specified in the request will be ignored and the time limit will not be applied.

## Usage scenario {#section_ctr_ghg_nmb .section}

On the customer side, purchase processing with the limited time of working with Payment Page looks as follows:

1.  On the merchant web service side, the customer confirms the purchase of the order and is redirected to the payment form.
2.  The customer performs the actions required for making the purchase and receives the result information.

    In case if the customer does not confirm the targeted action until the allocated time expires, the customer is notified about the time expiration on the next page of the payment form.


![](images/ecommpay/en_pp_time_limit_1.svg "1 — Opening payment form")

![](images/ecommpay/en_pp_time_limit_2.svg "2 a — Processing purchase")

![](images/ecommpay/en_pp_time_limit_3.svg "2 b — Declining purchase due to time expiration")

## Special aspects {#section_np3_qhq_5tb .section}

When using the capability of limiting the time of the work with Payment Page, consider the following aspects:

-   During the processing of separate payments, payment systemsor providers can require additional customer data—this can increase the time of working with the form \([details](en_pp_clarification.md)\).
-   The time allocated for working with the form within a separate payment is also relevant for making all retry attempts within this payment, regardless of their number \([details](en_PP_Try_Again.md)\).

## Request format {#section_pnk_grg_nmb .section}

To specify the time limit within which the customer can work with the form, pass the best\_before parameter with the date, time, and time zone in the format of `YYYY-MM-DDThh:mm:ss±hh` or `YYYY-MM-DDThh:mm:ss±hh:mm` in the request for opening Payment Page.The time allocated for working with the form cannot exceed 30 days from the moment when the request for opening Payment Page was sent.

```language-json

{  
    // required parameters for purchase processing
   "project_id": 42,
   "payment_id": "7654321777",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF...",

    // date and time when the work with the payment form is set to be completed—
    // 12 April 2021 10:15:30, GMT+3
   "best_before": "2021-04-12T10:15:30+03"  
 
}
```

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Specifying extended purchase data for subsequent merchant use {#en_pp_additional_data}

An article about the capability of capturing relevant purchase information via Payment Page for internal merchant use.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Introduction {#en_pp_additional_data_overview}

In addition to specifying required and provider-recommended parameters inpayment requests, merchants sometimes need to pass data that is related to specific payments and their statuses andthat can be subsequently used by merchantsat their discretion. For this purpose, the Payment Page API includes the parameters that allow passing various data in requests and receiving these data together with other information in final callbacks.

**Note:** When processing payments via Gate, you can use [similar capabilities](en_gate_additional_data.md).

## Specifying booking data {#en_pp_booking_data}

### Overview {#section_eqc_4gh_h1c .section}

The `booking_info` parameter allows you to keep track of booking information relevant to a certain payment and receive this information in callbacks from the payment platform. This capability can be applied in a wide range of use cases \(for example, to specify information about booking concert tickets\) and with sufficient flexibility as there are no restrictions by MCC \([Merchant Category Code, MCC](en_glossary.md)\). If you have questions concerning the use of this capability, refer to your Ecommpay account manager for more details.

The `booking_info` parameter can be used for processing almost all types of paymentsmade with cards, Apple Pay,Click to Pay, and Google Pay: it includes performing such actions as purchase processing, placing authorisation holds, registering unscheduled COF purchases, and payment instrument verification.

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` parameter containing information about the start and end dates of the booked service \(in the`start_date` and `end_date` parameters\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with Merchant Category Codes \(MCC\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

### Use case {#section_qkq_ryl_h1c .section}

Here is an example of a use case when a merchant in the music festival industry needs to:

-   collect and process data about music festival tickets booked by the customers.
-   Provide the company's employees with the timely access to such information about each customer.

For this purpose, the following workflow is set up:

1.  Each request for opening Payment Page sent from the web service contains booking information in the `booking_info` parameter. The value of this parameter is a string containing a Base64 encoded JSON object.

    The JSON object can include the following data.

    -   The `bookers` array with the information about the customers for whom the service is booked. Each element of this array contains:
        -   `first_name`—the name of the customer provided at the time of booking
        -   `last_name`—the last name of the customer provided at the time of booking
        -   `email`—the email provided at the time of booking
    -   The `items` array with the information about separate services included in the booking. Each element of this array contains:
        -   `description`—description of the service included in the booking
        -   `start_date`—starting date of the service included in the booking
        -   `end_date`—ending date of the service included in the booking
    -   Parameters with other details of the booking:

        -   `start_date`—starting date of the booked service
        -   `end_date`—ending date of the booked service
        -   `description`—a free-form description of the booked service
        -   `total`—the total cost of the booking
        -   `pax`—the number of people per booking
        -   `reference`—the booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service
        -   `id`—the identifier of the booking, unique in the merchant web service
        **Note:** Keep in mind that the standalone parameters `start_date` and `end_date` included in the JSON object are intended for specifying the starting and ending dates of the booking as a whole, while parameters `start_date` and `end_date` of the `items` array are intended for specifying the starting and ending dates of the separate services included in the booking.

        **Warning:** The value of parameters `total` and `pax` must be greater than `0`.

2.  When a relevant operation has been processed, the information specified in the `booking_info` parameter is passed to the merchant web service in the final callbackand can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the operation data.

### Setup {#section_j4j_r2n_h1c .section}

The capability of using the `booking_info` parameter in requests and receiving booking information in callbacks \(with standard format\) is available by default and does not require any specific setup.

### Data format {#section_wcl_w2n_h1c .section}

The `booking_info` parameter can be specified in requests for opening Payment Page as a string containing the Base64 encoded JSON object \(`booking_info`\) with the necessary booking parameters.

|Parameter|Description| |
|---------|-----------|--|
|`bookers`  
 array

|Array with the information about the customers for whom the service is booked|1|
|`first_name`  
 string

|Name of the customer provided at the time of booking|1-11|
|`last_name`  
 string

|Last name of the customer provided at the time of booking|1-21|
|`email`  
 string

|Email provided at the time of booking|1-31|
|`items`  
 array

|Array with the information about separate services included in the booking|2|
|`description`  
 string

|Description of the service included in the booking|2-12|
|`start_date`  
 string

|Starting date of the service included in the booking, in the `DD-MM-YYYY` format|2-22|
|`end_date`  
 string

|Ending date of the service included in the booking, in the `DD-MM-YYYY` format|2-32|
|`start_date`  
 string

|Starting date of the booked service, in the `DD-MM-YYYY` format|3|
|`end_date`  
 string

|Ending date of the booked service, in the `DD-MM-YYYY` format|4|
|`description`  
 string

|Free-form description of the booked service|5|
|`total`  
 integer

|Total cost of the booking. Must be greater than `0`|6|
|`pax`  
 integer

|Number of people per booking. Must be greater than `0`|7|
|`reference`  
 string

|Booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service|8|
|`id`  
 string

|Identifier of the booking, unique in the merchant web service|9|

```language-json
"booking_info": {
  "start_date": "12-08-2026",
  "end_date": "14-08-2026",
  "description": "Sideris music festival full pass",
  "total": 200000,
  "pax": 2,
  "bookers": [
     {
        "first_name": "William",
        "last_name": "Herschel",
        "email": "rsfellow@mail.com"
     },
     {
        "first_name": "Caroline",
        "last_name": "Herschel",
        "email": "salariedastronomer@mail.com"
     }
  ],        
  "items":[
     {
        "description": "VIP Arrival",
        "start_date": "12-08-2026",
        "end_date": "12-08-2026"
     },
     {
        "description": "Hotel",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "Concerts",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "VIP Departure",
        "start_date": "14-08-2026",
        "end_date": "14-08-2026"
     }
  ],
  "reference": "musicfestlink",
  "id": "83"
}
```

```
ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ==
```

```language-json
{
    "payment": {
        "date": "2024-01-24T06:24:45+0000",
        "method": "card",
        "id": "FESTIVAL_PASS_1781",
        "sum": {
            "amount": 0,
            "currency": "EUR"
        },
        "type": "purchase",
        "status": "refunded",
        "description": "FESTIVAL_PASS_1781"
    },
    "project_id": 111738,
    "customer": {
        "id": "musicaficionado_83"
    },
    "account": {
        "number": "551115******1822",
        "token": "7123ba1f24f16a115f3390a9",
        "type": "mastercard",
        "card_holder": "WILLIAM HERSCHEL",
        "expiry_month": "08",
        "expiry_year": "2030"
    },
    "booking info": \{    // Object with the booking information
        "start\_date": "12-08-2026",
        "end\_date": "14-08-2026",
        "description": "Sideris music festival full pass",
        "total": 200000,
        "pax": 2,
        "bookers": \[
          \{
            "first\_name": "William",
            "last\_name": "Herschel",
            "email": "rsfellow@mail.com"
          \},
          \{
            "first\_name": "Caroline",
            "last\_name": "Herschel",
            "email": "salariedastronomer@mail.com"
          \}
        \],        
        "items": \[
          \{
            "description": "VIP Arrival",
            "start\_date": "12-08-2026",
            "end\_date": "12-08-2026"
          \},
          \{
            "description": "Hotel",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "Concerts",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "VIP Departure",
            "start\_date": "14-08-2026",
            "end\_date": "14-08-2026"
          \}
        \],
        "reference": "musicfestlink",
        "id": "83"
    \},
    "operation": {
        "provider": {
            "payment_id": "0010000124258736",
            "auth_code": "",
            "endpoint_id": 414,
            "id": 414
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "id": 55386010114429,
        "type": "refund",
        "status": "success",
        "date": "2024-01-24T06:24:45+0000",
        "sum_initial": {
            "amount": 200000,
            "currency": "EUR"
        },
        "created_date": "2024-01-24T06:24:43+0000",
        "request_id": "abcaf52323381a-d988c158cc4b43046-00055387"
    }
}
```

## Specifying other extended purchase data {#en_pp_merchant_data}

### Overview {#section_thq_xq3_pzb .section}

The `merchant_data` parameter can be used for keeping track of extended information about the order, applying promotions and bonus points, and other relevant data.In addition, the value of this parameter can be combined with the information passed in the `payment_description` parameter and the receipt information passed in the `receipt_data` object. As a result, all necessary data can be provided in callbacks without passing certain pieces of information multiple times in different parameters.

### Use case {#section_fln_zq3_pzb .section}

Here is an example of a use case when a merchant in the video game industry needs to:

-   collect and process data about add-on services that the gamers purchase as they play.
-   Provide the company's employees with the timely access to such information about each customer.

Merchant specialists in charge of the integration inform the Ecommpay account manager about these requirements.As a result, the following workflow is devised and set up:

1.  Each request for opening Payment Page sent from the merchant web service contains information about the purchased services—passed as a JSON object in the `merchant_data` parameter.

    The `merchant_data` string includes the following:

    -   The `items` array in which each element contains the SKU \(`sku`\), the description \(`description`\), and the number of the purchased services \(`count`\).
    -   The `total_count` parameter with the total number of the purchased services or goods items.
    -   The `user_id` parameter with the internal identifier of the customer.
2.  When a payment has been processed, the information specified in the `merchant_data` string is passed to the merchant web service in the final callback and can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the payment data.

![](images/ecommpay/en_pp_additional_data.svg "Placing an order in the web service")

![](images/ecommpay/en_merchant_data_db.svg "Viewing information in Dashboard")

### Setup {#section_yfz_yq3_pzb .section}

To use the capability of passing information in the `merchant_data` parameter, contact your account manager. The capability is set up in the payment platform by the Ecommpay specialists who will subsequently inform you that it is ready to be usedand that the extended information is now available in callbacks and in the Dashboard interface.

### Data format {#section_lg1_cr3_pzb .section}

In requests for opening Payment Page to process payments, the data specified in the `merchant_data` parameter must be passed as a JSON object. However, because this parameter is a string \(string\), to pass the JSON object in it when using the HTTP POST method, you need to escape the `"` character \(quotation mark,U+0022\) by adding `\` \(backlash or reverse solidus,U+005C\) in front of it.It is necessary in order to distinguish on the level of programmatic interaction which quotation marks close the string and which quotations marks are part of the JSON contents within the string. At the same time, when sending HTTP GET requests, there is no need to use escape sequences if you pass a JSON object \(the string is going to be interpreted correctly in this case even without escaping\).

In final callbacks with payment results, the data specified in the `merchant_data` parameter is passed in the `data` parameter of the `merchant` object.

In the following examples, the contents of the parameter are split into several lines for the reader's convenience.

```language-json
"merchant_data": "{"items":[{"sku":"GM12-CC",
        "description":"10 Copper Coins","count":1},
        {"sku":"GM12-GC","description":"Golden Coin",
        "count":2}],"total_count":3,"user_id":"122"}"
```

```language-json
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"
```

```language-json
"merchant": {
        "data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" 
}
```



---

# Handling events in Payment Page {#en_pp_ui_monitoring}

An article about the capabilities of obtaining and processing the information about various interface events related to the payment form and customer actions in this form.

## Overview {#section_fhc_rmb_fhc .section}

When using a payment form, you may need to monitor customer interactions with the form, so that your web service can respond to different events in a timely and efficient manner. For example, if a payment form fails to load, the customer can be provided with an appropriate explanation, or if the customer abandons the order, they can be reminded to enter payment details to complete the purchase.

With Payment Page, you can use libraries from Ecommpay that support listening to events which occur in the front end of your web service and responding to them by executing JavaScript event handlers that are defined in the requests for opening Payment Page. Note that the information about events can only complement information obtained from [callbacks](en_platform_callbacks.md); hence, it is not recommended that you use event handlers exclusively as a replacement for callbacks.

## Use {#section_snr_rmb_fhc .section}

To implement event handling within Payment Page in your web service, you only need to complete technical steps \(that is, using this option does not require you to contact the Ecommpay technical support for additional assistance with this matter\).

Firstly, make sure to link the following libraries from Ecommpay to the front end of your web service.

``` {#codeblock_b13_c42_tgc .language-xml}
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
```

Secondly, configure your web service to process the data received from triggered event handlers according to the specifics of the web service and customer scenarios.For example, you may implement functions for updating the payment status on the checkout page or for accepting payments with card tokens.

Thirdly, in each request for opening Payment Page that requires listening to interface events, define necessary event handlers [from the table below](en_pp_ui_monitoring.md).Event handlers must be specified in JavaScript and placed after the list of required parameters and signature. You can add any number of functions to an event handler and use the `data` object that contains data associated with certain events \(not all event handlers support the `data` object\).

When testing the integration with the Ecommpay payment platform via Payment Page, you can log payment request identifiers in a browser console for the purpose of testing and debugging your web service and use the logged request identifiers for monitoring and analysing payment processing. The following is the example of the `onPaymentSubmitResult` event handler function that logs the `request_id` variable value to the browser console.

``` {#codeblock_sbr_twx_1hc .language-javascript .show_more}
EPayWidget.run({
    payment_id: 'payment_443',
    payment_amount: 1000,
    payment_currency: 'EUR',
    project_id: 57123,
    signature: 'YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV',
   
    **onPaymentSubmitResult: async function \(data\) \{
        console.log\(data.request\_id\);
    \}**
}, 'POST');
```

The following is the example of the `onResize` event handler function that is executed when the page contained in an iframe is resized.

``` {#codeblock_wh1_p42_tgc .language-javascript}
EPayWidget.run({
    payment_id: 'payment_443',
    payment_amount: 1000,
    payment_currency: 'EUR',
    project_id: 57123,
    signature: 'YWb6Z20ByxpQIjaCCsVIwVynXV',

    **onResize: function \(data\) \{
        site.resize\(\{
            frameWidth: data.width,
            frameHeight: data.height
        \}\);
    \}**
}, 'POST');

```

In this example, when the `onResize` event handler is triggered, it updates the iframe width and height based on the `frameWidth` and `frameHeight` values from the `data` object.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)

## Event handlers {#en_pp_ui_monitoring_handlers}

### Loading the form {#section_yyn_t42_tgc .section}

|`onLoaded`|Triggered when Payment Page is successfully loaded\(all UI elements are fully rendered and the Payment Page session is initialised according to the request parameters\).

 When using this event handler, you can measure the payment form load speed on a customer device.

 ``` {#codeblock_kvw_2dp_1hc .language-json}
{
"width":900,
"height":640
}
```

|
|`onFailLoading`|Triggered when Payment Page fails to load\(the Payment Page session cannot be initialised\).

 When using this event handler, you can check the parameters in the request for opening the payment form and then resend the request. You can reuse the same payment identifier if it is valid and has not been used within the project beforehand.

 ``` {#codeblock_sc5_y2p_1hc .language-json}
{
"message": "Application error",
"config":
    { 
        "customer_id": "1", 
        "frame_mode": "iframe",
        "payment_amount": "1000",
        "payment_currency": "EUR",
        "payment_id": "payment_443",
        "project_id": "57123",
        "signature": "YWb6Z20ByxpQIjaCCsVIwVynXV",
        "target_element": "iframe-holder"
    }
}
```

|

### Submitting payment information {#section_inz_z2p_1hc .section}

|`onPaymentMethodSelect`|Triggered when a customer selects a payment method. The event is raised whenever the customer switches between payment method tabs on the form.

 When using this event handler, you can record which payment method the customer has selected. The data includes the payment method name, the code of the payment type \(`1` for purchases, `2` for payouts\), and the payment method code \(according to [the reference](en_pm_codes.md)\).

 ``` {#codeblock_e3j_3fp_1hc .language-json}
{
"name":"Bank cards",
"payment_method_type":"1",
"payment_method_code":"card"
}
```

|
|`onWalletSelect`|Triggered when a customer selects saved payment data\(a card or another payment instrument\).

 When using this event handler, you can record which payment instrument the customer has selected \(based on masked details of this payment instrument\). If needed, this information can be used in your web service further on to initiate requests for payments with card tokens \([details](en_PP_Payment_by_token.md)\).

 ``` {#codeblock_rbq_kfp_1hc .language-json}
{
"code":"card",
"id":"37489",
"pan":"541333******0019",
"month":"12",
"year":"2028",
"type":"mastercard",
"pan_first6":"541333",
"pan_last4":"0019",
"expired":"0",
"cvv_required":"1",
"holder":"JOHN SMITH",
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"field_values":{
    "country":"",
    "phone":"",
    "email":"",
    "card[expiry]":"12/28",
    "card[holder]":"JOHN SMITH",
    "card[type]":"mastercard",
    "card[country]":"GB",
    "card[product_name]":"Mastercard Gold",
    "card[bank_name]":"Citibank",
    "recurring_enable":"0"
}
}
```

|
|`onWalletRemove`|Triggered when a customer selects to delete saved payment data\(a card or another payment instrument\).

 When using this event handler, you can record which payment instrument the customer has selected to delete \(based on masked details of this payment instrument\).

 ``` {#codeblock_l1s_nfp_1hc .language-json}
{
"code":"card",
"id":"37489",
"pan":"541333******0019",
"month":"12",
"year":"2028",
"type":"mastercard",
"pan_first6":"541333",
"pan_last4":"0019",
"expired":"0",
"cvv_required":"1",
"holder":"JOHN SMITH",
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"field_values":{
    "country":"",
    "phone":"",
    "email":"",
    "card[expiry]":"12/28",
    "card[holder]":"JOHN SMITH",
    "card[type]":"mastercard",
    "card[country]":"GB",
    "card[product_name]":"Mastercard Gold",
    "card[bank_name]":"Citibank",
    "recurring_enable":"0"
}
}
```

|
|`onPaymentSent`|Triggered when a customer confirms the payment \(after all required fields in the payment form have been filled\)and the preloader page is shown to the customer.

 When using this event handler, you can capture the time the customer spent interacting with Payment Page and then, if needed, set the time limit for working with the form \([details](en_pp_time_limit.md)\). You can also display the message that the web service is waiting for the payment result.

 The `data` object is not supported for this event handler.

|
|`onPaymentSubmitResult`|Triggered when the payment request is received in the Ecommpay platform.

 When using this event handler, you can save the identifier of the request for opening Payment Page and use it to monitor the payment status in the case of incidents, for example, when there is a loss of connection with the customer's device, or callbacks from Ecommpay are not delivered \(learn more about [callbacks](en_Gate_payment_status_request.md)\).

 ``` {#codeblock_t2z_sfp_1hc .language-json}

{
 "request_id": "bc4-5a032482802f-00002836"
}
```

|

### Redirecting the customer {#section_hzh_5fp_1hc .section}

|`onShowClarificationPage`|Triggered when the page to submit additional information is displayed to a customer \([details](en_pp_clarification.md)\).

 When using this event handler, you can record that additional data was requested from the customer and capture the event’s timestamp. Afterwards, you can check if the customer provides the required information \(use the `onSubmitClarificationForm` event handler\) and if the payment is completed with the `Success` status.

 The `data` object is not supported for this event handler.

|
|`onSubmitClarificationForm`|Triggered when a customer has submitted additional information.

 When using this event handler, you can capture the time the customer spent providing additional data and check if the payment is completed with the `Success` status. If you notice that the payments involving the use of the `onSubmitClarificationForm` event handler are frequently declined, it is recommended that you contact the Ecommpay technical support to extend the list of mandatory parameters for requests to open Payment Page or to use the procedure of submitting additional payment information on the form \([details](en_pp_clarification.md)\).

 The `data` object is not supported for this event handler.

|
|`onRedirectIframe`|Triggered when a customer is redirected from your web service to a third-party service in the iframe element \(according to the project settings and the request parameters; [details](en_PP_pm_redirect_mode.md)\).

 When using this event handler, you can capture the event’s timestamp when the customer is redirected to another service. Afterwards, you can check if the customer returns to Payment Page \(use the `onRedirectIframeComplete` event handler\) and if the payment is completed with the `Success` status. If you notice frequent disruptions in customer redirection between services during payment processing, it is recommended that you contact the Ecommpay technical support.

 The `data` object is not supported for this event handler.

|
|`onResize`|Triggered when an HTML page opened in the iframe element is resized.

 When using this event handler, you can determine the dimensions of the HTML page where the customer is redirected to. Then you can check if the original size of the iframe element allows the page to be displayed properly in it and, if needed, resize the iframe element.

 ``` {#codeblock_nqs_lgp_1hc .language-json}
{
"width":1080,
"height":660
}
```

|
|`onRedirectIframeComplete`|Triggered when a customer returns to Payment Page from a third-party service displayed in the iframe element.

 When using this event handler, you can capture the time the customer spent in the third-party service.

 The `data` object is not supported for this event handler.

|

### Displaying result information {#section_mk4_ngp_1hc .section}

|`onTokenizeSuccess`|Triggered when the final page is displayed with the message that the payment instrument has been saved \(according to the parameters of the request for opening the payment form in the `card_tokenize` mode\).

 When using this event handler, you can save the created token and use it in your web service.

 ``` {#codeblock_odk_jqp_1hc .language-json}
{
"general":{
    "project_id":57123,
    "customer_id":"1",
    "signature":"Lqj0B3ue5tG33F9NV
                   qkVbjXHXNZj3x1o/5q7r8/rY+O5MC64iW3k77tg=="
    },
"request":{
    "id":"a748130e0350895d71bd8154342e0c261e30e086-558
                   3739b323907d9d61a5ffbf4118afeec695552",
    "action":"tokenize",
    "status":"success"
},
"token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce",
"customer":{
    "ip_address":"102.129.155.0",
    "id":"1"
},
"token_created_at":"2025-09-28T11:25:30+0000",
"token_status":"active"
}
```

|
|`onCardVerifySuccess`|Triggered when the final page is displayed with the message that the payment instrument has been verified \(according to the parameters of the request for opening the payment form in the `card_verify` mode\).

 When using this event handler, you can record the information that the payment instrument was verified and proceed with the next steps \(for example, register a card token or initiate a payout\).

 ``` {#codeblock_hbf_r3j_dhc .language-json}

{
    "request_id": "bbeef4d51e6ae4aadcb86d-00003158",
    "transaction": {
        "id": 3157000012768,
        "date": "2025-10-29T14:15:02+0000",
        "type": "account_verification"
    },
    "payment": {
        "method": "card",
        "date": "2025-10-29T14:15:02+0000",
        "result_code": "0",
        "result_message": "Success",
        "status": "success",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "id": "EP1120-3e48",
        "cascading_with_redirect": false,
        "is_cascading": false,
        "remaining_refund": 0,
        "split_with_redirect": false,
        "method_id": 1,
        "provider_id": 3
    },
    "sum_real": {
        "amount": 0,
        "currency": "GBP"
    },
    "customer": {
        "id": "123"
    },
    "account": {
        "number": "424242******4242",
        "type": "visa",
        "id": 70256633,
        "card_holder": "HENRY FORD",
        "expiry_month": "12",
        "expiry_year": "2028"
    },
    "avs_result": "X",
    "rrn": "000047769105",
    "sum_request": {
        "amount": 0,
        "currency": "GBP"
    },
    "company": {
        "id": 1,
        "title": "My store"
    },
    "terminal": {
        "method_code": "card",
        "mode_code": "card_verify",
        "name": "v5"
    },
    "cashout_data": {
        "account_number": "424242******4242",
        "customer_first_name": "Henry",
        "customer_last_name": "Ford"
    },
    "general": {
        "project_id": 291451,
        "payment_id": "EP1120-3e48",
        "signature": "fZKqrch...3//pDDJUaJ8R/7Yi5A=="
    },
    "description": "",
    "operations": [
        {
            "id": 3157000013487,
            "type": "account verification",
            "status": "success",
            "date": "2025-10-29T14:15:02+0000",
            "processing_time": "2025-10-29T14:15:01+0000",
            "request_id": "12a469296f-00003158",
            "sum": {
                "amount": 0,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3,
                "payment_id": "17616663016501"
            }
        }
    ],
    "return_url": "https://mystore.com/redirect/au80n3l6krq80"
}

```

|
|`onCardVerifyFail`|Triggered when the final page is displayed with the message that the payment instrument has not been verified \(according to the parameters of the request for opening the payment form in the `card_verify` mode\).

 When using this event handler, you can record the information that the payment instrument was not verified, check the reason for decline, and display it to the customer.

 ``` {#codeblock_ij3_ylj_dhc .language-json}
{
    "sum_request": {
        "amount": 0,
        "currency": "GBP"
    },
    "request_id": "bbeef40ef99a6cd-00003158",
    "transaction": {
        "id": 3157000012768,
        "date": "2025-10-29T14:15:02+0000",
        "type": "account_verification"
    },
    "payment": {
        "method": "card",
        "date": "2025-10-29T14:15:02+0000",
        "result_code": "100",
        "result_message": "General decline",
        "status": "decline",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "id": "EP1120-3e48",
        "cascading_with_redirect": false,
        "is_cascading": false,
        "split_with_redirect": false,
        "method_id": 1,
        "provider_id": 3
    },
    "sum_real": {
        "amount": 0,
        "currency": "GBP"
    },
    "customer": {
        "id": "123"
    },
    "account": {
        "number": "424242******4242",
        "type": "visa",
        "card_holder": "HENRY FORD",
        "expiry_month": "12",
        "expiry_year": "2034"
    },
    "avs_result": "X",
    "rrn": "000047769105",
    "company": {
        "id": 1,
        "title": "My store"
    },
    "terminal": {
        "method_code": "card",
        "mode_code": "card_verify",
        "name": "v5"
    },
    "cashout_data": {
        "account_number": "424242******4242",
        "customer_first_name": "Henry",
        "customer_last_name": "Ford"
    },
    "general": {
        "project_id": 291451,
        "payment_id": "EP1120-3e48",
        "signature": "fZPTytEOwT1Z8...BB3//pDDJUaJ8R/7Yi5A=="
    },
    "description": "",
    "operations": [
        {
            "id": 3157000013487,
            "type": "account verification",
            "status": "decline",
            "date": "2025-10-29T14:15:02+0000",
            "processing_time": "2025-10-29T14:15:01+0000",
            "request_id": "70-18a296f-00003158",
            "sum": {
                "amount": 0,
                "currency": "GBP"
            },
            "code": "100",
            "message": "General decline",
            "provider": {
                "id": 3,
                "payment_id": "17617473016501"
            }
        }
    ],
    "return_url": "https://mystore.com/redirect/baun3l6krq80"
}

```

|
|`onPaymentSuccess`|Triggered when the final page is displayed with the message that the payment is completed.

 When using this event handler, you can record the information that the payment was completed and proceed to process the paid order and communicate with the customer if needed. You can also capture the total time of processing the payment.

 ``` {#codeblock_trr_lqp_1hc .language-json}
{
"sum_request":{
    "amount":1000,
    "currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
    "id":2000000004,
    "date":"2025-10-08T11:14:49+0000",
    "type":"purchase"
},
"payment":{
    "method":"card",
    "date":"2025-10-08T11:14:49+0000",
    "result_code":"0",
    "result_message":"Success",
    "status":"success",
    "is_new_attempts_available":false,
    "attempts_timeout":0,
    "id":"payment_443",
    "provider_id":3
},
"sum_real":{
    "amount":1000,
    "currency":"EUR"
},
"customer":{
    "id":"1"
},
"status":"success",
"account":{
    "number":"541333******0019",
    "type":"mastercard",
    "card_holder":"JOHN SMITH",
    "id":37489,
    "expiry_month":"12",
    "expiry_year":"2028"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
    "project_id":57123,
    "payment_id":"payment_443",
    "signature":"EjYXLJpvDBPtbwQSQ0ukti9B
                 Y1m73+0SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
    "id":2000000004,    
    "type":"sale",
    "status":"success",
    "date":"2025-10-08T11:14:49+0000",
    "processing_time":"2025-10-08T11:14:49+0000",
    "sum":{
        "amount":1000,
        "currency":"EUR"
        },
    "code":"0",
    "message":"Success"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
```

|
|`onPaymentFail`|Triggered when the final page is displayed with the message that the payment is declined.

 When using this event handler, you can record the information that the payment was declined, check the reason for decline, and display it to the customer. If needed, you can resend a request for opening Payment Page with a new payment identifier.

 ``` {#codeblock_xl5_mqp_1hc .language-json}
{
"sum_request":{
    "amount":1000,
    "currency":"EUR"
},
"request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024",
"transaction":{
    "id":2000000004,
    "date":"2025-10-08T11:14:49+0000",
    "type":"purchase"
},
"payment":{
    "method":"card",
    "date":"2025-10-08T11:14:49+0000",
    "result_code":"10106",
    "result_message":"expired",
    "status":"decline",
    "is_new_attempts_available":false,
    "attempts_timeout":0,
    "id":"payment_443",
    "provider_id":3
},
"sum_real":{
    "amount":1000,
    "currency":"EUR"
},
"customer":{
    "id":"1"
},
"status":"decline",
"account":{
    "number":"541333******0019",
    "type":"mastercard",
    "card_holder":"JOHN SMITH",
    "id":37489,
    "expiry_month":"12",
    "expiry_year":"2028"
},
"rrn":"000047769105",
"auth_code":"563253",
"general":{
    "project_id":57123,
    "payment_id":"payment_443",
    "signature":"EjYXLJpvDBPtbwQSQ0ukti9BY1m73+0
                   SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA=="
},
"description":"",
"operations":[{
    "id":2000000004,    
    "type":"sale",
    "status":"decline",
    "date":"2025-10-08T11:14:49+0000",
    "processing_time":null,
    "sum":{
        "amount":1000,
        "currency":"EUR"
        },
    "code":"10106",    
    "message":"expired"
}
],
"return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46"
}
```

|

### Closing the form {#section_od2_wgp_1hc .section}

|`onDestroy`|Triggered when Payment Page is closed before the payment result page is displayed.

 When using this event handler, you should take appropriate steps in the front end of your web service \(for example, notify the customer that the payment status is being checked\), check the current payment status \([details](en_Gate_payment_status_request.md)\), and decide on the subsequent course of action based on the payment status.

 The `data` object is not supported for this event handler.

|
|`onExit`|Triggered when Payment Page is closed after the payment result page is displayed\(according to the specified parameters\).

 When using this event handler, you can record that the Payment Page session was completed and proceed with the next steps in your web service. You may also capture the total time the customer spent interacting with the payment form.

 The `data` object is not supported for this event handler.

|



---

# Using dynamic merchant descriptor {#en_pp_descriptor}

An article about the capability of providing customers with information about merchants via issuer services.

## Overview {#section_u2p_3rk_mhc .section}

When Ecommpay acts as an acquirer, in compliance with the rules of card networksEcommpay shares merchant details with other parties involved in payment processing. These detailscan be used by each party at its discretion and can be specified in receipts and bank statements by issuers.

By default, merchant information isstatic and limited toagreed upon name of the merchant. However, the merchant can dynamically append additional detailsrelating to a particular paymentor other aspects of their business . These dynamic details can be included in the requests for opening Payment Pageand are only limited to the maximum string length and the permitted character set \(see [details](en_pp_descriptor.md#section_b3f_hvp_13c)\). For example, the merchant descriptor can include the merchant's name combined with a booking period \(`Cosmotour* 17-19 feb`\) or with the name of the reserved hotel \(`Cosmotour* MarsSuite`\).

![](images/ecommpay/en_gate_descriptor_2.svg "Adding booking period")

![](images/ecommpay/en_gate_descriptor_1.svg "Adding hotel name")

Flexible use of accurate and informative details makes it easier for customers to identify merchants and payments and allows merchants to improve user experience and reduce the risk of disputes.In the Ecommpay payment platform, dynamic descriptors are relevant for *card payments* \(including standard card payments and payments made with Apple Pay, Click to Pay, Google Pay, and Visa Instalments\) and such payment types as one-time and COF purchases, payouts, and payment instrument verification.

## Special aspects {#section_fhg_s3m_djc .section}

When working with merchant data, consider the following special aspects:

-   The primary purpose of the merchant descriptor is to help customers recognise payments they made and prevent unnecessary chargebacks.

    Hence, avoid ambiguous or potentially misleading information in the merchant descriptor. Focus on the information that enables the customer to identify both the merchant and each operation clearly. In particular, it is recommended that you use a familiar brand name together with a concise description of the goods or services related to the operation.

-   Requirements to the merchant descriptor can vary depending on the card network.

    Pay attention to such differences, at least regarding the supported formats \([details](en_pp_descriptor.md#section_b3f_hvp_13c)\).

-   The way merchant details are provided to users is determined by issuers.

    How merchant details will appear in receipts, bank statements, and other communication with the customer is determined by the rules of a specific issuer. As a result, merchant details may vary across issuers, different interfaces of the same issuer, and different operation types within a single interface. In particular, there may be differences due to processing different types of purchases ans payouts as well as Mastercard MoneySend and Visa Direct operations.


## Setup {#section_umd_gyr_djc .section}

The name of the merchant to be used as a default merchant descriptor is specified when the merchant is onboarded with the payment platform and, subsequently, can only be modified via the Ecommpay account manager.

To enable the use of the dynamic merchant descriptor, continue as follows:

1.  Coordinate with the Ecommpay account manager the roadmap of enabling the functionalityfor specific projects and the necessity for testing..
2.  If you need testing, get notified by the Ecommpay specialists that the capability is ready for being used in test mode,test this capability, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the capability has been added and fullyset up.

## Use {#section_okm_gyr_djc .section}

If you need to use the dynamic merchant descriptor, pass the corresponding parameter in the requests for opening Payment Page:

-   `merchant_descriptor` for purchases and payment instrument verification
-   `sender_descriptor` for payouts

Keep in mind that in cases when the values of the `merchant_descriptor` and `sender_descriptor` parameters do not conform to the required format \([details](en_pp_descriptor.md#section_b3f_hvp_13c)\), the platform can automatically correct them\(for example, by transliterating alphabetic characters and removing invalid non-alphabetic characters\). Such correction of values does not lead to declined payments. Also, note that the Ecommpay platform does not validatethe values of these parametersfor factual correctness, but this information can be analysed and subsequently used by the issuers. Merchants should therefore ensure that values provided in the `merchant_descriptor` and `sender_descriptor` parameters are both technically compliant and contextually accurate in every instance of use.

## Data format {#section_b3f_hvp_13c .section}

The maximum length of the merchant descriptor is determined by the card network. Mastercard sets a maximum length of 22 characters, while Visa sets a maximum length of 25 characters.Any characters exceeding these limits are truncated. Keep these limits and the allowed character requirements in mind when generating descriptions. The `merchant_descriptor` and `sender_descriptor` parameters can contain characters from the basic Latin alphabet, digits, a space character \(U+0020\) and the following symbols:

|`*`|U+002A|asterisk|
|`,`|U+002C|comma|
|`-`|U+002D|hyphen|
|`.`|U+002E|full stop|
|`=`|U+003D|equals sign|
|`_`|U+005F|underscore|

When generating the `merchant_descriptor` or the `sender_descriptor` parameter, use the agreed uponmerchant's name followed by additional details separated by an asterisk \(`*`\) and a space, ensuring compliance with the applicable string length restrictions. For example, if a 9-character name `Cosmotour` is used with a 2-character separator, the remaining string length available for additional details is 11 characters for Mastercard and 14 characters for Visa. This is enough for a value such as `Cosmotour* to the Moon`.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Sending receipts and notifications to customer {#en_PP_receipt_data .concept}

An article about the capability of informing customers about payment processing and related events via email notifications.

## Sending a receipt {#section_nkg_4ln_lhb .section}

If you need to send sales receipts to customers, you have to make sure that this functionality is enabled in the settings. You also have to make sure that all positions to be indicated in the receipt are passed in the payment request. When this functionality is added and configured, you can also decide on the set of languages available for forming receipts and choose the default language. In individual cases, a different language can be selected the same way as the language of the payment form—with the use of the `language_code` parameter.

The data for the receipt is passed as a JSON object which is encoded in Base64 and sent in the payment request in the receipt\_data parameter. The JSON object structure is given in the `[receiptdata](https://api-developers.ecommpay.com/api.html#/c2NoOjQwNTY3ODY2-receipt-data)` model in the Gate API.

## Example of the receipt data to be sent {#section_l5c_lft_lhb .section}

Initial JSON object:

```language-json
{  
   "receipt_data":{  
      "positions":[  
         {  
            "quantity":3,
            "amount":10000,
            "tax":18,
            "tax_amount":1800,
            "description":"Design frame"
         }
      ],
      "total_tax_amount":1800,
      "common_tax":18       
   }
}
```

The same data, encoded in Base64, to be sent to Payment Page in the payment request \(the contents of the parameter are split into several lines for the reader's convenience\):

```
receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAg
ICAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI
6MTgsCiAgICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiJEZXN
pZ24gZnJhbWUiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAsCiAgICA
gICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ"
```

For more information about sending receipts to customers, see the section [Sending notifications to customers](en_gate_receipts.md).

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)



---

# Customisation {#en_PP__design_customisation}

An article about the capability of customising the appearance of the payment form with the use of the Payment Page Designer in the Dashboard interface.

## Overview {#section_rz4_hbr_jgc .section}

When merchants work with Payment Page, they can use the standard design of the payment form developed and maintained by the Ecommpay specialists with the consideration of the most recent requirements and trends of the electronic payments industry. Along with that, each merchant can customise the appearance of the payment form to meet the specific needs of their projects using the **Payment Page Designer** in Dashboard. In order to use the **Payment Page Designer**, you need to have a Dashboard user account with the appropriate permissions \([learn more](en_dbl_roles_overview.md)\).

![](images/ecommpay/pp_designer_v5_1.svg "Standard design")

![](images/ecommpay/pp_designer_v5_2.svg "Customised design (1)")

![](images/ecommpay/pp_designer_v5_3.svg "Customised design (2)")

![](images/ecommpay/pp_designer_v5_4.svg "Designer interface (1)")

![](images/ecommpay/pp_designer_v5_6.svg "Designer interface (2)")

The interface of the **Payment Page Designer** supports a wide range of capabilities and allows flexible customisation of the payment form, both its standard edition and the [embedded mode edition](en_pp_microframe_solution.md). However, you should keep in mind that when the Payment Page design is customised, the responsibility for the potential negative effect of the introduced changes on the conversion rate is placed on the merchant. Therefore, any changes should be carefully prepared and analysed and, if necessary, you should be ready to revert to the proven standard design options.

If you have any questions or suggestions regarding the use of the **Payment Page Designer**, contact your Ecommpay account manager.

## Capabilities {#section_qzx_hbr_jgc .section}

Working with the Payment Page design options can require different procedures:

-   If you need to make simple modifications within one project, then you can use *the single style setup*.
-   If you need to fine-tune the design with various styles that determine the look and feel of the form within one or several projects, then you can *configure multiple styles* using different styles for different use cases.

Each of these options is described in the sections that follow. In each case, when configuring the standard edition of Payment Page, you can:

-   Add a logo or any other header image and position it on the form.
-   Hide the Ecommpay logo used as a primary logo \(if it has not been replaced in the Payment Page Designer\) and as a logo in the credit line at the bottom of the form.
-   Add a background colour or image to the payment information panel.
-   Change colours of the main elements on the form.
-   Set the visibility of the payment information panel for different options of invoking the form.
-   Add a background colour or image to the payment form.
-   Emulate the work of different pages of the payment form when different options of invoking the form are used

When configuring Payment Page in the embedded mode, you can change colours of the main elements on the form and emulate the work of the form using these colours.

**Parent topic:**[Payment Page](en_PP_about.md)

## Single style setup {#en_pp_single_style_setup}

To configure a single style on the basis of the standard Payment Page design for a specific project, you should:

1.  Open the designer.

    In Dashboard, open the **Projects** section, select the project you need, and switch to the **Payment Page Designer** tab.

2.  Create a design style.

    To add a style, click ![the plus button](images/universal/dbl/icon_add1.svg) in the top left corner, name the new style in the dialogue box that opens, and click **Create**.

3.  Configure design settings.

    Use the tools located on the tools panel on the left side of the designer.

    ![](images/ecommpay/pp_designer_v5_5.svg "Designer interface: 1—tools panel; 2—form preview area")

4.  Preview the design of the payment form.

    For this, emulate the Payment Page behaviour in different situations: use the **Preview layout** drop-down list to select pages of the payment form and switch between different Payment Page display modes \(**Redirect**, **Popup**, **iFrame**, **Mobile**, and **Microframe**\) with the corresponding buttons.

5.  Save or apply design style settings.

    To achieve this:

    1.  Click **Save style** at the top of the tools panel \(if you only need to save new style settings\) or **Save and apply** at the bottom of the tools panel \(if you also need to apply the new style settings\).
    2.  Make sure you can see the notification that informs you that the design style has been saved \(and applied, if relevant\) for this project.

Once the changes have been applied, the new design style will be used for all Payment Page sessions of the target project. You can further modify or switch it to a different one using these instructions.

## Multiple styles setup {#en_pp_multiple_styles_setup}

### Overview {#section_rtr_kxp_fdc .section}

When you need to set up and use different design styles of the payment form for different scenarios within one or several projects, you can use the capabilities of configuring *interface models* and *styles*. To do so effectively, you need to understand what the Payment Page design involves and what you can do with its separate elements.

Each version of the Payment Page design is based on the combination of an interface model and a style. The interface model specifies the composition, size, placement, and colours of various elements while the style can additionally determine the look of certain images and colours used on the form. Only one interface model and one style can be applied to the opening of the payment form at a time.

If simultaneous support of different design styles is needed for different situations, you can configure each version and specify it when invoking the payment form. Note that each style can be used for only one project in which it was created.

Overall, to configure multiple styles of the Payment Page design, the merchant can do the following:

-   *Arrange and use the combination of projects that the merchant needs.*

    All actions to set up this combination in the payment platform are carried out by the Ecommpay specialists in accordance with the merchant's requirements.

-   *Coordinate the use of the necessary interface models for specific projects.*

    As a rule, the Payment Page design is based on the most recent version of the basic interface model developed by Ecommpay. At the same time, it is possible to coordinate with the Ecommpay account manager the use of other interface models for specific cases.

-   *Create, set up, and apply required design styles to specific projects.*

    These capabilities are fully available when the merchant works with the most recent version of the basic interface model developed by Ecommpay and can be partially or fully unavailable when the merchant works with other interface models. Working with design styles is described in the following section.


### Special aspects {#section_lsn_xcr_jgc .section}

You can work with the design styles in Dashboard using the designer tool that you can access in the **Payment Page Designer** tab of the **Projects** section.

Note the following special aspects of using the **Payment Page Designer**:

-   It does not allow switching between projects in the process of configuration. To modify design styles for specific projects, open the designer for each project individually.
-   It does not support simultaneous work on multiple design styles and does not allow changing styles in bulk. If you need to work with multiple styles at the same time, open and use the designer in different browser tabs.
-   It does not support simultaneous work on the same design style by multiple users. Therefore, in order to prevent conflicts and loss of unsaved changes, avoid situations when changes are made to the same style at the same time on different devices.

## Working with design styles {#en_pp_working_with_stylesv5}

### Overview {#section_x5v_cbq_fdc .section}

You can work with the design styles of the Payment Page using the **Payment Page Designer**. Since modifying the design styles can significantly influence the user experience and payment processing, you can work with the **Payment Page Designer** only if you have a user account in Dashboard with the appropriate permissions \([learn more](en_dbl_roles_overview.md)\).

To open the designer, go to the **Projects** section of the Dashboard interface, select the project you need and switch to the **Payment Page Designer** tab. If you need to work with several design styles, you can use the designer in several browser tabs.

**Warning:** The **Payment Page Designer** does not support simultaneous work on the same design styles. Therefore, in order to prevent conflicts and loss of unsaved changes, avoid situations when changes are made to the same style at the same time on different devices.

### Special aspects {#section_l3n_js5_2dc .section}

If the you use more than one project of interaction with the payment platform, keep in mind the following special aspects of working with the **Payment Page Designer**:

-   A custom design style can be used only within one project.

    To apply the same design style to different projects, you need to create and configure a style for each project individually.

-   The **Payment Page Designer** does not allow switching between projects in the process of configuration.

    To modify design styles for specific projects, you have to open the designer for each project individually \(via the **Projects** section\).


### Adding a style {#section_nbq_ss5_2dc .section}

To add a design style,

1.  Click ![the plus button](images/universal/dbl/icon_add1.svg) in the top left corner of the designer.
2.  Name the new style in the dialogue box that opens and, if you need to apply the style when saving it, enable **Apply after saving**.
3.  Confirm the creation of the new style by clicking **Create**.
4.  Make sure that the designer interface shows the page of the created style and its name is specified in the **Choose style** drop-down list.

### Making changes to the style {#section_wdz_gt5_2dc .section}

To introduce changes to a design style:

1.  Select the style you need in the **Choose style** drop-down list.
2.  Make changes using the tools located on the tools panel of the designer.
3.  If necessary, preview the style [to check](en_PP__design_customisation.md#section_awn_vxs_fdc) that the introduced changes are accurate and consistent.
4.  Save or apply design style settings.

    To achieve this:

    1.  Use one of the two saving options listed in the dialogue box that opens:
        -   To save the new style settings without applying—click **Save style** at the top of the tools panel.
        -   To save and apply the new style settings—click **Save and apply** at the bottom of the tools panel.
    2.  Make sure you can see the notification that informs you that the design style has been saved.

To undo changes that have been made to the style, you can use one of the following options:

-   To undo all changes that were made but not saved since the most recent save, close the designer window by clicking **Back to Dashboard** in the top right corner or refresh the browser tab currently in use.
-   To undo all changes that were made to the style and revert it back to the default style settings, click the link **Reset to defaults** located under the drop-down list with all styles.

    **Note:** When the style is being reset, you will not be asked to confirm it. Hence, if you need to cancel the reset, close the designer window without saving any changes that were made.


### Previewing the style {#section_awn_vxs_fdc .section}

To preview how the payment form is going to be displayed with the specific design style applied in various scenarios, select the style you need in the **Choose style** drop-down list and emulate the required Payment Page behaviour. For this, you can use:

-   **Preview layout** drop-down list—to select the page of the payment form.
-   **Redirect**, **Popup**, **iFrame**, **Mobile**, and **Microframe** buttons—to switch between the Payment Page display modes.
-   Specific page of the payment form—to check that the fields can be filled in as expected.

Keep in mind that not all payment methods and pages of the payment form can be available for the preview mode, while the Payment Page behaviour can be emulated only for certain elements on the pages that can be previewed.

### Applying the style {#section_yv1_xxs_fdc .section}

To ensure that a certain style is used for the specific project, you should:

1.  Select the style you need from the drop-down list.
2.  Click **Save and apply** at the bottom of the tools panel.
3.  Make sure you can see the notification that the style has been applied.

**Note:** When you need to use multiple styles within one project in addition to the style that is set as default, each request for opening Payment Page with an additional style must contain the identifier of this style in the `style_id` parameter. The style identifier is a number and is put on the right of the style name after the `#` character, for example `Custom_red_style #6123`.

### Deleting the style {#section_w4g_xxs_fdc .section}

To delete a design style, you should:

1.  Select this style in the **Choose style** drop-down list.
2.  Click ![the trashcan button](images/universal/dbl/icon_trashbean2.svg) on the right of the style name.

    ![](images/universal/dbl/all_dbl_pp_designer_dropdown_list_of_styles.svg)

3.  Confirm by clicking **Delete** in the dialogue box that opens.
4.  Make sure you can see the notification that the style has been deleted.

Keep in mind that when you delete the style currently in use as default for the specific project \(which is indicated by the `current` sign next to the style's name\), the next design style on the list will be set as default. If there are no other styles on the list, the Payment Page design will be reverted to the standard style. In this case, if you need to set another style as default, you need to [apply](en_PP__design_customisation.md#section_yv1_xxs_fdc) it for this project.



---

# Payment Page API specification {#en_PP_Parameters}

An API specification with the description of data structures used in requests for opening Payment Page.

This article describes parameters used to open Payment Page, including basic information about them and links to related articles, which contain descriptions of the parameters' functionality and set out possible scenarios for their use.

Parameters marked in this list as required must be included in all Payment Page callsintended to process payments. In the Card Tokenize mode, the following parameters are *not* required: `payment_amount`, `payment_currency`, `payment_id`.

Parameters marked in this list as optional can be used as additional parameters for specific projects and payment methods.Moreover, the inclusion of some parameters is recommended in order to avoid the customer being subjected to the 3‑D Secure authentication procedure \(i.e., undergo authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\) and having to provide [additional payment information](en_pp_clarification.md), as well as for other improvements to custom scenarios and the general functionality of the payment form.

If you have any additional questions about whether specific parameters are required or recommended for different individual use cases, consult the existing documentation and the Ecommpay technical support specialists.

|Parameter|Description|
|---------|-----------|
|`account_token`  
 string, optional

|Payment instrument token.

 Consists of an identifier obtained for a specific payment instrument from the payment platform when data for that instrument is saved. Can be used to perform payments using that saved data \(i.e., when [making a purchase](en_PP_Payment_by_token.md)\).

 Example: `42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021`

|
|`avs_post_code`  
 string, optional

|The postal code of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Example: `WS13 6LG`

|
|`avs_street_address`  
 string, optional

|The address of the customer to be used in the [Address Verification Service](en_PP_avs.md) check.

 Consists of a house number and a street name.

 Example: `4 Breadmarket Street`

|
|`baseUrl`  
 string, optional

|The base URL used to open the payment form.

 Must be specified whena root address different from the default one \(https://paymentpage.ecommpay.com\) has been approved by the Ecommpay account manager, in cases where the address needs to be provided explicitly.

 Example: `https://cosmopage.site.com`

|
|`best_before`  
 string, optional

|The date and time in the specified timezone until which the customer is able to use the payment form to confirm their targeted action \(see [this article](en_pp_time_limit.md)\).

 Should be specified as follows: `YYYY-MM-DDThh:mm:ss`±`hh` or `YYYY-MM-DDThh:mm:ss`±`hh:mm`. The time allocated for working with the form cannot exceed 30 days from the moment when the request for opening Payment Page was sent.

 Example: `2024-04-26T13:50:37+00`

|
|`billing_address`  
 string, optional

|The house number\(including any additional parts of the address such as building indicators and apartment numbers\) andthe name of the street in the customer's billing address.

 When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Example: `33 Store Street`

|
|`billing_city`  
 string, optional

|The name of the city in the customer's billing address.

 When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Example: `London`

|
|`billing_country`  
 string, optional

|The country code in the customer's billing address.

 Specified in the ISO 3166-1 alpha-2 format. When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Pattern: `^[A-Z]{2}$`.

 Example: `GB`

|
|`billing_postal`  
 string, optional

|The postal code in the customer's billing address.

 When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Example: `BR1 1AA`

|
|`billing_region`  
 string, optional

|The name of the region\(i.e., state, province, or other administrative division type\) in the customer's billing address.

 When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Example: `Greater London`

|
|`billing_region_code`  
 string, optional

|The recipient's country subdivision code \(state, province, region, or territory\). The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. This parameter should be specified in requests where the `billing_country` parameter is also specified.When the parameter is passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 Pattern: `^[0-9A-Z]{1,3}$`.

 Example: `DOR`

|
|`booking_info`  
 string, optional

|Booking information tracked by the web service.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. Can be used to record and track relevant data about payments rendered for services by various organisations \(see [this article](en_pp_additional_data.md)\).

 -   `bookers`, array—the array with the information about the customers for whom the service is booked. Each element of this array contains:
    -   `first_name`, string—the name of the customer provided at the time of booking
    -   `last_name`, string—the last name of the customer provided at the time of booking
    -   `email`, string—the email provided at the time of booking
-   `items`, array—the array with the information about separate services included in the booking. Each element of this array contains:
    -   `description`, string—description of the service included in the booking
    -   `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—starting date of the service included in the booking
    -   `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—ending date of the service included in the booking
-   `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—starting date of the booked service
-   `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—ending date of the booked service
-   `description`, string—a free-form description of the booked service
-   `total`, integer—the total cost of the booking
-   `pax`, integer—the number of people per booking
-   `reference`, string—the booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service
-   `id`, string—the identifier of the booking, unique in the merchant web service

 ``` {#codeblock_t2l_mzm_phc .language-json}
"booking_info": {
  "start_date": "12-08-2026",
  "end_date": "14-08-2026",
  "description": "Sideris music festival full pass",
  "total": 200000,
  "pax": 2,
  "bookers": [
     {
        "first_name": "William",
        "last_name": "Herschel",
        "email": "rsfellow@mail.com"
     },
     {
        "first_name": "Caroline",
        "last_name": "Herschel",
        "email": "salariedastronomer@mail.com"
     }
  ],        
  "items":[
     {
        "description": "VIP Arrival",
        "start_date": "12-08-2026",
        "end_date": "12-08-2026"
     },
     {
        "description": "Hotel",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "Concerts",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "VIP Departure",
        "start_date": "14-08-2026",
        "end_date": "14-08-2026"
     }
  ],
  "reference": "musicfestlink",
  "id": "83"
}
```

 ``` {#codeblock_gt2_yzm_phc}
ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ==
```

|
|`card_holder`  
 string, optional

|The first and last name of the payment card holder.

 Data specified in this parameter can be used to fill in the corresponding fields on the payment form in advance—this data can then still be edited by the customer—and should be spelled as specified on the card and adhere to the rules for specifying names \(see [this article](en_faq_payment_processing.md#section_dbx_kby_t1c)\).

 Pattern: `^[\p\{L}\p\{M}\s\-\'.]{1,255}$`.

 Example: `John Doe`

|
|`close_on_missclick`  
 integer \(boolean\*\), optional

|Indicator that specifies the action to be taken if the customer clicks outside of the borders of a payment form opened in a [modal window](en_PP_method_ModalWindow.md).

 Should be specified for calls that make use of a modal window. Can have one of the following values:

 -   `0`—do not close the payment form \(used by default\),
-   `1`—close the form.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md)\), this parameter can be specified as a boolean value and set to either `false` or `true`.

 Example: `1`

|
|`css_modal_wrap`  
 string, optional

|Indicator for an additional CSS class to wrap the payment form inside of a modal window.

 Should be specified for calls that make use of a modal window.

 Example: `CosmoshopModal`

|
|`customer_address`  
 string, optional

|The name of the street and the house number\(including any additional parts of the address such as building indicators and apartment numbers\) in the customer's address, separated by a comma.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Main Street, 12`

|
|`customer_account_info`  
 string, optional

|Information about the customer's account and contact detailsobtained by the web service.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include the `customer` object containing various combinations of elements from the list of supported data. When passed for card purchases, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 -   `address_match`, string—indicates whether the customer's billing address matches the address specified in the `shipping` object:
    -   `Y`—addresses match
    -   `N`—addresses do not match
-   `home_phone`, string—the customer's home phone number, contains between 4 and 24 digits
-   `work_phone`, string—the customer's work phone number, contains between 4 and 24 digits
-   `account`, object—the object with the customer's account information kept on file by the merchant:
    -   `activity_day`, integer—number of payment attempts in the last 24 hours, 3 characters maximum
    -   `activity_year`, integer—number of payment attempts in the last 365 days, 3 characters maximum
    -   `additional`, string—additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters
    -   `age_indicator`, string, `^0[1-5]$`—number of days since the customer account was created. Possible values:
        -   `01`—guest checkout
        -   `02`—the account was created at the moment of making a payment
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `auth_data`, string—additional login information in free text, can contain up to 255 characters
    -   `auth_method`, string, `^(0[1-4]|0[1-4][1-6])$`—indicates how the customer was authenticated during their most recent login to the web service. Can have one of the possible values:
        -   for standard card payments:
            -   `01`—no authentication
            -   `02`—logging in with authentication data kept on file by the merchant
            -   `03`—logging in with the federated identity credentials \(for example, Google Account or Facebook ID\)
            -   `04`—logging in with the use of FIDO authenticator \(Fast Identity Online\)
    -   `auth_time`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format
    -   `change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format
    -   `change_indicator`, string, `^0[1-4]$`—number of days since the most recent change to the account, except for the password change or password reset. Possible values:
        -   `01`—the account was updated on the day when the payment was made
        -   `02`—fewer than 30 days
        -   `03`—between 30 and 60 days
        -   `04`—more than 60 days
    -   `date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—the account creation date in the `DD-MM-YYYY` format
    -   `pass_change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent password change or reset in the `DD-MM-YYYY` format
    -   `pass_change_indicator`, string, `^0[1-5]$`—number of days since the most recent password change or reset. Possible values:
        -   `01`—password was not changed or reset
        -   `02`—password was changed or reset on the day when the payment was made
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `payment_age`, string, `^\\d{2}-\\d{2}-\\d{4}$`—card record creation date in the `DD-MM-YYYY` format
    -   `payment_age_indicator`, string, `^0[1-5]$`—number of days since the payment card details were saved to a customer's account. Possible values:
        -   `01`—guest checkout
        -   `02`—card details were saved on the day when the payment was made
        -   `03`—fewer than 30 days
        -   `04`—between 30 and 60 days
        -   `05`—more than 60 days
    -   `provision_attempts`, integer—number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum
    -   `purchase_number`,—number of purchases made via the customer's account in the last 6 months, 4 characters maximum
    -   `suspicious_activity`, string, `^0[1-2]$`— indicates the presence of suspicious activity. Possible values:
        -   `01`—no suspicious activity detected
        -   `02`—suspicious activity detected

 ```language-json
{ 
  "customer":{ 
    "address_match":"Y",
    "home_phone":"442055526608",
    "work_phone":"442055537709",
    "account":{ 
      "additional":"gamer12345",
      "age_indicator":"01",
      "date":"01-10-2022",
      "change_indicator":"01",
      "change_date":"01-10-2022",
      "pass_change_indicator":"01",
      "pass_change_date":"01-10-2022",
      "purchase_number":12,
      "provision_attempts":16,
      "activity_day":22,
      "activity_year":222,
      "payment_age_indicator":"01",
      "payment_age":"01-10-2022",
      "suspicious_activity":"01",
      "auth_method":"01",
      "auth_time":"01-10-202213:12",
      "auth_data":"login_0102"
    }
  }
}
```

 ```
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====
```

|
|`customer_account_number`  
 string, optional

|The identifier assigned to the customer's account by the payment system.

 May be required when using specific payment methods\(e.g., [Neteller](pm_neteller.md) and [OVO Wallet](pm_ovo.md)\). Depending on the particular method, may consist of an e-wallet identifier, an email address, a phone number, or a different kind of identifier.

 Example: `example@mail.com`

|
|`customer_birthplace`  
 string, optional

|The name of the customer's birthplace\(e.g., town, city, or other settlement type\).

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `London`

|
|`customer_city`  
 string, optional

|The name of the place of residence \(e.g., town, city, or other settlement type\) in the customer's address.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `London`

|
|`customer_country`  
 string, optional

|The country code in the customer's address.

 Specified in ISO 3166-1 alpha-2 format.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Pattern: `^[A-Z]{2}$`.

 Example: `GB`

|
|`customer_day_of_birth`  
 string, optional

|The date of birth of the customer.

 Consists of a string specified in `DD-MM-YYYY` format.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Pattern: `^\\d{2}-\\d{2}-\\d{4}$`.

 Example: `12-12-1990`

|
|`customer_email`  
 string, optional

|The email address of the customer.

 The length of the string cannot be more than 255 characters. The string consists of a local-part and a domain name, separated by the "@" symbol. Required for purchases made using a payment card if the `customer_phone` parameter is not specified and the customer is not provided an opportunity to specify their phone number themselves \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `helen@example.com`

|
|`customer_first_name`  
 string, optional

|The first name of the customer.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Jane`

|
|`customer_id`  
 string, required

|The identifier assigned to the customer within the scope of the project\(specified in `project_id`\).

 Each web service account should be linked to only one identifier and vice versa. This requirement is intended to address various risks and fraudulent operations.

 Example: `customer_112`

|
|`customer_last_name`  
 string, optional

|The last name of the customer.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Smith`

|
|`customer_middle_name`  
 string, optional

|The middle, second, or patronymic name of the customer.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Mary`

|
|`customer_mpi_result`  
 string, optional

|Information about the customer's most recent authentication via the 3‑D Secure protocol.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. When passed for card purchases, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 -   `mpi_result`, object—object that contains information about the previous authentication attempt of the customer:
    -   `acs_operation_id`, string, `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`—the identifier that the issuer assigned to the previous operation of the customer and returned in the `acs_operation_id` parameter of the callback with payment processing result. Can contain up to 36 characters.
    -   `authentication_flow`, string, `^0[1-2]$`—the flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the `authentication_flow` parameter returned in the callback with payment processing result.

Possible values:

        -   `01`—frictionless flow
        -   `02`—challenge flow
    -   `authentication_timestamp`, string, `^\\d{12}$`—date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result.

 ```language-json
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
```

 ```
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0===
```

|
|`customer_phone`  
 string, optional

|The phone number of the customer.

 Generally, should include the country code; however, some cases do not require a country code to be specified.

 Should contain between four and 24 digits. If a particular project and payment method allow for the inclusion of punctuation marks and special characters in the phone number, the parameter can contain such characters in those cases; this is usually specially arranged beforehand.Required for purchases made using a payment card if the `customer_email` parameter is not specified and the customer is not provided an opportunity to specify their email address themselves \(see [this article](en_PP_Gathering_customer_data.md)\).

 Pattern: `^[0-9]{4,24}$`.

 Example: `443031237300`

|
|`customer_security_code`  
 string, optional

|The customer's purchase confirmation code.

 Some payment methods may require this parameter\(depending on the methods themselves\).

 Example: `852923`

|
|`customer_shipping`  
 string, optional

|Information about the delivery of a product or a service rendered to the customer.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. When passed for card purchases, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 -   `shipping`, object—object with shipping details:
    -   `address`, string—shipping address, can contain up to 150 characters.
    -   `address_usage`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date when the specified shipping address was used for the first time, in the `DD-MM-YYYY` format.
    -   `address_usage_indicator`, string, `^0[1-4]$`—number of days since the specified shipping address was used for the first time. Possible value:
        -   `01`—first-time use
        -   `02`—fewer than 30 days
        -   `03`—between 30 and 60 days
        -   `04`—more than 60 days
    -   `city`, string—shipping city, can contain up to 50 characters.
    -   `country`, string, `^[A-Z]{2}$`—shipping country code in the ISO 3166-1 alpha-2 format.
    -   `delivery_email`, string—the email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters.
    -   `delivery_time`, string, `^0[1-4]$`—delivery time. Possible values:
        -   `01`—digital same day delivery
        -   `02`—same day delivery
        -   `03`—next day delivery
        -   `04`—delivery more than one day after the purchase was made
    -   `name_indicator`, string, `^0[1-2]$`—indicates whether the customer's name matches the recipient's name. Possible values:
        -   `01`—names match
        -   `02`—names do not match
    -   `postal`, string—shipping postal code, can contain up to 16 characters.
    -   `region`, string—the name of the region \(state, province, or other administrative subdivision type\) of the shipping address. Can contain up to 255 characters.
    -   `region_code`, string, `^[0-9A-Z]{1,3}$`—state, province, or region code in the ISO 3166-2 format, for example, `DOR` for Dorset.

If you specify this parameter, you also need to specify and populate the `country` parameter in the `shipping` object.

    -   `type`, string, `^0[1-7]$`—delivery option selected by the customer. Possible values:
        -   `01`—delivery to the cardholder's billing address
        -   `02`—delivery to a different verified address
        -   `03`—delivery to the address that is not verified and does not match the billing address
        -   `04`—store delivery
        -   `05`—digital delivery
        -   `06`—no delivery needed \(for example, event ticket purchase\)
        -   `07`—other

 ```language-json
{ 
  "customer":{ 
    "shipping":{ 
      "type":"01",
      "delivery_time":"01",
      "delivery_email":"test@gmail.com",
      "address_usage_indicator":"01",
      "address_usage":"01-10-2022",
      "city":"London",
      "country":"GB",
      "address":"Blackheath Ave",
      "postal":"SE10 8XJ",
      "region":"Vilnius County",
      "region_code":"LND",
      "name_indicator":"01"
    }
  }
}
```

 ```
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTG9uZG9uIiwKICAgICAgImNvdW50cnkiOiJHQiIsCiAgICAgICJhZGRyZXNzIjoiQmxhY2toZWF0aCBBdmUiLAogICAgICAicG9zdGFsIjoiU0UxMCA4WEoiLAogICAgICAicmVnaW9uX2NvZGUiOiJMTkQiLAogICAgICAibmFtZV9pbmRpY2F0b3IiOiIwMSIKICAgIH0KICB9Cn0==
```

|
|`customer_ssn`  
 integer, optional

|The last four digits of the social security number of a US citizen.

 Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `1984`

|
|`customer_state`  
 string, optional

|The name of the region\(state, province, or other administrative subdivision type\) of the customer's address.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Greater London`

|
|`customer_street`  
 string, optional

|The name of the street in the customer's address.

 The length of the string cannot be more than 255 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `Main`

|
|`customer_zip`  
 string, optional

|The postal or zip code in the customer's address.

 The length of the string cannot be more than 10 characters.Passing this information, along with other information about the customer, may help avoid having to provide additional information about the payment and simplify user scenarios \(see [this article](en_PP_Gathering_customer_data.md)\).

 Example: `75001`

|
|`debt_account`  
 string, optional

|The number of the account designated to receive funds as part of debt settlement purchases.

 This parameter is required for debt settlement purchases \(see [this article](en_PP_debt_repayments.md)\).The length of the string cannot be more than ten characters. Only Latin-script letters and digits are allowed.

 Example: `an9876170i`

|
|`force_acs_new_window`  
 integer \(boolean\*\), optional

|Indicator specifying whether a third-party web service that the customer is redirected to is opened in a new tab or not \(see [this article](en_PP_pm_redirect_mode.md)\).

 May be required for specific payment methods and can have one of the following values:

 -   `0`—redirected using the mode specified as the default mode for the payment method,
-   `1`—redirected in a new tab, ignoring the mode specified as the default mode for the payment method.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md)\), this parameter can be specified as a boolean value and set to either `false` or `true`.

 Example: `1`

|
|`force_payment_method`  
 string, optional

|The code of the payment method that should be preselected for the payment \(see [this article](en_PP__PreselectingPS.md)\).

 Can have values specified in the [payment method code list](en_pm_codes.md).

 Example: `paypal-wallet`

|
|`force_payment_group`  
 string, optional

|The code of the payment method group that should be preselected for the payment \(see [this article](en_PP__PreselectingPS.md)\).

 If this parameter is passed, only those payment methods that are part of the corresponding method group and are supported within the project will be available to the customer. However, if this parameter is passed together with the `force_payment_method` parameter, only the payment method linked to the code specified in that parameter will be preselected in the payment form, while the payment method group code will be ignored.

 Currently, this parameter can be used to preselect the Open Banking method group when you work with the 4th generation Payment Page—to do so, specify `openbanking` as the value.

 Example: `openbanking`

|
|`force_payment_method_subtype`  
 string, optional

|The code of the payment card brand that should be preselected for the payment \(see [this aticle](en_PP__PreselectingPS.md)\).

 Can have values specified in the [payment card code list](en_card_codes.md).

 Example: `mastercard`

|
|`hide`  
 string, optional

|A single code or a list of codes for payment methods that should be excluded from the payment form for the payment \([details](en_pp_methods_availability.md)\). If a list of codes is specified, they should be separated by commas.

 Can have values specified in the [payment method code list](en_pm_codes.md).

 Example: `card, cup-union`

|
|`identify_doc_number`  
 string, optional

|The identifier of the document serving as a proof of identity for the customer.

 May be required for specific payment methods and can consist of a personal identity number, a taxpayer number\(e.g., [PIX](pm_pix.md)\), or other similar identifiers.

 Example: `6543234567`

|
|`interface_type`  
 string, optional

|An identifier for the interface of the payment platform.

 Using this parameter requires case-by-case coordination with Ecommpay.

 Example: `{"id":7}`

|
|`language_code`  
 string, optional

|The code of the language in which the payment form should be displayed \(see [this article](en_PP_WigetLanguages.md#section_ivb_h3b_sqb)\) and the notifications should be generated \(see [this article](en_PP_receipt_data.md)\).

 Can consist of a two-letter ISO 639-1 alpha-2 code \(see [Language codes](en_language_codes.md)\) or a code in a different format when this has been arranged prior.

 Pattern: `/^([a-z]{2}|zh\-hant)$/i`.

 Example: `de`

|
|`merchant_callback_url`   
 string, optional

|URL for handling request callbacks.

 This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default \(for information about callbacks and how to use them, see [this article](en_platform_callbacks.md)\).

 Example: `https://cosmoshop.earth/specialorder`

|
|`merchant_data`  
 string, optional

|Additional information that needs to be tracked by the web service.

 The data that is passed in this parameter can vary. However, what data set is passed in this parameter should be communicated to the Ecommpay specialists and configured beforehand to ensure the data is processed and displayed correctly in callbacks and payment information tabs \(see [this article](en_pp_additional_data.md)\). In specific cases can contain a JSON object; then, the `"` character \(quotation mark, U+0022\) needs to be preceded by the `\` escape character \(reverse solidus, U+005C\) in order to be sent via a POST request. If the JSON object is passed via a GET request, escape characters are not required.

 ``` {#codeblock_jjf_xhb_d2c .language-json}
"merchant_data": "{"items":[{"sku":"GM12-CC",
        "description":"10 Copper Coins","count":1},
        {"sku":"GM12-GC","description":"Golden Coin",
        "count":2}],"total_count":3,"user_id":"122"}"
```

 ``` {#codeblock_ts4_xhb_d2c .language-json}
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"
```

|
|`merchant_descriptor`   
 string, optional

|Information about the merchant provided to other parties involved in card payment processing and subsequently to customers.

 Can be used for processing purchases and performing payment instrument verification. The length of the string is limited to 22 characters for cards of the Mastercard card network and 25 characters for cards of the Visa card network. For more information on working with this parameter, see [this article](en_pp_descriptor.md).

 Example: `Cosmotour* to the Moon`

|
|`merchant_domain`  
 string, optional

|The domain name of the web service where the payment form should be opened.

 This parameter should be passed when Payment Page is invoked in the form of embedded Apple Pay and Google Pay payment buttons \(see [this article](en_pp_embedded_payment_buttons.md)\).

 Example: `merchant.example.com`

|
|`merchant_fail_enabled`  
 integer, optional

|Indicator that specifies the availability options for the final redirection of the customer to the web service when a purchase is declined.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto the web service is available if Payment Page is opened in a separate browser tab\(in this case, how the web service page is opened is determined by the corresponding parameter from the `mode` group\) and not as an iframe object or in a modal window,
-   `2`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `2`

|
|`merchant_fail_redirect_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when a purchase is declined.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `blank_page`

|
|`merchant_fail_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is declined.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/failed`

|
|`merchant_return_enabled`  
 integer, optional

|Indicator that specifies the availability options for the preliminary redirection of the customer to the web service from the payment form.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto the web service is available if Payment Page is opened in a separate browser tab\(in this case, how the web service page is opened is determined by the corresponding parameter from the `mode` group\) and not as an iframe object or in a modal window,
-   `2`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `0`

|
|`merchant_return_redirect_mode`  
 string, optional

|Indicator that specifies the mode for the preliminary redirection of the customer to the web service from the payment form.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `iframe`

|
|`merchant_return_url`  
 string, optional

|URL for preliminary redirection to the web service from the payment form.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/return`

|
|`merchant_success_enabled`  
 integer, optional

|Indicator that specifies the availability options for the final redirection of the customer to the web service when the purchase is completed.

 Can have one of the following values:

 -   `0`—redirectionto the web service is not available,
-   `1`—redirectionto the web service is available if Payment Page is opened in a separate browser tab\(in this case, how the web service page is opened is determined by the corresponding parameter from the `mode` group\) and not as an iframe object or in a modal window,
-   `2`—redirectionto the web service is available by default, using the mode specified in the `mode` parameter group.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `1`

|
|`merchant_success_redirect_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is completed.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `parent_page`

|
|`merchant_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when the purchase is completed.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/success`

|
|`mode`  
 string, optional

|Indicator that specifies the Payment Page operation mode.

 Can have one of the following values:

 -   `purchase`—for making a purchasein Purchase mode \(used by default\),
-   `payout`—for making a payoutin Payout mode,
-   `card_verify`—for verifying the validity of a payment instrumentin Card Verify mode,
-   `card_tokenize`—for creating a payment details tokenin Card Tokenize mode.

 Example: `card_verify`

|
|`moto_type`  
 integer, optional

|Type of order for carrying outa Mail Order/Telephone Order purchase\(involving the owner of the payment card providing its details over phone, mail, fax, or email\):

 -   `1`—Mail Order,
-   `2`—Telephone Order.

 Example: `2`

|
|`operation_type`  
 string, optional

|Indicator that specifieswhether a purchaseis processed in one or two steps.

 Should be specified in cases where the intended payment type is different from the one specified by default \(with regard to the number of steps\). Can have one of the following values:

 -   `sale`—for one-step purchases \(with the funds transferred to the merchant immediately;[details](en_pp_purchase.md)\),
-   `auth`—for two-step purchases \(with the funds transferred to the merchant after first being in an authorisation hold;[details](en_pp_purchase_auth.md)\).

 Example: `auth`

|
|`payment_amount`  
 integer, required\*

|The amount of the paymentin the smallest currency unit.

 Specified in the smallest currency unit without a decimal separator.Required for all Payment Page modes except Card Tokenize.

 Example: `1815`\(represents an amount of 18.15 currency units when referring to a currency with two decimals\)

|
|`payment_cryptocurrency_type` string, optional

|Indicator that specifies the type of the cryptocurrency.

 Required for payments involving cryptocurrencies via the Mastercard MoneySend and Visa Direct services. Can have one of the following values:

 -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority.
-   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution.
-   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments.
-   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation.

 Example: `cbdc`

|
|`payment_currency`  
 string, required\*

|Three-letter code of the payment currency.

 Specified in the ISO-4217 alpha-3 format, according to the [currency codes reference](en_currency_codes.md).Required for all Payment Page modes except Card Tokenize.

 Pattern: `^[A-Z]{3}$`.

 Example: `EUR`

|
|`payment_description`  
 string, optional

|A short description for the payment, intended to be displayed to the customer, as well as being used by the web service for tracking purposes.

 The length of the string cannot be more than 255 characters. Can be displayed to the customer on the information page, or via system notifications and the Dashboard interface.

 Example: `Thai massage session`

|
|`payment_extra_param`  
 string, optional

|Additional relevant information pertaining to the payment.

 May be required for specific payment methods and in other individual cases.Generally, where and how this parameter is used, as well as the format of any data contained therein should be decided uponduring the integration of the web service, or when implementing additional payment methods or capabilities.

|
|`payment_id`  
 string, required\*

|The payment identifier.

 Must be assigned by the web service. Should consist of a string no longer than 255 characters, be case-insensitive, and correspond one-to-one with the relevant payment within that project.Required for all Payment Page modes except Card Tokenize.

 Example: `payment_443`

|
|`payment_merchant_risk`  
 string, optional

|Additional information about a purchase made for goods or services by a customer and about which 3‑D Secure authentication method is preferred by the merchant.

 Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data. When passed for card payments, data contained in this parameter may serve to improve the probability of a successful 3‑D Secure authentication without any further input from the customer \(i.e., authentication via the frictionless flow instead of the challenge flow; [details](en_pp_3ds.md)\).

 -   `challenge_indicator`, string, `^0[1-9]$`—indicates whether the challenge flow is preferred. Possible values:
    -   `01`—no preferences
    -   `02`—not using the challenge flow is preferred
    -   `03`—using the challenge flow is preferred
    -   `04`—using the challenge flow is required
    -   `05`—do not use the challenge flow, the merchant has performed the risk analysis
    -   `06`—do not use the challenge flow, use the Data Only flow
    -   `07`—do not use the challenge flow, Strong Customer Authentication has been applied otherwise
    -   `08`—do not use the challenge flow, the merchant is included in cardholder's trusted beneficiaries list
    -   `09`—using the challenge flow is required, prompt the cardholder to add the merchant to the trusted beneficiaries list
-   `challenge_window`, string, `^0[1-5]$`—the dimensions of a window in which the authentication page opens. Possible values:
    -   `01`—250 x 400 px
    -   `02`—390 x 400 px
    -   `03`—500 x 600 px
    -   `04`—600 x 400 px
    -   `05`—full screen
-   `gift_card`, object—object with information about a purchase made with a prepaid or gift card:
    -   `amount`, integer—the amount of the purchase made with a prepaid or gift card in the smallest units of currency
    -   `count`, integer—total number of prepaid or gift cards used for making a purchase
    -   `currency`, string—the currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format
-   `preorder_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—the date when the preordered merchandise or service will be available in the `DD-MM-YYYY` format
-   `preorder_purchase`, string, `^0[1-2]$`—indicates whether the purchase is a preorder. Possible values:
    -   `01`—not a preorder
    -   `02`—a preorder
-   `reorder`, string, `^0[1-2]$`—indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:
    -   `01`—first-time purchase
    -   `02`—repeat purchase

 ```language-json
{ 
  "payment":{ 
    "reorder":"01",
    "preorder_purchase":"01",
    "preorder_date":"11-10-2022",
    "challenge_indicator":"01",
    "challenge_window":"01",
    "gift_card":{ 
      "amount":12345,
      "currency":"USD",
      "count":1
    }
  }
}
```

 ```
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==
```

|
|`payment_methods_options`  
 string, optional

|Additional information relevant for specific payment methods and third-party services.

 Can be used to manage individual methods, including Open Banking methods, in order to send additional information about the customer and the payment, manage the page size of third-party web services that the customer is redirected to, and for other possible reasons, depending on the specific payment methods being used.

 Example: `{\"online_thailand_banks\": {\"split_banks\": true}}`

|
|`project_id`  
 integer, required

|Identifier of the projectintended to manage the interactions of the web service with the payment platform. This identifier is assigned by Ecommpayduring the integration \([details](en_glossary.md)\).

 Example: `57123`

|
|`receipt_data`  
 string, optional

|Information about line items in an order.

 Can be used to generate a proof of purchase document to be sent to the customer \(see [this article](en_PP_receipt_data.md)\).Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme.The JSON object can include various combinations of elements from the list of supported data.

 -   `positions`, array—array which allows listing up to 300 purchased items in the notification. For each listed item, the following information can be specified:
    -   `amount`, integer—the price of the item
    -   `quantity`, integer—the number of purchased items of the same kind
    -   `tax`, integer—the VAT rate if it differs for different listed items
    -   `tax_amount`, integer—the VAT amount
    -   `description`, string—the description of the purchased item.
-   `total_tax_amount`, integer—the total VAT amount for the entire purchase
-   `common_tax`, integer—the VAT rate if it is the same for all listed items

 ``` {#codeblock_vd1_r3b_d2c .language-json}
{  
   "receipt_data":{  
      "positions":[  
         {  
            "quantity":3,
            "amount":10000,
            "tax":18,
            "tax_amount":1800,
            "description":"Design frame"
         }
      ],
      "total_tax_amount":1800,
      "common_tax":18       
   }
}
```

 ``` {#codeblock_k1g_r3b_d2c}
receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAg
ICAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI
6MTgsCiAgICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiJEZXN
pZ24gZnJhbWUiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAsCiAgICA
gICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ"
```

|
|`recipient_address`   
 string, optional

|The name of the street and the house number\(including any additional parts of the address such as building indicators and apartment numbers\) in the address of the payment recipient.

 The length of the string cannot be more than 99 characters.Required for Visa Direct debiting operations performed with Visa cards issued in Australia, Canada, or New Zealand.

 Example: `Via Dietro Duomo 36`

|
|`recipient_card_holder`   
 string, optional

|The first and last names of the holder of the payment card used to receive the payment.

 Should be spelled as specified on the card and adhere to the rules for specifying names \(see [this article](en_faq_payment_processing.md#section_dbx_kby_t1c)\). The length of the string cannot be more than 255 characters.

 Example: `Fran Petrarca`

|
|`recipient_city`   
 string, optional

|The name of the place of residence \(e.g., town, city, or other settlement type\) in the address of the payment recipient.

 The length of the string cannot be more than 25 characters.

 Example: `Padova`

|
|`recipient_country`   
 string, optional

|The country code of the place of residence of the payment recipient.

 Specified in the ISO 3166-1 alpha-2 format.

 Pattern: `^[A-Z]{2}$`.

 Example: `IT`

|
|`recipient_day_of_birth`  
 string, optional

|The date of birth of the payment recipient.

 Specified in `DD-MM-YYYY` format. Required if a Visa card is used to receive the payment.

 Pattern: `^\\d{2}-\\d{2}-\\d{4}$`.

 Example: `12-12-1990`

|
|`recipient_first_name`   
 string, optional

|The name of the payment recipient.

 The length of the string cannot be more than 255 characters.

 Example: `Fran`

|
|`recipient_last_name`   
 string, optional

|The last name of the payment recipient.

 The length of the string cannot be more than 255 characters.

 Example: `Petrarca`

|
|`recipient_pan`   
 string, optional

|The number of the payment card used to receive the payment.

 Specified as is, without masked characters, spaces, or other separators.

 Pattern: `^[0-9]{15,19}$`.

 Example: `4314220000000056`

|
|`recipient_state`   
 string, optional

|The local code of the region\(state, province, or other administrative subdivision type\) of the payout recipient's address \([details](en_Gate_payout.md)\).

 The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. Should be specified for processing payouts when the `recipient_country` parameter is also specified in the same query and its value is the country code of Canada \(`CA`\) or the United States \(`US`\).

 Pattern: `^[A-Z]+$`.

 Example: `AK`\(when specified for Alaska, designated `US-AK`\)

|
|`recipient_state_code`   
 string, optional

|The local code of the region\(state, province, or other administrative subdivision type\) associated with the recipient's address for fund transfers using Mastercard MoneySend and Visa Direct services \([details](en_gate_money_transfer_services.md)\).

 The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. Should be specified for Mastercard MoneySend and Visa Direct operations when the `recipient_country` parameter is also specified in the same query and its value is the country code of Canada \(`CA`\) or the United States \(`US`\).

 Pattern: `^[A-Z]+$`.

 Example: `ON`\(when specified for Ontario, designated `CA-ON`\)

|
|`recipient_wallet_id`   
 string, optional

|The identifier of the digital wallet used by the payment recipient.

 The length of the string cannot be more than 64 characters. Specified as is, without masked characters, spaces, or other separators.

 Pattern: `^[^!@&~№{}|<>\\[\\]]*$`.

 Example: `WID20071304`

|
|`recipient_wallet_owner`   
 string, optional

|The first and last names of the owner of the digital wallet used by the payment recipient.

 Should be spelled the same way as in the payment system and be at most 255 characters long in total.

 Pattern: `/^[\p{L}\p{M}0-9 .'-]+$/u`.

 Example: `Fran Petrarca`

|
|`recurring`  
 string, optional

|Information about the COF purchase being registered \([details](en_pp_recurring.md)\).

 If the Ecommpay JavaScript library is used, can be passed as a JSON object\(containing various combinations of elements from the list of supported data\), otherwise should be specified as a URLobtained by encoding the source JSON object.

 -   `register`, boolean—indicator that specifies whether a COF purchase should be registered
-   `type`, string, `^[RCU]$`—type of the COF purchase to register, possible values:
    -   `R`—regular purchase
    -   `C`—one-click purchase
    -   `U`—autopurchase
-   `period`, string, `^[DWMQY]$`—frequency of debits \(for a regular COF purchase\), possible values:
    -   `D`—daily
    -   `W`—weekly
    -   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
    -   `Q`—quarterly
    -   `Y`—annually
-   `amount`, integer—fixed amount of subsequent debits \(for a regular COF purchase\) in the smallest currency unit
-   `interval`, integer—multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter and should be assigned a numeric value from `1` to `100`
-   `time`, string, `^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$`—time of performing subsequent debits \(for a regular COF purchase\) in the `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request
-   `start_date`, string, `^([0-3]\\d-){2}[1-2]\\d{3}$`—date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format
-   `expiry_day`, integer orstring—calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\)
-   `expiry_month`, integer orstring—month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\)
-   `expiry_year`, integer—year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\)
-   `scheduled_payment_id`, string—identifier assigned to the payment within which scheduled debits are performed, it must differ from the identifier of the payment made to register a COF purchase that is specified in `payment_id`

 ```language-json
{
    "register": true,
    "type": "U"
}
```

 ```language-json
%7B%22register%22%3Atrue%2C%22type%22%3A%22U%22%7D%2C
```

|
|`redirect`  
 integer \(boolean\*\), optional

|Indicator specifying whether the payment form should be opened on a new HTML page regardless of the type of device being used \(see [this article](en_PP_method_NewTab.md)\).

 Can have one of the following values:

 -   `0`—the payment form should beopened usingeither the default method or a different method specified in other parameters,
-   `1`—the payment form should beopened in a new HTML page.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md)\), this parameter can be specified as a boolean value and set to either `false` or `true`.

 Example: `1`

|
|`redirect_fail_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is declined.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `blank_page`

|
|`redirect_fail_url`  
 string, optional

|URL for final redirection to the web service if the purchase is declined.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/failed`

|
|`redirect_on_mobile`  
 integer \(boolean\*\), optional

|Indicator specifying whether the payment form should be opened on a new HTML page for mobile devices \(see [this article](en_PP_method_NewTab.md)\).

 Can have one of the following values:

 -   `0`—the payment form should beopened using eitherthe default method or a different method specified in other parameters,
-   `1`—the payment form should beopened in a new HTML page.

 If the `merchant.js` library is used \([details](en_pp_interaction_organisation.md)\), this parameter can be specified as a boolean value and set to either `false` or `true`.

 Example: `1`

|
|`redirect_success_mode`  
 string, optional

|Indicator that specifies the mode for the final redirection of the customer to the web service when the purchase is completed.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab,
-   `blank_page`—opens the pagein a new tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `parent_page`

|
|`redirect_success_url`  
 string, optional

|URL for final redirection to the web service by customer decision when a purchase is completed.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/success`

|
|`redirect_return_url`  
 string, optional

|URL for preliminary redirection to the web service from third-party services such as banks and other payment systems.

 Requires this functionality \(for specific third-party services\) to be set up and enabled beforehand. For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/third_party_services`

|
|`redirect_tokenize_mode`  
 string, optional

|Indicator that specifies the mode for the automatic final redirection of the customer to the web service when a token has been generated in Card Tokenize mode using the relevant payment details.

 Can have one of the following values:

 -   `iframe`—opens the pagein an iframe object \(this value is ignored if the payment form is opened in a new tab and the customer is redirected in that new tab\),
-   `parent_page`—opens the pagein the currently active tab.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `parent_page`

|
|`redirect_tokenize_url`  
 string, optional

|URL for automatic final redirection to the web service when a token has been generated in Card Tokenize mode using the relevant payment details.

 For more information about managing options for redirecting the customer back to the web service, see [this article](en_PP_redirect_modes.md).

 Example: `https://cosmoshop.jupiter.example/pages/tokenize`

|
|`region_code`  
 string, optional

|The country code for the customer's address.

 Specified in the ISO 3166-1 alpha-2 format. If this parameter is not specified, the country code is determined using the customer's IP address or other parameters.

 Pattern: `^[A-Z]{2}$`.

 Example: `FR`

|
|`sender_address`   
 string, optional

|The name of the street and the house number\(including any additional parts of the address such as building indicators and apartment numbers\) in the address of the payment sender.

 The length of the string cannot be more than 99 characters.

 Example: `Via Certaldo 18`

|
|`sender_city`   
 string, optional

|The name of the place of residence \(e.g., town, city, or other settlement type\) in the address of the payment sender.

 The length of the string cannot be more than 25 characters.

 Example: `Florence`

|
|`sender_country`   
 string, optional

|The code of the country in the address of the payment sender.

 Specified in the ISO 3166-1 alpha-2 format.

 Pattern: `^[A-Z]{2}$`.

 Example: `IT`

|
|`sender_descriptor`   
 string, optional

|Information about the merchant provided to other parties involved in card payment processing and subsequently to customers.

 Can be used for issuing payouts. The length of the string is limited to 22 characters for cards of the Mastercard card network and 25 characters for cards of the Visa card network. For more information on working with this parameter, see [this article](en_pp_descriptor.md).

 Example: `Cosmotour* to the Moon`

|
|`sender_first_name`   
 string, optional

|The first name of the payment sender.

 The length of the string cannot be more than 255 characters.

 Example: `Gio`

|
|`sender_last_name`   
 string, optional

|The last name of the payment sender.

 The length of the string cannot be more than 255 characters.

 Example: `Boccaccio`

|
|`sender_state`   
 string, optional

|The local code of the region\(state, province, or other administrative subdivision type\) of the payment sender's address.

 The value of this parameter is the second element of a code for a subdivision \(in ISO 3166-2\), without the two-letter country code and the hyphen-minus used as a separator. Should be specified when the `sender_country` parameter is also specifiedin the same query.

 Example: `52`\(when specified for Tuscany, designated `IT‑52`\)

|
|`sender_wallet_id`   
 string, optional

|The identifier of the digital wallet used by the payment sender.

 The length of the string cannot be more than 64 characters. Specified as is, without masked characters, spaces, or other separators.

 Example: `WID16061313`

|
|`sender_zip`   
 string, optional

|The postal code in the address of the payment sender.

 The length of the string cannot be more than 255 characters.

 Example: `50142`

|
|`signature`  
 string, required

|The digital signature used to sign the query parameters.

 Should be generated using the appropriate algorithm after all relevant parameters have been specified \(see [this article](en_platform_signature.md)\).

|
|`style_id`  
 integer, optional

|The identifier of the payment form design style.

 Can be used for the Payment Page design style \(see [this article](en_PP__design_customisation.md)\).

 Example: `6123`

|
|`target_element`  
 string, optional

|The iframe element identifier\(for the HTML page of the web service\) of the element where the payment form should be opened \(see [this article](en_PP_method_Embedded.md)\).

 Example: `widget-container`

|
|`uuid`   
 string, optional

|Identifier used for internal purposes.

 The length of the string cannot be more than 64 characters.Can be used to invoke the payment form in Payout modeby specifying the value received in the payout registration callback \(see [this article](en_pp_payout.md)\).

 Example: `Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==`

|

**Parent topic:**[Payment Page](en_PP_about.md)



---

# Gate {#en_Gate_Integration_About .concept}

A section with the information about working with the the Gate API.

This section provides the information about working with the Gate interface.

## Overview {#section_yww_4nc_stb .section}

The information about the interfaceand the basic actions available during the work with the interface—[Overview](en_Gate_How_to_Integrate.md).

## Integration {#section_bbj_fpc_stb .section}

The information about the integration with the Ecommpay payment platform via Gate:

-   [Quickstart](en_gate_quickstart.md)—about quick and easy ways to start accepting payments and to implement other capabilities with the use of PHP and Go code examples.
-   [Interaction concepts](en_gate_interaction_organisation.md)—about integrating with the payment platform via Gate and the interaction formats and workflows utilised in the process.

## Basic actions {#section_y53_dsc_stb .section}

The information about the basic actions available during the work via Gate:

-   [One-time purchases](en_Gate_purchase.md)—about processing purchases with immediate debiting of funds\([one-step purchases](en_gate_payment_sale.md)\) and with debiting after authorisation hold \([two-step purchases](en_gate_payment_auth.md)\).
-   [Payment link purchases](en_gate_invoice.md)—about processing one-stepand two-step purchases with the use of payment links and with the customer redirection to the Payment Page payment form.
-   [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)—about registering and processing purchases with the subsequent series of recurring debits.
-   [Purchase refunds](en_Gate_Refund.md)—about returning the funds that were debited from the customer's account within a particular purchase.
-   [Payouts](en_Gate_payout.md)—about processing payouts with the transfer of funds from the merchant to the customer.
-   [Payment instrument verification](en_gate_account_verification.md)—about debiting a dummy \(zero\) amount or authorising a specific \(non-zero\) amount to verify a payment instrument.

## Auxiliary procedures and additional capabilities {#section_ddb_gzc_stb .section}

The information about various procedures and capabilities that can be used for processing payments via Gate:

-   [Auxiliary procedures](en_gate_procedures.md)—about the procedures that can be required for processing separate payments.
-   [Additional capabilities](en_Gate_Additional_capabilities.md)—about the capabilities that can be useful for boosting payment acceptance rates, customer convenience, and the quality of the provided services.

## API specification {#section_xkk_v1d_stb .section}

The information about the data structuresin program requests and responses—[API Reference](https://api-developers.ecommpay.com/).

-   **[Overview](en_Gate_How_to_Integrate.md)**  
An article with the introductory information about the Gate interface and its capabilities.
-   **[Quickstart](en_gate_quickstart.md)**  
A quickstart guide on how to implement payment processing via Gate with the use of source code examples in PHP and Go.
-   **[Interaction concepts](en_gate_interaction_organisation.md)**  
An article about organising the work with Gate on the web service side based on the principles of the payment platform operation and the utilised interaction flows and formats.
-   **[One-time purchases](en_Gate_purchase.md)**  
Articles about processing via Gate one-time purchases with immediate debiting of funds \(one step\) and with debiting of funds after placing an authorization hold \(two steps\).
-   **[Payment link purchases](en_gate_invoice.md)**  
An article about processing one-step and two-step purchases with the use of payment links and redirecting customers to Payment Page.
-   **[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)**  
Articles about registering and processing via Gate different types of purchases followed by a series of recurring debits and about the capabilities of managing debits within recurring payments.
-   **[Purchase refunds](en_Gate_Refund.md)**  
An article about refunding different types of purchases via Gate.
-   **[Payouts](en_Gate_payout.md)**  
An article about processing payouts via Gate.
-   **[Payment instrument verification](en_gate_account_verification.md)**  
An article about verifying a payment instrument via Gate by debiting a zero amount or placing a hold on funds.
-   **[Auxiliary procedures](en_gate_procedures.md)**  
Articles about auxiliary procedures that can be required during processing specific payments via Gate.
-   **[Additional capabilities](en_Gate_Additional_capabilities.md)**  
Articles about additional capabilities of Gate for boosting payment acceptance rates, customer convenience, and the quality of the provided services.
-   **[Gate API](gate_api.md)**  
The Gate API specification with the descriptions of data structures and schemas for generating requests to different endpoints.



---

# Overview {#en_Gate_How_to_Integrate .concept}

An article with the introductory information about the Gate interface and its capabilities.

Gate is one of the Ecommpay payment platform, and it provides a full range of capabilities for interaction with the payment platform. Gate supports performing one-time purchases and COF purchases,refunds and payouts, as well as requesting additional information, for instance, a payment status.You can integrate with the platform solely via Gate, or you can combine using Gate with other Ecommpay interfaces and solutions. For example, you can set up processing purchases via Payment Page and issue payouts and refunds via Gate.

Gate allows you to accept card paymentsand alternative payments \(for more information, see [Methods](en_pm_about.md)\). Payments with direct use of payment cards are supported for American Express, Mastercard, Visa, CUP \(only for payouts\).

To process payments via Gate, you need to develop your own payment interface, with full UI control.Processing card payments via Gate requires your payment interface to be a PCI compliant \(for more information about necessary documents, contact your Ecommpay account manager\).

![](images/en_gate_scheme_1.svg)

In general, while performing a payment, the web service sends a request to one of the Gate API endpoints. Then the payment platform receives the request, processes and redirects it to third parties participating in payment processing and responds with a callback contained the final payment result.

The sections about Gate cover the following:

-   [Interaction concepts](en_gate_interaction_organisation.md)—how to integrate by using Gate, technical aspects on interaction between the web service and the payment platform, including interaction models and the formats of request, response and callback.
-   [Payment processing](en_platform_payment_model.md)—overview information about payment types provided in the payment platform, processing of each payment types, payment statuses as well as objects related to payment—requests and operations.
-   [One-time purchases](en_Gate_purchase.md), [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md), [Payouts](en_Gate_payout.md), [Payment instrument verification](en_gate_account_verification.md)—technical aspects on processingall types of payments such as purchases, COF purchases, payments and card verification.
-   Other sections with information on Gate.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Quickstart {#en_gate_quickstart}

A quickstart guide on how to implement payment processing via Gate with the use of source code examples in PHP and Go.

**Parent topic:**[Gate](en_Gate_Integration_About.md)

## Overview {#en_gate_quickstart_overview}

This guide explains how to organise payment processing via the Gate API of the Ecommpay payment platform. This integration mode implies that you use your in-house user interface to ensure maximum interaction with customers on the side of the web servicewhile the interaction with the payment platform is carried out on the programmatic level, “under the hood” so to speak. It allows you to apply tested and quick solutions as you follow the instructions and use code samples in PHP and Go.

With this guide, you will learn how to accept one-stepcard purchases \(which are the most frequently used payments\)and how to issue refunds on such purchases. As a rule, this functionality is optimal for the initial testing and quick launching of payment projects into production. Moreover, havingintegrated these capabilities, you can add anything else easily enough because working with any payment typeand any payment method supported in the platform relies on the same principles as working with one-step card purchases and most of the time involves similar procedures.

If processing purchases via Gate is not relevant, and you need only refund or payout functionality, you can use this guide to learn how to work with signatures, responses, and callbacks and then proceed to integrate relevant [additional capabilities](en_gate_quickstart.md).If you need Gate only for checking statuses of individual payments, use this guide to learn how to work with signatures and see [Checking current payment information](en_Gate_payment_status_request.md). If you feel like you need something completely different, consider the following options.

-   If you need to set up payment solutions with the use of Payment Page developed by Ecommpay for processing payments via websitesand mobile applications, go to [Payment Page](en_PP_about.md)and [Integration using SDK](en_sdk_overview.md).
-   If you need to set up payment link purchases that utilise Payment Page, use this guide to learn how to work with signatures, responses, and callbacks and then go to [Payment link purchase](en_platform_invoice_model.md). You can also initiate payment link purchases manually [via Dashboard](en_dbl_payments.md), the interface for the merchant's employees.
-   If you need to set up retrieving operation, chargeback, and balance information via an API, go to [Using Data API](en_dbl_api_protocol.md).
-   Finally, if what you need has not been covered above, browse other sections of the documentation and contact the Ecommpay specialists.

**Note:** It should also be mentioned that to start payment processing via Gate you need to address both technological and organisational aspects of integration, which includes the PCI DSS complianceif you plan to take card payments. For more information about it, see [Interaction concepts](en_gate_interaction_organisation.md).

Now that the introductory matters have been taken care of, let's get to work.

## Brief theory {#en_gate_quickstart_theory}

### Projects and keys {#section_g4h_1hp_wxb .section}

Working with the Ecommpaypayment platform can be compared to using hotel services: to check into a hotel, you need a room and a key for this room, and to start working with the platform, you need *a project and a key* for this project. And like in case of hotel rooms, there can be a different number of projects for one client—for different aims and purposes—and each project requires its own key.

Usually, to work with the platform, having one test and one production project is enough. This case is typical and is used as the basis within the Quickstart guide. If for any reason you need more projects, make sure to identify this need in the communication with your account manager. In the meantime, you don't have to wait till this issue gets resolved: you can already start working on the implementation and setup with one test project.

If you have already obtained the identifier \(`project_id`\) and the secret key \(`secret_key`\) of the test project, have them at hand as you proceed with the implementation.Otherwise, you can [get an access](https://ecommpay.com/sign-up/) to the test project and return to this article.

### Workflow {#section_plt_tqf_rxb .section}

To ensure payments are processed via Gate correctly, you need to set up collecting relevant parameters, forming and sending requests to the payment platform as well as accepting and processing information sent in responses from the payment platform. Along with that, all interaction with customers\(necessary for collecting and displaying relevant information\) should be carried out on the side of the web service with the use of your own in-house solutions, while all other procedures \(to process the information\) can be implemented with the use of the code samples presented below.

Let's have a look at the workflow of processing a purchase with the focus on the technical aspects for the web service and the payment platform.

| |Web service|Payment platform|
|--|-----------|----------------|
|1|Collects all necessary data when the customer is ready to pay for their order, combines payment parameters into a payload of the request and signs it, creates a payment request and sends it to the payment platform.|–|
|2|Informs the customer that the payment is being processed.|Accepts the request and works on it to execute the payment. If applicable, sends a callback prescribing necessary actions.|
|3|If applicable, accepts the callback prescribing necessary actions, performs these actions \(with or without the customer's involvement\) and sends the request for resuming payment processing to the payment platform.|–|
|4|Informs the customer that the payment is being processed.|If applicable, accepts the additional request and performs actions necessary to resume the payment processing. Sends a callback with the payment result to the web service.|
|5|Accepts the payment result callback and displays relevant information to the customer.|–|

When you work with other payment types, the actions can somewhat differ; however, the overall workflow remains the same. Modes of its implementation on the side of the web service can vary.In this guide, we cover basic procedures that can be used and adapted to the specifics of your web service.

### Request parameters {#section_wkz_y5f_rxb .section}

The set of parameters required for executing a payment can vary depending on the type of this payment, the specifics of the utilisedpayment method and the payment system, regional characteristics and other aspects. Thus, sometimes you may need to provide the payment description, the customer's address, or other details, and sometimes such data may not be required. This is why when you set up processing of different payment typesand payment methods, refer to the documentation and the Gate API specification for particular details.

To process a basic card purchase, you need to specify its amount and currency, add three identifiers \(of the project, payment, and customer\) and the payment card details, and then generate a signature for these parameters.

**Note:** Payment card details can be provided as is and in the form of the standardized tokens and arbitrary identifiers of the card data saved earlier.If the tokens and identifiers are not yet created or the relevant card details have not been migrated to the Ecommpay platform from the other provider, you need to create them first. You can do it as soon as you set up processing purchases \(which includes testing and going live\), that is, after you complete the steps described in this guide.

If the card details are provided as is, then required parameters include the following:

|Parameter|Description|
|---------|-----------|
|`general`—object containing general request identification information|
|`project_id`  
 integer

|Project identifier. Together with the key, it is provided by Ecommpay and should be accurately specified even in test requests. If not, the payment platform will react accordingly: think of it as trying to enter someone else's hotel room with your key.  
 Example: `42`

|
|`payment_id`  
 string

|Payment identifier. It can have random values but should always be unique within the project used. Otherwise, an error will occur.  
 Example: `Cosmoshop_purchase_2025-01-01_000001`

|
|`signature`  
 string

|Request signature. It is generated according to the specialised algorithm described below. Use the test key for sending test requests and use the production secret key for processing live payments.  
 Example: `rnv1OS3PJUKEJ5kw5wqoK0ftZGSd4Q6LX5A5NxK6d5alpND4sQTRFt7/9aFV+m3SRwNB8ba98GMsOY91yTVhEQ==`

|
|`payment`—object containing general payment information|
|`payment_amount`  
 integer

|Payment amount. In test requests it can be a random amount while in real ones the amount should correspond to the amount of the order. The amount is specified in minor currency units.  
 Example: `8855` \(for the amount of `88.55`\)  


|
|`payment_currency`  
 string

|Payment currency code. It is specified in the three-letter ISO 4217 alpha-3 format. Test requests can contain any of the existing codes while every real request should contain the code of the currency in which the payment is being initiated.  
 The currency codes are provided in the corresponding [reference](en_currency_codes.md).  
 Example: `USD`  


|
|`customer`—object containing general customer information|
|`customer_id`  
 string

|Customer identifier in the web service.It can have random values and be reused in different requests; however, the identifier of every real customer should exactly match the account of this very customer in the web service and be unique within the project.Otherwise, it can lead to processing difficulties including those related to risk assessment.  
 Example: `17008  
`

|
|`ip_address`|IP address of the customer. In test requests you can provide your own IP address while in real requests you must specify an actual IP address where the customer initiates the payment.  
 Example: `248.121.176.220`

|
|`card`—object containing the customer's payment card details|
|`pan`  
 string

|PAN. In test requests you can specify any realistic values, including the test values provided [below](en_gate_quickstart.md); however, real requests must contain actual card data.  
 Example: `4242424242424243`

|
|`year`  
 string

|Card expiration year, in the `YYYY` format. In test requests you can provide any value as long as it is valid and in proper format; real requests must contain actual card data.  
 Example: `2025`

|
|`month`  
 string

|Card expiration month, a number between 1 and 12. In test requests you can provide any value as long as it is valid and in proper format; real requests must contain actual card data.  
 Example: `5`

|
|`card_holder`  
 string

|Customer name as specified on the card and with regard to [relevant restrictions](en_faq_payment_processing.md#fig_hgj_jds_4nb), passed if this parameter is required for the specific project \(note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\). In test requests you can provide any random value; real requests must contain actual card data.  
 Example: `SONYA KOVALEVSKY`

|
|`cvv`  
 string

|Card verification code as specified on the card or provided to the cardholder by the issuer. In test requests you can provide random values as long as they consist of three digits; real requests must contain actual card data.   
 Example: `345`

|

The request payload with these parameters may look like the following:

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "Cosmoshop_purchase_2025-01-01_000001",
      "signature": "rdCiqlibt8SUMe3OVPNfKMYnQjQ6dkEvRQhMkJRg9ZJULdsKJEZU21E5Y/ISdv0FtXi3oJE5n4hSNK3Owo7Axw=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "17008"
  },
    "payment": {
      "amount": 8855,
      "currency": "USD"
  },
    "card": \{
      "pan": "4242424242424243",
      "year": 2025,
      "month": 5,
      "card\_holder": "SONYA KOVALEVSKY",
      "cvv": "123"
  \}  

}
```

You may also need to use other parameters when processing payments:

-   Parameters necessary due to specific characteristics of payment systems and regional differences. If these parameters were not passed in the initial request, the payment may be declined or you may need to specify them while the payment is being processed.
-   Parameters necessary due to specific characteristics of the web service operation, for example,when the 3‑D Secure authentication is performed on the side of the web service, or when you need to send the payment result notification to the customer. If such parameters are not provided, these capabilities may not be supported.

To ensure proper handling of these parameters, you may require to set up additional procedures. They are partially described below and fully covered in [Additional aspects](en_gate_quickstart.md). Refer to this section of the article once you configured and tested all basic procedures.

Overall, collection of necessary parameters can be set up at your convenience, with regard to your web service's architecture and other aspects \(for examples, relevant dictionaries and databases\). Now that the required parameters have been covered, let's get to implementation.

## Basic implementation {#en_gate_quickstart_basic_implementation}

### Overview {#en_gate_quickstart_basic_implementation_overview}

Implementing payment processing with the use of your web service functionality can be carried out in various ways, which includes creating your own software solutions. This guide describes the implementation procedure with the use of the ready-made code from Ecommpay to sign data, send requests, accept responses to these requests as well as callbacks and with the use of your solutions on the side of the web service for performing other actions, which includes collecting customer information and notifying customers about payment results.

### Data signing {#en_gate_quickstart_basic_implementation_signature}

When all required parameters have been specified, you can generate a signaturefor them and create a request.

```language-php
*/
class Signer
{
    const ITEMS_DELIMITER = ';';
    const ALGORITHM = 'sha512';
    const IGNORED_KEYS = ['frame_mode'];

    /**
     * Secret key
     *
     * @var string
     */
    private $secretKey;

    /**
     * __construct
     *
     * @param string $secretKey
     */
    public function __construct(string $secretKey)
    {
        $this->secretKey = $secretKey;
    }

    /**
     * Check signature
     *
     * @param array $params
     * @param string $signature
     * @return boolean
     */
    public function check(array $params, string $signature): bool
    {
        return $this->sign($params) === $signature;
    }

    /**
     * Return signature
     *
     * @param array $params
     * @return string
     */
    public function sign(array $params): string
    {
        $stringToSign = implode(self::ITEMS_DELIMITER, $this->getParamsToSign($params, self::IGNORED_KEYS));
        return base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $this->secretKey, true));
    }

    /**
     * Get parameters to sign
     *
     * @param array $params
     * @param array $ignoreParamKeys
     * @param string $prefix
     * @param bool $sort
     * @return array
     */
    private function getParamsToSign(
        array $params,
        array $ignoreParamKeys = [],
        string $prefix = '',
        bool $sort = true
    ): array {
        $projectId = 42;
        $paymentId = '12345';
        $customerId = '123';
        $ip = '192.168.1.1';
        $paymentAmount = '1000';
        $paymentCurrency = 'USD';
        $cardPan = '\*4567';
        $cardYear = '2029';
        $cardMonth = '09';
        $cardHolder = 'SONYA KOVALEVSKY';
        $cardCvv = '123';



        $paramsToSign = [
            'general'  => [
            'project_id' => $projectId,
            'payment_id' => $paymentId,
            ],
            'customer'  => [
            'id' => $customerId,
            'ip_address' => $ip,
            ],
            'payment'  => [
            'payment_amount' => $paymentAmount,
            'payment_currency' => $paymentCurrency,
            ],
            'card'  =\> \[
            'pan' =\> $cardPan,
            'year' =\> $cardYear,
            'month' =\> $cardMonth,
            'card\_holder' =\> $cardHolder,
            'cvv' =\> $cardCvv,
            \],

        ];

        foreach ($params as $key => $value) {
            if (in_array($key, $ignoreParamKeys, true)) {
                continue;
            }

            $paramKey = ($prefix ? $prefix . ':' : '') . $key;
            if (is_array($value)) {
                $subArray = $this->getParamsToSign($value, $ignoreParamKeys, $paramKey, false);
                $paramsToSign = array_merge($paramsToSign, $subArray);
            } else {
                if (is_bool($value)) {
                    $value = $value ? '1' : '0';
                } else {
                    $value = (string)$value;
                }

                $paramsToSign[$paramKey] = $paramKey . ':' . $value;
            }
        }

        if ($sort) {
            ksort($paramsToSign, SORT_NATURAL);
        }

        return $paramsToSign;
    }
}
```

```
package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/base64"
	"sort"
)

const itemsDelimiter = ";"

var ignoredKeys = map[string]struct{}{"frame_mode": struct{}{}}

var secretKey string

func SetSecretKey(key string) {
	secretKey = key
}

func Check(params map[string]map[string]string, signature string) bool {
	return Sign(params) == signature
}

func Sign(params map[string]map[string]string) string {
	var stringToSign string

	paramsToSign := getParamsToSign(params, ignoredKeys, "", true)
	for _, value := range paramsToSign {
		for _, v := range value {
			stringToSign = stringToSign + itemsDelimiter + v
		}
	}

	mac := hmac.New(sha512.New, []byte(secretKey))
	mac.Write([]byte(stringToSign))

	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}

func getParamsToSign(params map[string]map[string]string, ignoreParamKeys map[string]struct{},
	prefix string, sorted bool) map[string]map[string]string {
	var paymentId, customerId, ip, amount, currency, cardPan, cardYear, cardMonth, cardHolder, cardCvv string

	paramsToSign := map[string]map[string]string{
		"general": {
			"project_id": projectId,
			"payment_id": paymentId,
		},
		"customer": {
			"id":         customerId,
			"ip_address": ip,
		},
		"payment": {
			"payment_amount":   amount,
			"payment_currency": currency,
		},
		"card": \{
			"pan":         cardPan,
			"year":        cardYear,
			"month":       cardMonth,
			"card\_holder": cardHolder,
			"cvv":         cardCvv,
		\},

	}

	for key, value := range params {
		for k, v := range value {
			if _, ok := ignoreParamKeys[k]; ok {
				continue
			}

			paramKey := k
			if prefix != "" {
				paramKey = prefix + ":" + k
			}

			paramsToSign[key][paramKey] = paramKey + ":" + v
		}
	}

	if sorted == true {
		return sortParams(paramsToSign)
	}

	return paramsToSign
}

func sortParams(params map[string]map[string]string) map[string]map[string]string {
	var sortedParams map[string]map[string]string
	keys := make([]string, 0, len(params))

	for kp := range params {
		keys = append(keys, kp)
	}
	sort.Strings(keys)

	for _, ks := range keys {
		sortedParams[ks] = params[ks]
	}

	return sortedParams
}
```

### Sending requests and accepting responses {#en_gate_quickstart_basic_implementation_requests}

When all data is collected and signed, you can send the request to the required endpoint\(the list of endpoints can be found in the Gate API\). In our case, it is the [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) endpoint. When the request is received\(as a rule, within 100 ms\), the payment platform sends a synchronous HTTP response to the web service stating either that the request was accepted for processing or that the request was not accepted due to detected errors.

The following codes are used in the responses from the platform:

-   `200 OK`—the request has been accepted for processing. In this case, expect subsequent callbacks about processing of the payment. The next section describes how to work with such callbacks.
-   `400 Bad Request`—the request has not been accepted because at least one required parameter is missing or the signature is invalid. In this case, add missing data and generate a new signature \(or generate a signature again after you have checked the validity of the project ID and the key\) and resend the request.
-   `403 Forbidden`—the request has not been accepted due to lack of permissions to access the endpoint. In this case, contact the Ecommpay technical support to have the sender's IP address added to the IP whitelist.
-   `422 Unprocessable Entity`—the request has not been accepted because it contains a syntax error \(for example, a comma is missing\). In this case, correct the mistake and resend the request.
-   `500 Internal Error`—the request has not been accepted because the payment platform was unavailable. In this case, try resending the request later.

If you need information contained in the responses from the platform, set up their reception and processing.

```language-php
$headers        = [];
$headerCallback = function ($curl, $header_line) use (&$headers) {
    if (strpos($header_line, ":") === false) {
        return strlen($header_line);
    }
    list($key, $value) = explode(":", trim($header_line), 2);
    $headers[trim($key)] = trim($value);

    return strlen($header_line);
};

$absUrl = 'https://abs.url';
$curl = curl_init();

$opts[CURLOPT_URL]            = $absUrl;
$opts[CURLOPT_RETURNTRANSFER] = true;
$opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout;
$opts[CURLOPT_TIMEOUT]        = $this->timeout;
$opts[CURLOPT_HEADERFUNCTION] = $headerCallback;
curl_setopt_array($curl, $opts);
$rbody = curl_exec($curl);
$errno = curl_errno($curl);
if ($rbody === false) {
    $errno   = curl_errno($curl);
    $message = curl_error($curl);
    curl_close($curl);
    $this->handleCurlError($absUrl, $errno, $message);
}
$rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo "http code = ".$rcode."\n";
echo "http response = ".$rbody."\n";
```

```
package main

import (
	"fmt"
	"net/http"
	"time"
)

type conf struct {
	connectTimeout, timeout time.Duration
	returnTransfer          bool
}

func main() {
	absUrl := "https://abs.url"
	var cf = conf{10 * time.Second, 20 * time.Second, true}

	req, err := http.NewRequest(http.MethodGet, absUrl, nil)
	if err != nil {
		fmt.Printf("client: could not create request: %s\n", err)

		return
	}

	client := http.Client{
		Timeout: cf.timeout,
	}

	res, err := client.Do(req)
	if err != nil {
		fmt.Printf("client: error making http request: %s\n", err)
		handleError(err)

		return
	}

	fmt.Printf("http code = %d\n", res.StatusCode)
	fmt.Printf("http response = %s\n", res.Body)
}
```

### Receiving callbacks and sending response messages {#en_gate_quickstart_basic_implementation_callbacks}

When processing the payment, the platform sends two kinds of callbacks to the web service: *prescriptive* and *informational*.

*Prescriptive* callbacks are triggered by the necessity of a certain action: for example, specific data has to be sent to the payment platform, the customer must be provided with specific information or redirected to third-party services, and so on. Such callbacks always contain intermediate information, and timely response to this category of callbacks is indispensable for payments to be processed correctly.

*Informational* callbacks allow you to receive payment status and other important information.This information can be used for timely updates of order statuses in your web service, providing information to your customers and other purposes according to the way your web service operates. These callbacks can contain intermediate or final payment information \(for example, important events during payment processing or payment result information\).

To receive callbacks\(both prescriptive and informational\),

1.  Specify the URL designated for receiving callbacks by the web service within the project. This can be done via Dashboard in the **Projects** section with the use of the **Callbacks** tab tools.
2.  Set up the integrity validation and parsing of the callbackssent to the URL you have specified as it is crucial that callbacks with incorrect signatures are handled properly \(i.e. rejected\). You can use the code example presented belowto set up.
3.  Set up sending synchronous HTTP responses with the information about the callbacks receipt: `200 OK` if the signature is correct and `400 Bad Request` if the signature is incorrect.

```language-java
{
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "SONYA KOVALEVSKY",
        "id": 45678,
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "17008",
    },
    "payment": {
        "date": "2023-01-11T13:02:42+0000",
        "id": "Cosmoshop_purchase_2025-01-01_000001",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 8855,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2023-01-11T13:02:42+0000",
        "created_date": "2023-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 8855,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 8855,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2023-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

```language-php
require_once __DIR__ . 'signature.php';

//@todo net set to merchant project https://api.merchant.com/callback.php

//@todo set projectId
$projectId = null;
//@todo set paymentId 
$paymentId = '';
//@todo set secretKey
$secretKey = '';


$response = json_decode(file_get_contents('php://input'), true);

$rsignature = $response['signature'];

unset($response['signature']);


if ((new Signer($secretKey))->check($response, $rsignature)) {
    header('HTTP/1.1 200 OK');
    header('Status: 200 OK');
    echo "signature is correct\n";

    $projectId = $response['project_id'];
    $paymentId = $response['payment']['id'];

    //@todo save necessary info to merchant system
} else {
    header('Status: 400 Bad Request');
    header('HTTP/1.1 400 Bad Request');
    echo "signature is invalid\n";
}
```

```
package main

import (
	"encoding/json"
	"io/ioutil"
	"log"
	"net/http"
)

//@todo net set to merchant project https://api.merchant.com/callback.go

//@todo set project
type project struct{}

type request struct {
	Signature string `json:"signature"`
}

var prj project

//@todo set secretKey
var secretKey string

//@todo set paymentId
var paymentId string

//@todo get request
var r *http.Request

func main() {
	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		log.Printf("Error reading body: %v", err)
	}

	var req request

	err = json.Unmarshal(body, &req)
	if err != nil {
		log.Printf("Error parsing request: %v", err)
	}

	var w http.ResponseWriter

	if checkSignature(req, secretKey, req.Signature) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("signature is correct\n"))
	} else {
		w.WriteHeader(http.StatusBadRequest)
		w.Write([]byte("signature is invalid\n"))
	}
}

func checkSignature(req request, secretKey string, signature interface{}) bool {
}
```

This should be enough to move on to [testing](en_gate_quickstart.md), or you can continue reading for more in-depth information about responding to callbacksand move on to testing afterwards.

### Responding to callbacks {#en_gate_quickstart_basic_implementation_callbacks_for_cards}

#### General case {#section_dvf_bkh_yxb .section}

Responding to *informational* callbacks implies that you can configure collecting information from such callbacks for further useif required by the specifics of your web service operation.

Responding to *prescriptive* callbacks requires you to figure out how to perform actions that can be necessary for further payment processing.

That said, this step can be omitted now and performed later, after the initial setup and testing.

Prescriptive callbacks are typically triggered by the following events:

1.  Additional payment data is required: collect and send to the platform.

    In these cases, the callback contains the `clarification_fields` object with the list of parameters required to be sent to the platform in the subsequent request. As a rule, the platform requests customer information: first and last name, date of birth, billing address, and so on.

    ```language-json
    "clarification_fields":{
      "avs_data": [
      "avs_post_code",
      "avs_street_address"
      ]
    }
    ```

    Collection of required information in such cases can be carried out in any convenient way, which includes using the existing database or prompting the customer to fill in the corresponding fields in the web service's interface. You can learn more about working with this type of callbacks in [the section below](en_gate_quickstart.md) once you have finished the initial setup and testing. It is also important to mention here that these cases are not rare and require timely response from the web service.

2.  Redirection of the customer to the external service is required.

    In these cases, the callback contains the `acs`or the `redirectData` object with the URL for redirecting the customer and with additional information. Responding to such callbacks requires you to redirect the customer to the provided URL. You can use HTML page code for this purpose.

    ```language-json
    "acs":{  
      "pa_req":"eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em", 
      "acs_url":"https://example.com/ACS",
      "md":"eyJfto7jg456ZCI6IiJ9"
    }
    ```

    ```language-xml
    <form id="3dsform" action="https://example.com/ACS" method="post" enctype="application/
    x-www-form-urlencoded">
        <input type="hidden" name="PaReq" value="eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em" />
        <input type="hidden" name="TermUrl" value="http://example.com/termurl" />
        <input type="hidden" name="MD" value="eyJfto7jg456ZCI6IiJ9" />
    </form>
    <script type="text/javascript">
        setTimeout(function() {
            document.getElementById("3dsform").submit();
        }, 1000);
    </script>
    ```

    After the customer has been redirected to the URL received in the callback, you may need to receive additional information from the external service \(for example, the Access Control Server when the 3‑D Secure authentication is performed\) or expect another callback from the payment platform, which depends on the payment processing workflow and the specific aspects of the utilised payment method. You can learn about working with this type of callbacks in [the section below](en_gate_quickstart.md) once you have finished the initial setup and testing.

3.  Displaying information to customers is required.

    In these cases, callbacks usually contain the `display_data` object with the information that you need to show your customer\(for example, a text or a QR code\) and additional data.

    ```language-json
    "display_data": [
      {
         "type": "qr_data",
         "title": "QR Code",
         "data": "https://example.com/paygate/union/pay/MDAyMDUxNjk0OTMwNjYyMTQzMTgwOHwwNHw0ODgxMDAwMA=="
      },
      {
         "type": "add_info",
         "title": "QR Code Timeout",
         "data": "600"
      }
    ]
    ```

    These callbacks can be useful for processing payments with alternative payment methods. To learn more about working with alternative payment methods, go to [Payment methods](en_pm_about.md). We recommend you study this section once the initial setup and tests are done.


#### Card payments {#section_wqs_2kh_yxb .section}

When you work with card payments, callbacks for performing the 3‑D Secure authentication are the most frequently used intermediate callbacks. They usually contain data to redirect the customer directly to the issuer's service\(if the callback contains the `acs` object\) or the provider's service\(if the callback contains the `redirectData` object\). You can redirect the customer to the required page using the same HTML page code that was provided in the example above \(and presented here\).

```language-xml
<form id="3dsform" action="https://example.com/ACS" method="post" enctype="application/
x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em" />
    <input type="hidden" name="TermUrl" value="http://example.com/termurl" />
    <input type="hidden" name="MD" value="eyJfto7jg456ZCI6IiJ9" />

</form>
<script type="text/javascript">
    setTimeout(function() {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>
```

When the customer is redirected back from the issuer's service, you have to receive the authentication result information from the issuer, send it in the HTTP POST request to the platform, and accept the synchronous HTTP response to this request.If the customer is redirected back from the provider's service, the authentication result information will not be sent, and the web service will receive the payment result callback instead.

```language-php
require_once __DIR__ . 'signature.php';

//@todo set projectId
$projectId = null;
//@todo set paymentId 
$paymentId = '';
//@todo set secretKey
$secretKey = '';

$params = [
    'general'  => [
        'project_id' => $projectId,
        'payment_id' => $paymentId,
    ],
    "pares" => "",
    "md" => ""
];

$absUrl = 'https://api.ecommpay.com/v2/payment/card/3ds_result';

$params['general']['signature']  = (new Signer($secretKey))->sign($params);
$request                         = json_encode($params);

$curl = curl_init();
$opts = [];

$opts[CURLOPT_POST]       = 1;
$opts[CURLOPT_POSTFIELDS] = $request;
$opts[CURLOPT_HTTPHEADER] = ['Content-Type: application/json', 'Content-Length: '.strlen($request)];

$headers        = [];
$headerCallback = function ($curl, $header_line) use (&$headers) {
    if (strpos($header_line, ":") === false) {
        return strlen($header_line);
    }
    list($key, $value) = explode(":", trim($header_line), 2);
    $headers[trim($key)] = trim($value);

    return strlen($header_line);
};

$opts[CURLOPT_URL]            = $absUrl;
$opts[CURLOPT_RETURNTRANSFER] = true;
$opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout;
$opts[CURLOPT_TIMEOUT]        = $this->timeout;
$opts[CURLOPT_HEADERFUNCTION] = $headerCallback;
curl_setopt_array($curl, $opts);
$rbody = curl_exec($curl);
$errno = curl_errno($curl);
if ($rbody === false) {
    $errno   = curl_errno($curl);
    $message = curl_error($curl);
    curl_close($curl);
    $this->handleCurlError($absUrl, $errno, $message);
}
$rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo "http code = ".$rcode."\n";
echo "http response = ".$rbody."\n";
```

```
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type general struct{ project_id, payment_id, signature string }

type params struct {
	gnrl      general
	pares, md string
}

type conf struct {
	connectTimeout, timeout time.Duration
}
func main() {
	//@todo set project
	project := ""

	//@todo set secretKey
      var secretKey string

       //@todo set paymentId
       var paymentId string

	var cf = conf{10 * time.Second, 20 * time.Second}

	prms := params{
		gnrl:  general{project_id: project, payment_id: paymentId, signature: ""},
		pares: "",
		md:    "",
	}

	signature := sign(prms, secretKey)
	prms.gnrl.signature = signature

	absUrl := "https://api.ecommpay.com/v2/payment/card/3ds_result"
	reqBody, err := json.Marshal(prms)
	bodyReader := bytes.NewReader(reqBody)

	req, err := http.NewRequest(http.MethodPost, absUrl, bodyReader)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Content-Length", string(rune(bodyReader.Len())))

	client := http.Client{
		Timeout: cf.timeout,
	}

	res, err := client.Do(req)
	if err != nil {
		fmt.Printf("client: error making http request: %s\n", err)
		handleError(err)
		os.Exit(1)
	}

	defer res.Body.Close()

	fmt.Printf("http code = %d\n", res.StatusCode)
	fmt.Printf("http response = %s\n", res.Body)
}

func sign(par params, secretKey string) string {
	//@todo implement sign function
}
```

You can learn more about 3‑D Secure authentication in the [corresponding article](en_gate_payment_3ds.md), which you can explore after you have tested the initial implementation.

## Testing {#en_gate_quickstart_testing}

Once you have set up working with signatures, responses, and callbacks, you can start testing payment processing. In the test project, there are two available types of payment credentials: *special* test credentials, which allow you to test predefined payment scenarios, and *random* realistic credentials, which allow you to test a number of optional payment processing scenarios in various cases.

For bare minimum testing\(to process payments according to the shortest scenarios\), use the following numbers of test cards:

|Emulated scenario|Final payment result|
|Payment completed|Payment declined|
|-----------------|:-------------------|
|-----------------|:---------------|
|Purchase without 3‑D Secure|`4000 0000 0000 0077`|`4111 1111 1111 1111`|
|Purchase with 3‑D Secure|`4314 2200 0000 0056`|``5544 3300 0000 0045``|

For the purposes of the more comprehensive testing, you can use extended test data for [card](en_test_cards.md) paymentsand various [alternative](en_pm_testing.md) payments, as well as random data including credentials of cards, wallets, and other payment instruments. It allows you to test various payment processing scenarios including, for example, scenarios with the 3‑D Secure authentication without customer involvement.It is safe because all data in the test and the production environment is protected equally, even if in the test environment there are no actual payments taking place.

Once testing is completed, the basic functions for purchase processing can be considered implemented. If you want, you can then move on to different add-ons, which can already be helpful at the initial stages of working with the payment platform, and to the launch of the solution.

## Additional aspects {#en_gate_quickstart_additional_aspects}

### General monitoring of payment processing {#section_zhn_zxp_rxb .section}

After several test payments have been executed, you can explore how to monitor payment processing. You can use Dashboard—the user interface and Data API—the program interface. These interfaces allow you to access consolidated data about amounts, statuses, and other characteristics of the payments being processed, but there can be a delay of up to several minutes. To start monitoring, first, you have to obtain [access](en_dbl_overview.md) to Dashboard, then set up permissions to access the test project, and, if you need to work with the Data API, generate an API token and the secret key. Once this is done, you can move on to working with payment information.

To monitor payment processing in Dashboard, use the **Payments** section \(it contains information about all payment types\) and the specialised sections with information about specific payment types as well as individual payment information tabs. To learn more about using these sections, go to [Monitoring and performing payments](en_dbl_payments.md)

![](images/ecommpay/dbl/en_quickstart_dbl_overview.svg "Payments register")

![](images/ecommpay/dbl/en_quickstart_dbl_payment_details.svg "Payment information tab")

Data API contains endpoints you can send requests to in order to retrieve information about groups of payments or individual payments. You can learn more in [this section of the documentation](en_dbl_using_api.md).

### Checking current state of individual payments {#section_ohn_rbq_rxb .section}

To retrieve up-do-date information about the status of individual payments via the Gate API, send HTTP POST requests to the [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status) endpoint\(with identifiers of the project and the payment you need\) and receive synchronous HTTP responseswith the requested data.

```language-php
require_once __DIR__ . 'signature.php';

//@todo set projectId
$projectId = null;
//@todo set paymentId 
$paymentId = '';
//@todo set secretKey
$secretKey = '';

$params = [
    'general'  => [
        'project_id' => $projectId,
        'payment_id' => $paymentId,
    ]
];

$absUrl = 'https://api.ecommpay.com/v2/payment/status';

$params['general']['signature']  = (new Signer($secretKey))->sign($params);
$request                         = json_encode($params);

$curl = curl_init();
$opts = [];

$opts[CURLOPT_POST]       = 1;
$opts[CURLOPT_POSTFIELDS] = $request;
$opts[CURLOPT_HTTPHEADER] = ['Content-Type: application/json', 'Content-Length: '.strlen($request)];

$headers        = [];
$headerCallback = function ($curl, $header_line) use (&$headers) {
    if (strpos($header_line, ":") === false) {
        return strlen($header_line);
    }
    list($key, $value) = explode(":", trim($header_line), 2);
    $headers[trim($key)] = trim($value);

    return strlen($header_line);
};

$opts[CURLOPT_URL]            = $absUrl;
$opts[CURLOPT_RETURNTRANSFER] = true;
$opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout;
$opts[CURLOPT_TIMEOUT]        = $this->timeout;
$opts[CURLOPT_HEADERFUNCTION] = $headerCallback;
curl_setopt_array($curl, $opts);
$rbody = curl_exec($curl);
$errno = curl_errno($curl);
if ($rbody === false) {
    $errno   = curl_errno($curl);
    $message = curl_error($curl);
    curl_close($curl);
    $this->handleCurlError($absUrl, $errno, $message);
}
$rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo "http code = ".$rcode."\n";
echo "http response = ".$rbody."\n";

$response = json_decode($rbody, true);

$rsignrature = $response['signature'];

unset($response['signature']);

if ((new Signer($secretKey))->check($response, $rsignrature)) {
    echo "signature is correct\n";
} else {
    echo "signature is invalid\n";
}
```

```
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"math/rand"
	"net/http"
	"os"
	"time"
)

//@todo net set to merchant project https://api.merchant.com/callback.go

type general struct{ project_id, payment_id, signature string }

type params struct{ gnrl general }

type response struct {
	Signature string `json:"signature"`
}

func main() {
	//@todo set project
	project := ""
       //@todo set secretKey
       var secretKey string
       //@todo set paymentId
       var paymentId string

	prms := params{
		gnrl: general{project_id: project, payment_id: paymentId, signature: ""},
	}

	signature := sign(prms, secretKey)
	prms.gnrl.signature = signature

	absUrl := "https://api.ecommpay.com/v2/payment/status"
	reqBody, err := json.Marshal(prms)
	bodyReader := bytes.NewReader(reqBody)

	req, err := http.NewRequest(http.MethodPost, absUrl, bodyReader)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Content-Length", string(rune(bodyReader.Len())))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Printf("client: error making http request: %s\n", err)
		handleError(err)
		os.Exit(1)
	}

	defer res.Body.Close()

	fmt.Printf("http code = %d\n", res.StatusCode)
	fmt.Printf("http response = %s\n", res.Body)

	var respBody response
	b, err := io.ReadAll(res.Body)

	err = json.Unmarshal(b, &respBody)
	if err != nil {
		log.Printf("Error parsing response: %v", err)
	}

	rsign := respBody.Signature

	if checkSignature(respBody, secretKey, rsign) {
		fmt.Printf("signature is correct\n")
	} else {
		fmt.Printf("signature is invalid\n")
	}
}

func sign(par params, secretKey string) string {
	//@todo implement sign function
}

func checkSignature(resp response, secretKey string, signature interface{}) bool {
	//@todo implement checkSignature function
}
```

If you have any questions about checking payment status information via Gate, go to [the corresponding article](en_Gate_payment_status_request.md).

### Refunds {#section_vzx_hdq_rxb .section}

If refunding a purchase is required, you can use Dashboard and Gate.

In Dashboard you can open the payment information tab of the payment to be refunded and use the **Refund** button. You can also send batch requests using files \([details](en_dbl_payments.md) \).

When working via Gate, you can send a request to theendpoint of the payment method that was used to perform an initial purchase. In case of card payments, send a request to the [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund) endpoint.

Each request to refund a card purchase must contain the project and payment identifiers and the description of the reason to refund. Together with the required data, you can also specify the amount and the currency code of the refund if you need to issue a partial refund of the purchase amount. In such cases, the currency code must match the currency code of the initial payment. If not, the request will be declined. For more in-depth understanding of issuing refunds, go to [Purchase refunds](en_Gate_Refund.md).

```language-json
{
  "general": {
    "project_id": 42,
    "payment_id": "Cosmoshop_purchase_2025-01-01_000001",
    "signature": "of8k9xeKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },
  "payment": {
    "description": "Item return"
  }
}
```

```language-json
{ 
  "project_id":42,
  "payment":{
    "id":"Cosmoshop_purchase_2025-01-01_000001",
    "type":"purchase", // Payment type: one-time purchase
    "status":"refunded", // Payment status after full refund
    "date":"2023-01-12T15:20:36+0000",
    "method":"card",
    "sum":{ 
      "amount":0, // Updated payment amount after full refund
      "currency":"USD" // Payment currency code
    }
  },
  "account":{
    "number":"424242******4243",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"SONYA KOVALEVSKY",
    "expiry_month":"05",
    "expiry_year":"2025"
  },
  "customer":{
    "id":"17008"
  },
  "operation_description":"Item return", // Refund reason description
  "operation":{
    "id":3861,
    "type":"refund", // Operation type
    "status":"success", // Operation status
    "date":"2023-01-12T15:21:00+0000",
    "created_date":"2023-01-12T15:20:58+0000",
    "request_id":"67a97cd6b14f1aa0543c81e18cd270b66-aadc6e790206d5-00038611",
    "sum_initial":{ 
      "amount":8855, // Refund amount
      "currency":"USD" // Refund currency code (matches initial payment currency)
    },
    "sum_converted":{
      "amount":8855,
      "currency":"USD"
    },
    "code":"0",
    "message":"Success",
    "provider":{
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}
```

### Setting up processing of other payment types {#section_wzz_dgq_rxb .section}

Once you set up accepting card purchases, you can move on to other payment typesand other payment methods.To learn how different payment types are processed in the payment platform, set up processing of payment types and payment methods, you need go to [the section](en_platform_payment_model.md) with the description of supported payment types and their possible statusesand [the section](en_pm_about.md) with the description of alternative payments specifics.

### Using auxiliary procedures and additional capabilities {#section_prd_ljq_rxb .section}

Processing payments via Ecommpay payment platform may involve various *procedures* and *capabilities*. Auxiliary procedures are required in certain cases, for example, when authentication of customers is needed. These procedures can be required for payment processing, which is why it is important that you know how to work with them. Additional capabilities, on the other hand, do not get in the way of payment processing andcan be used if the merchant expresses the need for them; however, they do improve the quality of the provided service.

Once you have set up processing purchases, as described in this guide, it can be useful to set up performing procedures and capabilities that can be needed due to the specific characteristics of your web serviceand the payment methods used. These procedures and capabilities may include:

-   [Submission of additional payment information](en_Gate_Clarification.md)—to ensure timely submission of additional data that can be requested by payment systems.
-   [3‑D Secure authentication](en_gate_payment_3ds.md)—to provide customer authentication for processing card payments.
-   [Sending notifications to customers](en_gate_receipts.md)—to inform customers about payment processing results and other events via email.

You can also implement other procedures and capabilities described in[Auxiliary procedures](en_gate_procedures.md) and [Additional capabilities](en_Gate_Additional_capabilities.md).

## Launch {#en_gate_quickstart_launch_project}

After implementing the basic functions, testing needed capabilities, and defining the user scenarios and workflows relevant for you, you can proceed to the launch of the production project. Make sure that by this time all organisational issues have been resolved. Then all you will have to do is to configure the project settings on the payment platform side and begin to use the identifier and the key of the production project.

Following the launch, you can continue your work on configuring various payment types, payment methods, and capabilities depending on the needs of your business. Please refer to our specialists with feedback and any other questions.

Good luck!



---

# Interaction concepts {#en_gate_interaction_organisation}

An article about organising the work with Gate on the web service side based on the principles of the payment platform operation and the utilised interaction flows and formats.

Gate is an application programming interface \(API\) intended to accept requests from merchant's web services to the Ecommpay payment platform. Gate conforms to the Representational State Transfer \(REST\) architectural style and is backward compatible, in other words, all components developed for any older version of Gate work correctly with the current version without changing program code on the web service side.

Gate can be accessed by using the following URL: `https://api.ecommpay.com`. Gate accepts requests that use the HTTP protocol, version 1.1 or higher and TLS of version 1.2 or higher. The Gate specification is available at [https://api-developers.ecommpay.com](https://api-developers.ecommpay.com).

This section describes how to integrate by using Gate and covers technical integration aspects.

**Parent topic:**[Gate](en_Gate_Integration_About.md)

## Integration steps {#en_gate_integration_step}

To integrate with the Ecommpay payment platform by using Gate, the merchants should do the following:

1.  Address the following organisational issues of interaction with Ecommpay:

    1.  If the company has not obtained the project identifier or a secret key from Ecommpay, submit [the application](https://ecommpay.com/apply-now/) for connecting to the Ecommpay payment platform.
    2.  For processing payments made with the Visa and Mastercard cards, provide the Ecommpay key account manager with the documents of compliance with [the PCI DSS requirements](en_faq_integration.md#fig_fgk_rgs_4nb). The following documents are required:
        -   From all merchants—[the ASV scan](en_glossary.md) report.

            ASV scanning must be performed by the authorised scanning service providers \(PCI SSC Approved Scanning Vendor, ASV\) quarterly and after every significant change in the network infrastructure.The Ecommpay merchants can select these providers on their own and, if relevant, involve a provider that is in partnership with Ecommpay. To have the scanning services via the partner organised, contact the key account manager.

        -   From the merchants processing over 6 million operations annually \(Level 1\)—the Attestation of Compliance, AOC.
        -   From the merchants processing to 6 million operations annually \(Levels 2, 3, and 4\)—[the Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment), SAQ.

            With questions on completing the questionnaire, contact the Ecommpay key account manager.

    3.  Coordinate the procedures of integrating with the payment platform, testing\(including testing various payment methods\), and launching the functionality with the Ecommpay technical support specialists.
2.  Update the code of the web service to integrate with the Ecommpay payment platform by using Gate.
3.  Test the integration solution and launch it in coordination with the Ecommpay technical support specialists.

    Upon testing and monitoring, in case of correct payment processing in the production mode, the Ecommpay technical support specialists interact with the web service in the full-time support mode.


With any questions about using Gate, contact the Ecommpay key account manager and technical support specialists \([support@ecommpay.com](mailto:support@ecommpay.com)\).

## Interaction models {#en_gate_interaction_scheme}

The Ecommpay payment platform and merchant's web service interact by exchanging request and reply messages in the HTTP format: the web service issues requests and the payment platform responds to those requests. This interaction model supports two interaction models: *synchronous* and *asynchronous*. If the payment platform is able to respond to request without resorting to any third parties such as customer or external payment system, it uses the synchronous model; otherwise the payment platform uses the asynchronous model.

### Synchronous model {#section_bc4_fsh_thb .section}

The payment platform uses *the synchronous interaction model* when it can generate the response by using only its own data and resources, for instance to return the current status of payment. Synchronous interaction is performed in a single HTTP session and allows you to send only one response. Normally, the time between the payment platform receives the request issued by the web service and the payment platform sends out the response is less than 100 ms.

![](images/en_gate_sync.svg "Synchronous request processing")

### Asynchronous model {#section_sdm_hsh_thb .section}

*The asynchronous interaction model* is used when to generate response, the payment platform needs to communicate with third parties, for instance when it processes payment which requires input from customer and/or payment system.

In this model, the payment platform sends the following to merchant web service: acknowledgement that initial request is accepted and successfully validated *and* the callback with final result \(in case initial request is successfully validated\). The model may also include exchange of messages with intermediate results between those two responses, for instance the payment platform may issue redirect to a form exposed by payment system.

Normally, the time between web service issues the initial request and the Ecommpay payment platform sends out the first response is less than 100 ms; though, the time between request receiving and callback sending may vary depending on third parties that are involved in request processing.

![](images/en_gate_async.svg "Asynchronous request processing")

To ensure correct asynchronous interaction with the payment platform, you need to properly implement reaction to callbacks you obtain from the payment platform. The reaction to the callbacks with intermediate results depends on the information the callbacks contain while the reaction to the callback with final result require send the receipt acknowledgement HTTP response:

-   If the callback was successfully processed, specify HTTP `200 OK` status code. The response may not include a response body.
-   If an error was detected while handling a callback, specify HTTP error status code. It is recommended to provide one that are clearly defined the type of error and registered in the HTTP specification.

The payment platform sends callbacks while web service returns the `200 OK` response.

```
HTTP/1.1 200 OK
Date: Fri, 07 Jun 2019 11:38:32 GMT
Content-Type: text/plain;charset=UTF-8
Content-Length: 2
Connection: keep-alive
                    
OK
```

## Request handling {#en_gate_requests_processing_scheme}

Within any interaction models interaction begins with a request which is sent from the web service to the Ecommpay payment platform. When the payment platform receives a request, there are three stages in the lifetime of request handling as follows:

-   On the stage of request acceptance, the payment platform performs various preliminary tasks including reading and parsing a JSON string contained in the request, as well as checking for the minimum number of parameters in JSON.
    -   If the payment platform is able to parse the JSON string and the minimum number of parameters is specified the JSON, the request is sent through to the stage of request processing. If the payment platform uses an asynchronous model, the payment platform sends a HTTP response with information that the request has been accepted for processing.
    -   If the payment platform encounters errors, the request handling is stopped. Within any interaction models, the payment platform sends a HTTP response showing error condition.
-   During the stage of request processing the payment platform performs Gate specification compliance checks, as well as data semantic consistency checks and signature validity.
    -   If the payment platform does not encounter errors in the data extracted from the JSON string, the request is sent through to the stage of request execution. In this case, the payment platform does not send a HTTP response. For the request initiating a payment, a payment is registered in the platform and a `payment` object is created.
    -   If the payment platform encounters errors in the data, the request handling is stopped. If the payment platform uses a synchronous model, the payment platform sends a HTTP response showing error condition; if the payment platform uses an asynchronous model, it sends a callback.
-   During the stage of request execution the payment platform performs Gate specification compliance checks, as well as data semantic consistency checks and signature validity.
    -   If the payment platform successfully executes the request, it returns result. If the payment platform uses a synchronous model, it responds with an HTTP response with the result; if the payment platform uses an asynchronous model, it responds with a callback with the result.
    -   If the payment platform unsuccessfully executes the request, it stops request handling and returns error result. If the payment platform uses a synchronous model, it responds with an HTTP response with the requested data; if the payment platform uses an asynchronous model, it responds with a callback with the result.

Normally, the time between the payment platform receives the request and it responds with the first response is less than 100 ms in any cases. If no response is received, the web service may repeat the request with the same data \(and the same payment identifier for payment processing request\). In case of `4xx` error response, the web service should resend the request with a new or replaced data.

## Data formats {#en_Gate_Formats}

### Overview {#section_hgq_qwb_wvb .section}

When working with the Gate API, as well as other interfaces of the Ecommpay payment platform, you should use only the permitted data encoding methods and formats.General information about them can be found in this article and [the Gate API specification](https://api-developers.ecommpay.com/). In addition, you can use the specialised [references](en_directory.md), descriptions of specific payment methods in the [corresponding section](en_pm_about.md), and articles about additional capabilities. Besides, you can contact the Ecommpay support specialists with any questions about data formats that arise.

### Data encoding {#section_kkg_kjl_bbb .section}

The generation of requests sent to the platform and the processing of responses and callbacks received from the platform must be carried out with the use of the UTF-8 encoding. In addition, in some cases you have to use other encoding methods, for example, Base64.Such cases are stipulated in this documentation and [the Gate API](https://api-developers.ecommpay.com/) specification.

### Dates and times {#section_db4_ckl_bbb .section}

In the scope of interaction with the platform, dates and times are usually represented in the `YYYY-MM-DDThh:mm:ss±hh:mm` format \(according to the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) requirements\), where `YYYY-MM-DD` is a date, `T` is a separating character, `hh:mm:ss` is time, `hh:mm` is a UTC \(Coordinated Universal Time\) offset. For example, `2025-05-25T15:30:25+00:00`.

Along with that, in some cases the date and time format can differ from the described above.Such cases are stipulated in this documentation and [the Gate API](https://api-developers.ecommpay.com/) specification.

### Amounts {#section_okf_xjl_bbb .section}

In the scope of interaction with the platform, payment and operation amounts are specified, as a rule, in the smallest units of currency and with no decimal separator. For example, 100 US dollars are represented in cents and specified as 10000 \(not as 100 or as 100.00\).The examples of other currencies representation are provided in the table.

|Currency|Amount|Representation|
|--------|------|--------------|
|EUR|39.95|`3995`|
|GBP|450.66|`45066`|
|JPY|200|`200`|
|KWD|150.155|`150155`|

The number of decimal digits for different currencies is defined according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard and provided [in the reference with currency codes](en_currency_codes.md).

### Currency, country, and language codes {#section_iq3_dkl_bbb .section}

In the scope of interaction with the Ecommpay payment platform, the following codes can be used:

-   three-letter *currency codes*—according to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard
-   two-letter *country codes*—according to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) standard
-   single-, two-, and three-character *territory codes* \(such as states, provinces, and regions\)—according to the [ISO 3166-2](https://www.iso.org/iso-3166-country-codes.html) standard
-   two-letter *language codes*—according to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard

These codes, except for territory codes, can be found [in the references](en_directory.md).

## Request format {#en_gate_requests_format}

All the HTTP requests to the payment platform submitted through Gate must use the POST method. This section covers the structure of such requests; for the information about structure of the data transferred inside the requests to Gate, see [API](https://api-developers.ecommpay.com/).

### Structure {#section_chd_1p2_xhb .section}

Each HTTP request to the payment platform must include the following elements:

-   The start line which contains the following: the HTTP method which always is `POST`, the endpoint in Gate \(for instance [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status)\), and the protocol, and its version \(normally it is `HTTP/1.1`\).
-   The header with the `Host` field that contains the domain name of the Gate API \(for instance, `api.ecommpay.com`\).
-   An empty line which serves as a separator between the message header and the body.
-   The message body, or payload, that contains JSON string in the form of UTF-8 with request data including the signature.

Besides the mandatory `Host` field, the header may include any other fields supported by [HTTP version 1.1](https://tools.ietf.org/html/rfc2616#page-31). Below you will find a sample HTTP request with recommended header fields. The JSON string is formatted for better readability.

```
POST /v2/payment/status HTTP/1.1
User-Agent: curl/7.29.0
Host: api.ecommpay.com
Accept: */*
Content-Length: 179
Content-Type: application/x-www-form-urlencoded
                    
{
    "general": {
    "project_id": 1,
    "payment_id": "ID_184",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tawY3T\/pOMeSaRfBaNIipTv+AWoXW\...=="
  }
}

```

### Addressing parameters {#section_b3q_bsx_thb .section}

The requests the merchant web service generates must include the basic and the relative addresses. The basic address for Gate requests is `api.ecommpay.com`; the relative address is the path to target endpoint in Gate.

**Note:** Therefore, the complete address takes the following format: `https://{<*Gate domain name*>}/{<*target endpoint path*>}`. Here is an example of the address for the payment status request: [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status). Normally, the complete addresses are not used for generating POST requests.

### Message body {#section_kdx_ptx_thb .section}

The message body must contain request data in the JSON format. The JSON string follows the format `"<parameter name>": <parameter value>`. To prevent data eavesdropping when transferring data to the payment platform, you must sign messages and include the signature inside the request data. Also, to secure data transfer you need to use the TLS 1.2 encryption protocol. For more information about generating signature, see [Signature generation and verification](en_platform_signature.md).

Here is an example of a JSON code with all the information to request current payment status from the payment platform. Because this is the status request, you do not need to specify payment amount and currency.

```
{
    "general": {
      "project_id": 2990,
      "payment_id": "payment_id",
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    }
```

## Response format {#en_gate_responses_format}

The Ecommpay payment platform responds with an HTTP response message to each request received from the web service within the same HTTP session. The requested data of the response body varies depending on the interaction model and the result of request handling. The response can contain the following:

-   Requested data—if the payment platform successfully handles the request and uses a synchronous model.
-   Information that request is accepted for processing—if the payment platform successfully accepts the request for processing and uses an asynchronous model.
-   Extended error description—if the payment platform cannot handle the request using a synchronous model or cannot accept the request for processing using an asynchronous model.

This section covers the structure of such responses as well as their status codes and statuses used to indicate the request status; for information about the unified response codes used in the data transferred within the responses, see [Handling operation processing information](en_platform_payment_info_codes.md).

### Structure {#section_c2t_tbm_xhb .section}

Each HTTP response to the web service includes the following elements in the given order:

-   The status line which contains the following: the protocol and its version \(usually, it is `HTTP/1.1`\), status code and reason phrase \(for instance, `200 OK`\).
-   Header fields.
-   An empty line which serves as a separator between the message header and the body.
-   The message body, or payload, that contains JSON string in the UTF-8 encoding with response data.

### Status code {#section_aj3_knq_13b .section}

Status codes are used in status line to communicate successful or failed request acceptance or execution as well as to provide error causes. These status codes and reason phrases are listed in the following table.

|Status code|Description|
|-----------|-----------|
|200 OK|*Synchronous model*: The request has been successfully executed. The response body has the requested data.

 *Asynchronous model*: The request has been successfully accepted. The response body has the requested result. You can expect callbacks with intermediate or final results.

|
|400 Bad Request|The request cannot be accepted because of the missing mandatory parameter in JSON string, for instance, a project identifier.|
|403 Forbidden|The request cannot be accepted because access to the requested \(valid\) endpoint is forbidden, for instance, when the IP address from which the request has been sent is not allowed.|
|422 Unprocessable Entity|The request cannot be accepted because of malformed syntax in JSON string, for instance, a comma is missing.|
|500 Internal Error|The request cannot be processed because of the payment platform error.|

### Request status {#section_jmx_knq_13b .section}

Response body may include the `status` parameter to communicate that the request has been or has not been accepted for processing. There are two statuses:

-   `success`—the request is accepted for processing. This status is specified in responses with `200` status-code only if the payment platform handles request asynchronously.
-   `error`—the request is not accepted for processing. This status is specified in responses with `400`, `403`, `422` and `500` status-codes for both asynchronous and synchronous request handling.

### Synchronous responses {#section_rn2_tm2_yhb .section}

This section covers sample responses to synchronously handled requests. JSON string is formatted for better readability.

If the payment platform successfully handles the request, it responds with the status line including `200` code as well as the response body including the requested data without status.

```
POST /v2/payment/status HTTP/1.1        // The web service request for checking the payment status
                    
HTTP/1.1 200 OK                                  // The payment platform response
Server: api.ecommpay.com
Date: Wed, 22 May 2019 10:27:49 GMT    
Content-Type: application/json; charset=UTF-8
Content-Length: 875
Connection: keep-alive
Keep-Alive: timeout=60
Cache-Control: no-cache
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Origin: *
X-Powered-By: PHP/7.0.32
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type
Expires: Wed, 22 May 2019 10:27:48 GMT

{
	"project_id":665,
	"payment":{
		"id":"E2E__S02_0.53381200_1558520409",
		"type":"purchase","status":"success",
		"date":"2019-05-22T10:20:20+0000",
		"method":"cup-card",
		"sum":{
			"amount":100,
			"currency":"CNY"
		},
	"description":"Success from PP"
	},
	"account":{
		"number":"628888******8888"
	},
	"customer":{
		"id":"Vally Vasya"
	},
	"operations":[{
		"id":3259141213429,
		"type":"sale",
		"status":"success",
		"date":"2019-05-22T10:20:20+0000",
		"created_date":"2019-05-22T10:20:13+0000",
		"request_id":"e0d69edf1c3aac249e",
		"sum_initial":{
			"amount":100,
			"currency":"CNY"
		},
	"sum_converted":{
		"amount":100,
		"currency":"CNY"
	},
	"provider":{
		"id":1379,
		"payment_id":"1558520414466",
		"date":"2019-05-22T10:20:14+0000",
		"auth_code":""
	},
	"code":"0",
	"message":"Success"
	}],
	"signature":"p6BvZTmzzzUSaN06OVT2SNxTJWvm6\/GEOSEMvUaKgLGzVO5VpKKWt27rq\
	/D1HulyqMGvV0+yN6ixICqSW3oCeA=="
}
```

If the payment platform cannot handle the request, it responds with the status line including error code \(for instance `422`\) as well as the response body including `error` status and extended error description with the error code that the payment platform provided \(for instance `2003`\) and its description \(for instance `Invalid JSON string`\).

```
POST /v2/payment/status HTTP/1.1         // The web service request for checking the payment status
                    
HTTP/1.1 422 Unprocessable Entity                 // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:44:26 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 30 May 2019 09:44:25 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,
User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"status":"error",
	"code":"2003",
	"message":"Invalid JSON string"
}
```

### Asynchronous responses {#section_zxw_5m2_yhb .section}

This section covers sample responses to asynchronously handled requests. JSON string is formatted for better readability.

If the payment platform successfully accepted the request for processing, it responds with the line including `200` code as well as the response body including the `success` status.

```
POST /v2/payment/card/auth HTTP/1.1        // The web service request for holding funds
                    
HTTP/1.1 200 OK                                     // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:52:16 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 30 May 2019 09:52:15 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"status":"success",
	"request_id":"e7cdefae67068d",
	"project_id":69,
	"payment_id":"ORDER_ID__sendPurchase_dcc_1"
}
```

If the payment platform cannot handle the request, it responds with status line including error code \(for instance `400`\), as well as response body including `error` status and extended error description with the error code that the payment platform provided \(for instance `2004`\) and its description \(for instance `Required field not provided`\).

```
POST /v2/payment/card/auth HTTP/1.1    // The web service request for holding funds
                    
HTTP/1.1 400 Bad Request                        // The payment platform response
Server: nginx/1.14.2
Date: Thu, 30 May 2019 09:23:23 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33

{
	"status":"error",
	"code":"2004",
	"message":"Required field not provided"
}
```

## Callback format {#en_gate_callbacks_format}

In asynchronous interaction model, the Ecommpay payment platform returns intermediate and final results with callbacks to the web service URIs. This section covers the structure of callbacks; for detailed information about callbacks, see [Handling callbacks](en_platform_callbacks.md).

Each callback from the payment platform must include the following elements:

-   The start line which contains the following: the HTTP method which always is `POST`, the web service endpoints for callbacks with results \(for instance, `/notify/success`\), and the protocol, and its version \(normally it is `HTTP/1.1`\).
-   The header with the `Host` field that contains the domain name of the web service \(for instance, `webservice.com`\).
-   An empty line which serves as a separator between the message header and the body.
-   The message body, or payload, that contains JSON string in the form of UTF-8 with result data including the signature.

Below you will find a sample callback with payment result. JSON string is formatted for better readability.

```
POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
	"account":{
		"number":"431422******0056",
		"token":"1234567890",
		"type":"visa",
		"card_holder":"TEST TEST",
		"id":1234,"expiry_month":"**",
		"expiry_year":"****"
	},
	"customer":{
		"id":"12345",
		"phone":"***********"
	},
	"payment":{
		"date":"2019-06-07T11:38:31+0000",
		"id":"1234567890",
		"method":"card",
		"status":"success",
		"sum":{
			"amount":1750,
			"currency":"EUR"
		},
		"type":"purchase",
		"description":"Deposit to 1234567890"
	},
	"project_id":25,
	"processingDateTime":"2019-06-07T11:38:30+0000",
	"country":"GB",
	"product_name":"Visa",
	"issuer_name":"",
	"operation":{
		"id":1234567890,
		"type":"sale",
		"status":"success",
		"date":"2019-06-07T11:38:32+0000",
		"created_date":"2019-06-07T11:37:56+0000",
		"request_id":"1234567890-1234567890",
		"sum_initial":{
			"amount":1750,
			"currency":"EUR"
		},
		"sum_converted":{
			"amount":1750,
			"currency":"EUR"
		},
		"provider":{
			"id":11,
			"payment_id":"098765432",
			"date":"2019-06-07T11:38:30+0000",
			"auth_code":"","endpoint_id":1
		},
		"code":"0",
		"message":"Success",
		"eci":"05"
	},
	"signature":"qwertyuioiuytrewqwertyuu123434"
}
```



---

# One-time purchases {#en_Gate_purchase .concept}

Articles about processing via Gate one-time purchases with immediate debiting of funds \(one step\) and with debiting of funds after placing an authorization hold \(two steps\).

This section covers information on processing of one-time purchases.General information, which extends the section about payment models and statuses \([Payment processing](en_platform_payment_model.md)\), is applicable to payments with payment cards and payments by using alternative instruments, while the detailed information is only applicable to payments with payment cards. For more information about payments by alternative instruments, see [Methods](en_pm_about.md).

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` object containing information about the start and end dates of the booked service \([details](en_gate_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

*One-time purchase* is a payment type which makes a one-time transfer of funds from customer to merchant. The Ecommpay payment platform supports the following *types* of one-time purchases:

-   *One-step purchase*, or *one-time one-step purchase*, is a payment type which uses only one request to make a one-time transfer of funds from customer to merchant.You can use this purchase type toprocess payments by using payment cards and alternative payment instruments and to implement repayment of loans issued by microlenders. The purchase workflow and format of requests and callbacks are covered in greater detail in the following section: [One-step purchase](en_gate_payment_sale.md).
-   *Two-step purchase*, or *one-time two-step purchase*, is a payment type which uses two steps to make a one-time transfer of funds from customer to merchant. On the first step, merchant initiates an authorization hold—in other words, the purchase amount is deducted from the credit limit of customer's card account. On the second step, the purchase amount is 'captured', or, in other words, it is transferred to the merchant account based on the merchant request or after specific time lag.Two-step purchases are supported for payment processing by using payment cards and alternative payment instruments.The purchase workflow and format of requests and callbacks are covered in greater detail in the following section: [Two-step purchase](en_gate_payment_auth.md).


Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_sms_model.md).

-   **[One-step purchase](en_gate_payment_sale.md)**  
An article about processing via Gate one-time one-step purchases with immediate debiting of funds.
-   **[Two-step purchase](en_gate_payment_auth.md)**  
An article about processing via Gate one-time two-step purchases that comprise placing an authorization hold and subsequent debiting of funds.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# One-step purchase {#en_gate_payment_sale}

An article about processing via Gate one-time one-step purchases with immediate debiting of funds.

**Note:** This article covers processing one-time one-step purchases via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time one-step purchases:

-   [One-time one-step purchase](en_platform_sms_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing one-time one-step purchases in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing one-time one-step purchases via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

**Parent topic:**[One-time purchases](en_Gate_purchase.md)

## Overview {#en_gate_payment_sale_overview}

When performing an one-time one-step purchase, you can use one of the following options to transfer payment details:

-   *Transfer of complete payment details*. This is a basic option in which you collect all payment details from the customer, and then submit the data inside a payment request. MO/TO \(Mail Order/Telephone Order\) payment is a special case in which you transfer complete payment details. MO/TO is a card-not-present payment in which a customer may phone or email the merchant, place an order and pay by providing the payment card details over the phone or by email. For more information about MO/TO payments, see [MO/TO payment processing](en_Gate_moto.md).
-   *Transfer of payment details identifier*. To enable this option, you need to perform an initial COF payment. Once you do this, the payment platform creates a payment instrument record and returns a callback with the ID of the record in the `account_id` or `card_id` parameter. You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials, see [Saving payment data](en_gate_saved_data.md)
-   *Transfer of payment token*. To enable this option, you need to perform an initial payment. Once you do this, the payment platform creates a payment token and returns a callback with the token in the `token` parameter. You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials. For more information about using tokens, see [Using tokens](en_Gate_Token.md).

## Workflow {#en_gate_payment_sale_workflow}

When processing a one-step purchase by using Gate, the merchant web service is required to do the following:

1.  Send the one-step purchase request with payment details to one of the relevant endpoints in the following group: `/v2/payment/\{payment method\}/sale[/specifying payment details]`.
2.  If necessary, complete the additional procedures:
    -   *3‑D Secure authentication*. This authentication is intended to provide security to online payments by payment cards. For more information on the authentication workflow, as well as request and callback formats, see [3‑D Secure authentication](en_gate_payment_3ds.md).
    -   **Customer authentication on merchant's request**. This authentication is intended to make purchases with payment cards more secure. For more information on the authentication workflow, as well as request and callback formats, see [Authentication on merchant's request](en_gate_payment_merch_auth.md).
    -   *Additional payment information submission*. This procedure is intended for cases in which the initial request did not contain the information needed by one of the payment process stakeholders. For more information on this procedure, see [Submission of additional payment information](en_Gate_Clarification.md).
3.  Receive a callback with the payment result from the payment platform.
4.  If needed, after completing a one-time one-step purchase you can return your customers their money, if the payment method supports refunds. For more information on this procedure, see [Purchase refunds](en_Gate_Refund.md).

The following diagram provides the detailed picture of an ordinary one-step purchase processing procedure without additional requests.

![](images/purchase_schemes/en_gate_sale.svg)

1.  Customer initiates a purchase on the merchant web service.
2.  The web service sends the request for processing a one-step purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request for processing a one-step purchase by using Gate.
4.  The payment platform performs the request acceptance that includes validation of the required parameters and signature.
5.  The payment platform sends to the web service response with request receipt confirmation and correctness check result.
6.  The payment platform performs the internal request processing and sends it to the card organisation.
7.  The card organisation performs the internal request processing and sends it to the issuer.
8.  The issuer performs the internal request processing and debiting customer account.
9.  The issuer sends the callback with a one-step purchase result to the card organisation.
10. The card organisation sends the callback with a one-step purchase result to the Ecommpay payment platform.
11. The payment platform sends the callback to the web service.
12. The customer receives the payment result from the web service.

The sections that follow discuss in greater detail the request format and the required parameters and the information about the format of callbacks with payment results. Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_sms_model.md).

## Request format {#en_gate_payment_sale_request_format}

In this section the presented request format is applicable to one-step purchases made with *payment cards*.When performing requests the following needs to be considered:

1.  The request is sent by using POST \(HTTP\) method to one of the following endpoints:
    -   when indicating complete card credentials—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
    -   when indicating the identifier instead of card credentials—[/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)
    -   when indicating the token instead of card credentials—[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)
2.  The following objects and parameters should be specified in the request:

    -   Object `general`—general request identification information:
        -   `project_id`—the project ID obtained from Ecommpay
        -   `payment_id`—payment ID unique within the project
        -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object `customer`—customer information:
        -   `ip_address`—IP address
        -   `id`—the ID of the customer within the merchant project
        -   `screen_res`—screen resolution of the customer's device, in pixels, with an `x` character as a delimiter \(for example, `360x640`\)
        -   `email`—customer's email
        -   `phone`—customer's phone number
    -   Object `payment`—payment information:
        -   `amount`—payment amount in minor units
        -   `currency`—payment currency in the ISO-4217 alpha-3 format
    **Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` object containing information about the start and end dates of the booked service \([details](en_gate_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

3.  The request should contain the following customer's payment card information:
    -   when indicating complete card credentials—the following data in the `card` object:
        -   `pan`—card number
        -   `year`—year of expiration date
        -   `month`—month of expiration date
        -   `card_holder`—name of the cardholder, passed if this parameter is required for the specific project \(the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\)
        -   `cvv`—card verification code \(as indicated on the card\). This parameter is not necessary for processing of MO/TO payments. For more information, see [MO/TO payment processing](en_Gate_moto.md)
    -   when indicating the identifier—the identifier which is associated with the card credentials in the payment platform in the `saved_account_id` parameter, and the card verification code in the `cvv` parameter
    -   when indicating the token—token in the `token` parameter and the card verification code in the `cvv` parameter
4.  The request should contain the `return_url` object with the addresses for redirecting the customer to the web service:
    -   `success`—the URL for redirecting the customer after the payment is completed
    -   `decline`—the URL for redirecting the customer after the payment is declined
5.  Depending on specific regional requirements and requirements of providers and payment systems, you may be required to add the following additional user information:

    -   `first_name`—first name
    -   `last_name`—last name
    -   `middle_name`—middle name \(or patronymic\)
    -   `day_of_birth`—birth date
    -   `phone`—phone number
    -   `email`—email address
    -   `zip`—post code of residence location
    -   `address`—address \(street, house number\)
    -   `city`—city of residence \(town, village, etc.\)
    -   `district`—district of residence
    -   `state`—region of residence \(state, county, canton, etc.\)
    -   `avs_post_code`—post code registered with issuer as customer's actual post code
    -   `avs_street_address`—street and house number registered with issuer as customer's actual address
    If some parameters are missing from request submitted by your web service, the payment platform may require the web service to submit additional payment information. \(For more information, see [Submission of additional payment information](en_Gate_Clarification.md)\). For detailed information what parameters are required is you specific case, refer to your account manager at Ecommpay.

6.  If required, you can also add any other additional parameters Gate supports.

Thus, to perform a one-step payment by a payment card, the request must include project and payment IDs, signature, IP-address of the customer, currency and amount of payment, as well as information about the payment card, as shown in the following example:

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12",
      "screen\_res": "360x640",
      "phone": "44991234567",
      "email": "john\_smith@email.com"
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },

//when indicating complete card credentials:
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//when indicating the identifier of a stored payment card:
    "saved_account_id": 2345678,
    "cvv": "123"

//when indicating the token of a stored payment card:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}
```

## Customer redirection data format {#en_gate_payment_sale_redirect_form}

In dependence on the payment system to complete the payment, you may need to redirect a customer from the web service to the payment system side. To perform the redirection, you must receive a callback from the payment platform containing the URL for redirection in the `redirect_data` object with the following parameters:

-   `redirect_data.url`—URL to redirect a customer
-   `redirect_data.body`—data for request sending \(may be null\)
-   `redirect_data.method`—request sending method

The following is the callback example containing customer redirection data. This callback is sent from the Ecommpay payment platform to the URL specified in the merchant project settings. The payment status in this callback is `awaiting redirect result` until the payment is completed by the customer.

```
    "type": "redirect",
                "code": "0",
                "operation_id": 64897000022161,
                "request_type": "purchase",
                "redirect_data": {
                    "body": {
                    },
                    "method": "POST",
                    "url": "https://payment.asiapaygateway.com/payment/DirectInterface",
                    "encrypted": {
                        "key": 3,
                        "message": "d4d9aa52891d0a59c40069bae69b57e872d0e946b70c67860e9c3e3b182cf240033a..."
                    }
```

## Callback format {#en_gate_payment_sale_callback_format}

A one-step purchase uses the standard format for callbacks to submit purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `4,000.00 USD` purchase the `customer_12` made by using the payment card № `431422******0056` in the `42` project.

```language-json
{
    "account": {
        "number": "431422******0056",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 400000,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2019-01-11T13:02:42+0000",
        "created_date": "2019-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2019-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback for a one-step purchase declined due to incorrect card data entered.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 400000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 13300000004505,
        "type": "sale",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "created_date": "2019-01-11T14:11:00+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "USD"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```



---

# Two-step purchase {#en_gate_payment_auth}

An article about processing via Gate one-time two-step purchases that comprise placing an authorization hold and subsequent debiting of funds.

**Note:** This article covers processing one-time two-step purchases via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time two-step purchases:

-   [One-time two-step purchase](en_platform_dms_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing one-time two-step purchases in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing one-time two-step purchases via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

**Parent topic:**[One-time purchases](en_Gate_purchase.md)

## Overview {#en_gate_payment_auth_overview}

In the payment platform, two-step purchases are processed according to the payment processing model \([One-time two-step purchase](en_platform_dms_model.md)\): *the first step* is initiated by request sent from merchant's web service to the payment platform, and *the second step* is initiated by request from merchant's web service or the payment platform may automatically perform the step after specific time elapses. Information on two-step purchases with direct use of payment cards is presented in this section, while the information on such purchases by using of alternative payment methods—in the [Methods](en_pm_about.md) section.

Merchant web service may request change of the amount authorised on the first step. The change may be performed on a one-time basis with the following initiation of the second step or the web services may change the authorised amount multiple times with the final initiation of the second step, on request or automatically.

To configure automatic initiation of the second step \(automatic withdrawal or release of the held funds\), contact Ecommpay technical support \([support@ecommpay.com](mailto:support@ecommpay.com)\). The time lag and the type of the operation to be performed once the time lag expires are specified by the merchant.

When performing an one-time two-step purchase, you can use one of the following options to transfer payment details:

-   *Transfer of complete payment details*. This is a basic option in which you collect all payment details from the customer, and then submit the data inside a payment request. MO/TO \(Mail Order/Telephone Order\) payment is a special case in which you transfer complete payment details. MO/TO is a card-not-present payment in which a customer may phone or email the merchant, place an order and pay by providing the payment card details over the phone or by email. For more information about MO/TO payments, see [MO/TO payment processing](en_Gate_moto.md).
-   *Transfer of payment details identifier*. To enable this option, you need to perform an initial COF payment. Once you do this, the payment platform creates a payment instrument record and returns a callback with the ID of the record in the `account_id` or `card_id` parameter.You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials, see [Saving payment data](en_gate_saved_data.md)
-   *Transfer of payment token*. To enable this option, you need to perform an initial payment. Once you do this, the payment platform creates a payment token and returns a callback with the token in the `token` parameter. You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials.For more information about using tokens, see [Using tokens](en_Gate_Token.md).

## Limits {#en_gate_payment_auth_time_limit}

### Time limit for authorisation hold {#section_hgy_djl_ylb .section}

According to the requirements of Visa, Mastercard, and American Express, the time lag for holding funds is limited. For different types of cards the maximum allowed time lag is defined as follows:

-   Visa cards:
    1.  If authorisation hold is performed as a part of COF purchase processing, the maximum allowed time lag is 5 days.
    2.  If authorisation hold is performed not as a part of COF purchase processing or COF purchase registration, and the merchant's Merchant Category Code \(MCC\) is one of the following: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513, the maximum allowed time lag is 30 days.
    3.  In other cases the maximum allowed time lag is 10 days.
-   Maestro and Cirrus cards: the maximum allowed time lag is 6 days.
-   OtherMastercard cards: the maximum allowed time lag is 28 days.
-   American Express cards:
    1.  If merchant MCC is associated with hotel industry, car rental, or cruise lines the allowed time lag may extend to the entire duration of stay at a hotel, car rent duration or cruise duration, accordingly.
    2.  In other cases the maximum allowed time lag is 7 days.

The maximum allowed time lag for holding funds is calculated starting from the moment the `auth` operation is created in the Ecommpay payment platform. 30 minutes before the time lag expires, depending on the parameters specified by the Ecommpay employees, one of the following operations is performed automatically: a withdrawal \(`capture`\) or a release \(`cancel`\) of the held funds, after that a callback is sent to the web service. The format of the callback is described in the [Callback format](en_gate_payment_auth.md) section. For more information and configuration of the operation type you can refer to your Ecommpay key account manager.There is an exception for American Express cards for which the maximum allowed time lag is limited by the entire duration of stay at a hotel, car rent duration or cruise duration—automatic withdrawal is not available for such cards.

If the time lag specified by the merchant for automatic withdrawal or release of funds exceeds the maximum allowed time lag, withdrawal or release of funds is performed based on the maximum allowed time lag.For instance, if the merchant configures automatic release of the held funds after 10 days and authorisation hold is performed by using Maestro card \(the maximum allowed time lag for Maestro card is 6 days\), automatic release of funds is performed after 6 days.

### Limits on authorised amount change {#section_zpr_z1m_mnb .section}

Changing the authorised amount is supported only for the purchases made with the use of the Mastercard and Visa cards with respect to the following restrictions:

-   After reducing the authorised amount, the remaining amount should be at least 0.01 USD or equivalent to this amount in another currency according to the rate for this currency. If the remaining amount is less than required, the request for reducing the amount is declined with the `3117` error code.
-   For the Visa cards purchases, initial amount changes of over 15 per cent are supported only for the following MCCs \(Merchant Category Codes\): 3351–3500, 3501–3999, 4111, 4112, 4121, 4131, 4411, 4457, 5411, 5552, 5812, 5813, 7011, 7033, 7394, 7512, 7513, 7519, 7523, 7996, 7999. For any other MCC, initial amount changes are limited to 15 per cent.

For the American Express cards purchases, this capability is not supported.

## Workflow {#en_gate_payment_auth_workflow}

When processing a two-step purchase by using Gate, the merchant web service is required to do the following:

1.  Send the request for an authorisation hold with payment details to the following endpoint: [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth).
2.  If necessary, complete the additional procedures:
    -   *3‑D Secure authentication*. This authentication is intended to provide security to online payments by payment cards. For more information on the authentication workflow, as well as request and callback formats, see [3‑D Secure authentication](en_gate_payment_3ds.md).
    -   **Customer authentication on merchant's request**. This authentication is intended to make purchases with payment cards more secure. For more information on the authentication workflow, as well as request and callback formats, see [Authentication on merchant's request](en_gate_payment_merch_auth.md).
    -   *Additional payment information submission*. This procedure is intended for cases, where the initial request did not contain the information necessary for any payment process stakeholders. For more information on this procedure, see [Submission of additional payment information](en_Gate_Clarification.md).
3.  Receive a callback with the authorisation hold result from the payment platform.
4.  If you need to change previously authorised amount without actually debiting customer account, send a request with the corresponding parameters to one of the following endpoints:

    -   `/v2/payment/card/incremental`—to increase the authorised amount
    -   `/v2/payment/card/cancel`—to decrease the authorised amount
    Then, you need to receive a callback with the result of your authorised amount change request.

5.  Send the request for debiting customer account to the [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) endpoint or the request for cancelling an authorisation hold to the [/v2/payment/card/cancel](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-cancel) endpoint.

    If you need debit amount different from the authorised amount, simply specify the debit amount and the currency in a request to the `/v2/payment/card/capture` endpoint.

6.  Receive a callback with the payment result from the payment platform.
7.  If needed, after completing a one-time one-step purchase you can return your customers their money, if the payment method supports refunds. For more information on this procedure, see [Purchase refunds](en_Gate_Refund.md).

The following diagram provides the detailed picture of an ordinary \(without additional requests\) two-step purchase processing procedure with cancelling an authorisation hold.

![](images/purchase_schemes/en_gate_auth_cancel.svg)

1.  Customer initiates a purchase on the merchant web service.
2.  The web service sends the request for an authorisation hold by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request for an authorisation hold by using Gate.
4.  The payment platform performs the request acceptance that includes validation of the required parameters and signature.
5.  The payment platform sends to the web service response with request receipt confirmation and correctness check result.
6.  The payment platform performs the internal request processing and sends it to the card organisation.
7.  The card organisation performs the internal request processing and sends it to the issuer.
8.  The issuer performs the internal request processing and an authorisation hold.
9.  The issuer sends the callback with the authorisation hold result to the card organisation.
10. The card organisation sends the callback with the authorisation hold result to the Ecommpay payment platform.
11. The payment platform sends the callback with the authorisation hold result to the web service.
12. The customer receives the authorisation hold result from the web service.
13. The web service sends the request for debiting customer account \(or cancelling an authorisation hold\) by using Gate to the specified Ecommpay URL.
14. The payment platform receives the request for debiting customer account \(or cancelling an authorisation hold\) by using Gate.
15. The payment platform performs the request acceptance that includes validation of the required parameters and signature.
16. The payment platform sends to the web service response with request receipt confirmation and correctness check result.
17. The payment platform performs the internal request processing and sends it to the card organisation.
18. The card organisation performs the internal request processing and sends it to the issuer.
19. The issuer performs the internal request processing and debiting customer account.
20. The issuer sends the callback with result of debiting customer account to the card organisation.
21. The card organisation sends the callback with result of debiting customer account to the Ecommpay payment platform.
22. The payment platform sends the callback with result of debiting customer account to the web service.
23. If an authorisation hold cancelled, the customer receives the payment result from the web service.

The sections that follow discuss in more details the request format and the required parameters and the information about the format of callbacks with payment results. For the general information on how to use the API, see [Interaction concepts](en_gate_interaction_organisation.md). Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_dms_model.md).

## Request format {#en_gate_payment_auth_request_format}

This section describes the request format applied in two-step purchases by *payment cards*.Note that processing of two-step purchases includes issuing requests for authorisation hold, as well increase, decrease, release, and debit of authorised amount.

### Request for authorisation hold {#section_ps3_mnb_v3b .section}

There are several things you need to consider when issuing requests:

1.  The request is sent by using POST \(HTTP\) method to one of the following endpoints:
    -   when indicating full card details—[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth),
    -   when indicating an identifier instead of card details—[/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved),
    -   when indicating a token instead of card details—[/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token).
2.  The following objects and parameters should be specified in the request:

    -   Object `general`—general request identification information:
        -   `project_id`—the project ID obtained from Ecommpay
        -   `payment_id`—payment ID unique within the project
        -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object `customer`—customer information:
        -   `ip_address`—IP address
        -   `id`—the ID of the customer within the merchant project
        -   `screen_res`—screen resolution of the customer's device, in pixels, with an `x` character as a delimiter \(for example, `360x640`\)
        -   `email`—customer's email
        -   `phone`—customer's phone number
    -   Object `payment`—payment information:
        -   `amount`—payment amount in minor units
        -   `currency`—payment currency in the ISO-4217 alpha-3 format
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation
    **Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` object containing information about the start and end dates of the booked service \([details](en_gate_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

3.  The request should contain the following customer's payment card information:
    -   when indicating complete card credentials—the following data in the `card` object:
        -   `pan`—card number
        -   `year`—year of expiration date
        -   `month`—month of expiration date
        -   `card_holder`—name of the cardholder, passed if this parameter is required for the specific project \(the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\)
        -   `cvv`—card verification code \(as indicated on the card\). This parameter is not necessary for processing of MO/TO payments. For more information, see [MO/TO payment processing](en_Gate_moto.md);
    -   when indicating the identifier—the identifier which is associated with the card credentials in the payment platform in the `saved_account_id` parameter, and the card verification code in the `cvv` parameter
    -   when indicating the token—token in the `token` parameter and the card verification code in the `cvv` parameter.
4.  The request should contain the `return_url` object with the addresses for redirecting the customer to the web service:
    -   `success`—the URL for redirecting the customer after the payment is completed;
    -   `decline`—the URL for redirecting the customer after the payment is declined.
5.  In case it is needed tot transfer funds to a merchant e-wallet, the object `customer` must contain the following additional parameters:
    -   `first_name`—first name
    -   `last_name`—last name
    -   `address`—address \(street, house number\)
    -   `email`—email
    -   `city`—city of residence \(town, village, etc.\)
    -   `state`—region of residence \(state, county, canton, etc.\)
6.  If required, you can also add any other additional parameters Gate supports.

Thus, to perform a two-step payment by a payment card, the request must include project and payment IDs, signature, IP-address of the customer, currency and amount of payment, as well as information about the payment card, as shown in the following example:

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12",
      "screen\_res": "360x640",
      "phone": "44991234567",
      "email": "john\_smith@email.com"
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },

//when indicating complete card credentials:
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//when indicating the identifier of a stored payment card:
    "saved_account_id": 2345678,
    "cvv": "123"

//when indicating the token of a stored payment card:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}
```

### Request for increasing the authorised amount {#section_y1l_b1s_mnb .section}

The request is sent by using POST \(HTTP\) method to the following endpoint [/v2/payment/card/incremental](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-incremental) and must contain the following objects and parameters:

-   Object `general`—general request identification information:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID unique within the project
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
-   Object `customer`—customer information:
    -   `id`—the ID of the customer within the merchant project
-   Object `payment`—payment information:
    -   `amount`—amount by which you request to increase the authorised amount, specified in minor units
    -   `currency`—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold
-   If required, you can also add any other additional parameters as specified on the specification.

Thus, the correct request for increasing the authorised amount must include project and payment IDs and signature, as well as the amount by which you need to increase the authorised amount and the currency code.

```language-json
{
    "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "id": "customer_12"
  },
    "payment": {
      "amount": 1000,
      "currency": "USD"
  }
```

### Request for debiting of authorised amount {#section_vgl_r1g_k3b .section}

The request is sent by using POST \(HTTP\) method to the following endpoint [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) and must contain the following objects and parameters:

-   Object `general`—general request identification information:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID unique within the project
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   If required, you can also add any other additional parameters Gate supports.

These parameters are required to debit the entire authorised amount. To debit only a part of the authorised amount, you must additionally specify the following parameters in the `payment` object:

-   `amount`—the final amount to debit in minor currency units
-   `currency`—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold

Thus, the correct request for debiting of authorised amount must include project and payment IDs and signature and, if required, the amount and currency code.

```language-json
{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}
```

### Request for partial debit or release of authorised amount {#section_flr_s1g_k3b .section}

The request is sent by using POST \(HTTP\) method to the following endpoint [/v2/payment/card/cancel](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-cancel) and must contain the following objects and parameters:

-   Object `general`—general request identification information:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID unique within the project
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   If required, you can also add any other additional parameters Gate supports.

These parameters are required to release the entire authorised amount. To decrease the authorised amount, you must additionally specify the following parameters in the `payment` object:

-   `amount`—the amount by which you need decrease the authorised amount, specified in minor currency units
-   `currency`—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold

Thus, the correct request for releasing of authorised amount must include project and payment IDs and signature; if you need just to decrease the authorised amount, the correct request must contain the amount and the currency code.

```language-json
{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}
```

## Callback format {#en_gate_payment_auth_callback_format}

A two-step purchase uses the standard format for callbacks to submit purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is an example of a callback with the information about the successful `2,000.00 USD` authorisation hold the `customer_12` made by using the payment card `541333******0019` in the `42` project.

```language-json
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2019-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 2777000002350,
        "type": "auth",
        "status": "success",
        "date": "2019-01-11T13:00:40+0000",
        "created_date": "2019-01-11T13:00:37+0000",
        "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "224750650",
            "date": "2019-01-11T13:00:39+0000",
            "result_code": "000",
            "result_message": "Approved",
            "auth_code": "505050",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success",
        "description": "SUCCESS",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback for a declined authorisation hold because of an incorrect card expiration date.

```language-json
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 6304000002973,
        "type": "auth",
        "status": "decline",
        "date": "2019-01-11T13:00:40+0000",
        "created_date": "2019-01-11T13:00:34+0000",
        "request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239689120",
            "date": "2019-01-11T13:00:36+0000",
            "result_code": "101",
            "result_message": "Decline, expired card",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "10106",
        "message": "Card expired",
        "description": "Bank cards. Operation was declined due to incorrect card expiry date entry",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback with the information about the successful increase of the authorisation hold by `10,00 USD` made on the payment card `541333******0019` in the `42` project of for the `customer_12` customer.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2019-01-11T15:54:40+0000",
        "method": "card",
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 7178000006589,
        "type": "incremental",
        "status": "success",
        "date": "2019-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 1000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2019-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback with the information about the successful `2,000.00 USD` debiting customer account the `customer_12` initiated the payment card `541333******0019` in the `42` project.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "success",
        "date": "2019-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 7178000006597,
        "type": "capture",
        "status": "success",
        "date": "2019-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2019-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback with the information about the successful cancelling of the `2,000.00 USD` authorisation hold for the payment card `541333******0019` in the `42` project.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "canceled",
        "date": "2019-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 18289000007021,
        "type": "cancel",
        "status": "success",
        "date": "2019-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:40+0000",
        "request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239672146",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

The following is the example of a callback for cancelling an authorisation hold declined due to incorrect card data entered.

```language-json
 {
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T15:54:40+0000",
        "id": "456789",
        "method": "card",
        "status": "decline",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 18397000002376,
        "type": "cancel",
        "status": "decline",
        "date": "2019-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:35+0000",
        "request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "248013808",
            "date": "2019-01-10T22:37:10+0000",
            "auth_code": "876856",
            "endpoint_id": 120
        },
        "code": "10102",
        "message": "Incorrect data entered"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```



---

# Payment link purchases {#en_gate_invoice}

An article about processing one-step and two-step purchases with the use of payment links and redirecting customers to Payment Page.

**Note:** This article covers processing payment link purchases via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of payment link purchases:

-   [Payment link purchase](en_platform_invoice_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing payment link purchases in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   Step-by-step [instructions](en_dbl_payments.md) on how to perform payment link purchases via Dashboard.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing purchases via Payment Page with the focus on the specific processing scenarios and interaction workflows.

**Parent topic:**[Gate](en_Gate_Integration_About.md)

## Overview {#en_gate_invoice_overview}

*Payment link purchase* is a payment type which uses an initial request to generate a web link that customers can click to make purchases that involve a one-timeor recurring transfer of funds from the customer to the merchant.As a rule, payment link purchases are used for one-time payments with or without the authorisation hold. At the same time, if needed, payment link purchases can be used for registering [COF purchases](en_Gate__payments_on_saved_data.md), while with certain payment methods payment links can be used for obtaining the customer's consent to registration of a COF purchase, without actual withdrawal of funds.

Purchases of this type utilise Payment Page. The payment link to open the payment form is delivered to the customer by the Ecommpay payment platform via email or by the merchant using any available delivery media. The merchant chooses the payment link validity period and the payment processing scenario and specifies them in the request for initiating the payment. The validity period of the link \(from the moment when the link is generated in the payment platform to the moment when the request to initiate the payment is received in the payment platform\) cannot exceed 30 days, and when the link expires, the payment platform sends a corresponding callback. The merchant can also specify the payment method for making the payment. Alternatively, the merchant can allow the customer to choose one of the payment methods available in the merchant project.

Because payment link purchases are processed via Payment Page, payment requests either do not contain payment instrument data, or provide it in the form of a card token. In the latter case, the customer is required only to prove the validity of the payment instrument; there is no need to specify payment instrument details in the payment form.

As in other payment types, payment link purchase may require additional procedures such as the 3‑D Secure authentication, submission of additional payment information, or currency conversion. These procedures are performed on the side of Payment Page and require no additional effort on the merchant's web service side.

## Processing scenarios {#en_gate_invoice_scenarios}

Suppose that your customer wants to make a `1379.50 USD` purchase by using payment link and asks you to send the payment link to email `eddington@mail.uk`.

### Payment processing {#section_u3k_51f_5kb .section}

![](images/ecommpay/en_gate_invoice_1.svg "Opening payment form and entering payment details")

![](images/ecommpay/en_gate_invoice_2.svg "Receiving the information about the payment result")

1.  The web service sends to the payment platform a request with parameters that require the Ecommpay platform to send the payment link to customer.
2.  The payment platform processes the request, issues the corresponding callback to merchant's web service, and sends the payment link to the email that was specified in the initial request. The preferable language of email is English.
3.  Customer clicks the payment link to open Payment Page.If the initial request does not contain instructions to select specific payment method, Payment Page displays payment method selection page. If the initial request specifies the payment method, Payment Page displays the page for the selected payment method.
4.  The customer enterspayment details and proceeds with payment; if necessary the customer performs additional operations required to complete one or more auxiliary procedures.
5.  After payment is complete the payment platform submits a callback with the payment results to the web service; the web page with the payment result information is displayed to the customer.

### Payment cancellation {#section_urr_zsf_5kb .section}

1.  Merchant's web service sends a request for payment cancellation to the payment platform.
2.  The payment platform processes the request, issues the corresponding callback to merchant's web service, and sends an email to the email address that was specified in the initial request.Standard email content is shown below. The preferable language of email is English.

    ![](images/ecommpay/en_gate_invoice_4.svg "Sample payment cancellation email")

3.  Customer clicks the payment link and is presented with the payment cancellation page.

### Payment link expiration {#section_if1_btf_5kb .section}

1.  The payment platform sends a callback with notification about expired payment link to the web service.
2.  If customer clicks the payment link, a page with the notification about expired payment link is displayed.

    ![](images/ecommpay/en_gate_invoice_3.svg "Page with notification about expired payment link")


Below you find the information about what the web service is required to do to complete payment.

## Customising email and payment form {#en_gate_invoice_custom}

### Email content and design {#section_vjk_3nx_1lb .section}

By default, the email sent to the customer includes the sender's email address\(noreply@ecommpay.com\), the subject line with the name of the merchant or the project used \(as specified in the platform\), for example, `Payment Link from Cosmoshop`, as well as the following information from the request to generate a payment link:

-   payment identifier \(from the `payment_id` parameter\)
-   payment amount and currency \(from the `amount` and `currency` parameters, respectively\)
-   payment link expiry date and time \(from the `best_before` parameter\)
-   payment description \(from the `description` parameter\)

![](images/ecommpay/en_gate_invoice_5.svg "Default email template")

If needed, the merchant can designate a specific email address that will be shown to the customer as a sender's address, change the language and the information included in the email, or provide their own customised version of the email design and layout.

To customise the template of payment link email, contact the Ecommpay technical support at [support@ecommpay.com](mailto:support@ecommpay.com).

### Payment form design {#section_kfw_3nx_1lb .section}

By default, the payment form displayed to the customer has the standard design provided by Ecommpay. If desired, it is possible to customise the design with the application of various changes to separate payment form elements by using the corresponding [design builder](en_PP__design_customisation.md). With questions that do not cover the design builder capabilities, contact your account manager.

## Workflow {#en_gate_invoice_workflow}

When processing a payment link purchase by using Gate, merchant's web service is required to do the following:

1.  Send a [payment link purchase request](en_gate_invoice.md#section_qxt_mz3_tkb) to the following endpoint `/v2/payment/invoice[/card/token]/create`.
2.  Receive [the callback with the payment link](en_gate_invoice.md#section_h1k_nz3_tkb).
3.  If the payment link was not requested to be sent via the Ecommpay payment platform and is instead intended to be sent via the web service, send the link to the customer \(by email or via other forms of communication\).
4.  Receive [the callback with payment result](en_gate_invoice.md#section_yd1_4tk_tkb) or [the callback with payment link expiry notification](en_gate_invoice.md#section_wv1_yjq_tkb).

In a two-step payment link purchase, you need to complete the second step which includes either capturing the authorised amount or cancelling authorisation. For more information about performing the second step in two-step purchase, see [Two-step purchase](en_gate_payment_auth.md).

The following diagram provides the detailed picture of payment link purchase processing.

![](images/en_gate_invoice_uml.svg)

1.  The web service sends the request for processing a payment link purchase to the specified Ecommpay URL.
2.  The payment platform receives the request.
3.  The payment platform accepts and validates the request.
4.  The payment platform sends to the web service response with request receipt confirmation and validation result.
5.  The payment platform processes the request.
6.  The payment platform sends a callback with the payment link to merchant's web service.
7.  The payment platform sends an email with the payment link to customer's address. The payment link may be delivered by using merchant's web service or any other available delivery means.
8.  Customer follows the payment link.
9.  The payment platform receives the request for payment page.
10. The payment platform processes the request.
11. The payment platform generates Payment Page that is compliant with the project settings.
12. Customer is presented with the generated payment form.
13. Customer enterspayment details and confirms the purchase.
14. The payment platform receives the purchase request.
15. The payment platform processes the request and forwards it to the payment system \(or to the provider service\).
16. The payment system \(or the provider service\) processes the payment.
17. The payment system \(or the provider service\) sends a notification with the payment result to the payment platform.
18. The payment platform sends a callback with the payment result to the web service.
19. The payment platform sends the payment result to Payment Page.
20. The payment result is displayed to customer on Payment Page.

To cancel the purchase, do the following *before* the customer confirms the purchase:

1.  Send [cancel payment request](en_gate_invoice.md#section_nnb_tgk_tkb) to endpoint `/v2/payment/invoice/cancel`.
2.  Receive [the callback about payment cancellation](en_gate_invoice.md#section_nkb_ntk_tkb).

The next sections describes request formats and the parameters for initiating and cancelling payment link purchases; the sections that follow also discuss payment callback formats. Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_invoice_model.md).

## Request format {#en_gate_invoice_format_request}

### Request to initiate a payment {#section_qxt_mz3_tkb .section}

When creating requests, you need to consider the following:

1.  The request is sent by using POST \(HTTP\) method toone of the following endpoints: [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)or [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create).
2.  The following objects and parameters must be specified in the request:

    -   `general`—object with general request identification information:
        -   `project_id`—the project identifier obtained from Ecommpay when onboarding
        -   `payment_id`—payment identifier that must be unique within the project
        -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
    -   `customer`—object with customer information:
        -   `id`—customer identifier in merchant's web service
    -   `payment`—object with payment information:
        -   `amount`—payment amount in minor currency units
        -   `currency`—payment currency in the ISO-4217 alpha-3 format
        -   `best_before`—expiry date and time of the payment link in the following format: `YYYY-MM-DDThh:mm:ss±hh:mm`. Keep in mind that the validity period of the payment link cannot exceed 30 days.
    **Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards merchants in certain business categories must specify the `booking_info` object containing information about the start and end dates of the booked service \([details](en_gate_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

3.  To initiate a payment by card token, specify it in the `token` parameter.
4.  To send the payment link via the Ecommpay payment platform, specify the following parameters:
    -   `send_email`—the indicator that communicates the need to send the link automatically \(must be set to `true`\).
    -   `email` \(in the `customer` object\)—the email of the customer to be used.
    -   `language` \(in the `customer` object\)—the code of the language to be used in the email. The parameter is required if the customer language is not English \(used by default\) and the email template in this language has been previously configured in the payment platform.
5.  To send the payment link via your web service \(and, thus, removing the option to send the email via the Ecommpay platform\), pass the `send_email` parameter set to `false`.
6.  To select the purchase type that differs from a default one, specify the appropriate value in the `operation_type` parameter.
7.  To preselect a specific payment method, pass the payment method code in the `force_method`. \(For complete list of payment methods codes, see [Payment method codes](en_pm_codes.md).\)
8.  To register a COF purchase, pass the `recurring` object that contains required parameters for the COF purchase being registered:
    -   `register`—COF purchase registration indicator; use `true` value to have the COF purchase registered.
    -   `type`—type of the COF purchase to register, possible values:
        -   `C`—one-click purchase
        -   `U`—autopurchase
        -   `R`—regular purchase
    -   `period`—debiting period for the regular purchase:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly
        -   `Q`—quarterly
        -   `Y`—yearly
    -   `time`—time of subsequent debiting for the regular purchase in `hh:mm:ss` format
9.  To initiate a debiting operation executed as part of the Mastercard MoneySend and Visa Direct services, specify the information about the payment recipient in the `recipient` object \(to learn more about the request format, refer [to the article about working with these services](en_gate_money_transfer_services.md).
10. If necessary, you can also add other additional parameters as specified in the API specification.

Thus, a correct payment request for purchase by a payment link must include project and payment identifiers, signature, customer identifier, payment currency and amount, payment link expiry date and time, and, if required, payment card token. If you want Ecommpay to send the payment link to your customer, you also need to specify a customer email and set the automatic payment link delivery indicator to `true`.

```language-json
{
  "general": {
      "project_id": 1901,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm=="
  },
    "customer": {
      "id": "stapleton",
      "email": "baskerville@mail.uk"
  },
    "payment": {
      "amount": 1500,
      "currency": "GBP",
      "best_before": "2026-03-08T09:00:00+03:00"
  },
    "send_email": true,
// If card token was previously submitted:
    "token": "f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654"  
}
```

```language-json
{
  "general": {
    "project_id": 1901,
    "payment_id": "1234",
    "signature": "rS3vlABOs/fve6o555OINkQJqlDDZR2rQ=="
  },
  "customer": {
    "id": "stapleton",
    "email": "baskerville@mail.uk"
  },
  "payment": {
    "amount": 1299,
    "currency": "EUR",
    "description": "fluorescent paint 400ml",
    "best_before": "2026-10-20T23:59:59Z"
  },
  "send_email": false,
  "operation_type": "sale"
}
```

### Request to cancel the payment {#section_nnb_tgk_tkb .section}

When creating requests, you need to consider the following:

1.  The request is sent by using POST \(HTTP\) method to the following endpoint: [/v2/payment/invoice/cancel](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-cancel).
2.  The request must contain the `general` object with the key parameters:
    -   `project_id`—the project identifier obtained from Ecommpay when onboarding
    -   `payment_id`—identifier of payment to cancel
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
3.  If required, you can also add other additional parameters as specified in the API specification.

Thus, a correct payment request for payment cancellation must include project and payment identifiers and signature.

```language-json
{
  "general": {
      "project_id": 1901,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm=="
  }
}
```

## Callback format {#en_gate_invoice_format_callback}

### Callback with information about payment link generation and delivery {#section_h1k_nz3_tkb .section}

Callbacks with payment link delivery information use the standard format for callbacks described in greater detail in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about successful generation and delivery of a payment link for a `12.99 GBP` purchase to email `baskerville@mail.uk` of the customer `stapleton`. The expiration date and time of the payment link is October 11, 2026, 11:50.

```language-json
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"invoice sent",
    "date":"2025-11-11T11:50:24+0000",
    "best_before":"2026-10-11T11:50:00+0000",
    "force\_payment\_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&operation\_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":\{ 
    "number":"431422\*\*\*\*\*\*0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card\_holder":"STAPLETON JACK",
    "id":1353,
    "expiry\_month":"11",
    "expiry\_year":"2028"
  \},
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"invoice sent",
    "date":"2025-11-11T11:57:34+0000",
    "created_date":"2025-11-11T11:56:32+0000",
    "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3701",
    "message":"Merchant sent invoice",
    "eci":"02"
  },
  "signature":"hghwGGyapGUQnI+Qg...=="
}
```

The following is the example of a callback with information about successful generation of a payment link that will be sent to the customer `stapleton` via the merchant web service.

```language-json
{
    "customer": {
        "id": "stapleton"
    },
    "project_id": 1901,
    "payment": {
        "id": "1234",
        "type": "invoice",
        "status": "awaiting payment",
        "date": "2025-10-13T13:14:46+0000",
        "sum": {
            "amount": 1299,
            "currency": "EUR"
        },
        "description": "fluorescent paint 400ml"
    },
    "paymentLink": "https://cosmoshop-pp.com/3fdsfdfoeV6",
    "operation": {
        "sum_initial": {
            "amount": 1299,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 1299,
            "currency": "EUR"
        },
        "code": "9999",
        "message": "Awaiting processing",
        "provider": {
            "id": 0,
            "payment_id": ""
        },
        "id": 5034534534341907,
        "type": "invoice",
        "status": "awaiting payment",
        "date": "2025-10-13T13:14:47+0000",
        "created_date": "2025-10-13T13:14:46+0000",
        "request_id": "3b1ef25371d43bcf061bdfgdf2276a2fb0eb4647-05026527"
    },
    "signature": "oFsfX5SZkzSNubrB3dsfsdf555P3iMTdfsds55VnMgmhLlsmx6cJLQg=="
}
```

### Callback with payment cancellation information {#section_nkb_ntk_tkb .section}

Callbacks with payment cancellation information use the standard format for callbacks described in greater detail in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about cancellation of the `456789` payment; the payment status is `invoice canceled`.

```language-json
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"invoice canceled",
    "date":"2025-11-11T11:57:36+0000",
    "best_before":"2026-10-11T11:50:00+0000",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&operation\_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":\{ 
    "number":"431422\*\*\*\*\*\*0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card\_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry\_month":"11",
    "expiry\_year":"2028"
  \},
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"invoice canceled",
    "date":"2025-11-11T11:57:34+0000",
    "created_date":"2025-11-11T11:56:32+0000",
    "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3702",
    "message":"Merchant canceled invoice",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}
```

### Callback with payment link expiry information {#section_wv1_yjq_tkb .section}

Callbacks with payment link expiry information use standard format for callbacks described in greater details in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information that the payment link which was previously delivered to email `baskerville@mail.uk` of the customer `stapleton` expired on February 11, 2025 at 11:50.

```language-json
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"expired",
    "date":"2025-01-11T11:57:36+0000",
    "best_before":"2025-02-11T11:50:00+0000",
    "force\_payment\_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2025-02-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&operation\_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":\{ 
    "number":"431422\*\*\*\*\*\*0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card\_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry\_month":"11",
    "expiry\_year":"2028
  \},
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"expired",
    "date":"2025-01-11T11:57:34+0000",
    "created_date":"2025-01-11T11:56:32+0000",
    "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3700",
    "message":"Best_before has expired",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}
```

### Callback with payment result {#section_yd1_4tk_tkb .section}

Callbacks with payment result information use the standard format for callbacks described in greater details in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `12.99 GBP` payment completion for the customer `stapleton`.

```language-json
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"success",
    "date":"2025-11-11T11:57:36+0000",
    "best_before":"2026-10-11T11:50:00+0000",
    "force\_payment\_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&operation\_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":\{ 
    "number":"431422\*\*\*\*\*\*0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card\_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry\_month":"11",
    "expiry\_year":"2028"
  \},
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"success",
    "date":"2025-11-11T11:57:34+0000",
    "created_date":""2025-11-11T11:56:32+0000",
    "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"0",
    "message":"Success",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}
```



---

# Credential-on-file \(COF\) purchases {#en_Gate__payments_on_saved_data .concept}

Articles about registering and processing via Gate different types of purchases followed by a series of recurring debits and about the capabilities of managing debits within recurring payments.

**Note:** This subsection covers processing COF purchases via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing COF purchases:

-   articles [On-demand COF purchase](en_platform_recurring_model.md) and [COF purchase with automatic debiting](en_platform_sheduled_recurring_model.md) in the section [Payment processing](en_platform_payment_model.md) that provide a general description of processing COF purchases in the Ecommpay payment platform and cover information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of processing COF purchases via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

In this article:

-   [Overview](en_Gate__saved_cards_payments_type.md)
-   [Registering COF purchase](en_gate_payment_recurring_registration.md)
-   [On-demand COF purchase](en_Gate__cof_merchant_side.md)
-   [COF purchase with automatic debiting](en_Gate__cof_gate_side.md)
-   [Managing debiting series of a COF purchase](en_gate_payment_recurring_manage.md)
-   [Working with debiting retry attempts](en_gate_cof_retry_attempts.md)

-   **[Overview](en_Gate__saved_cards_payments_type.md)**  
An article with the general information about recurring purchases, their classification, and processing workflows.
-   **[Registering COF purchase](en_gate_payment_recurring_registration.md)**  
An article about registering via Gate purchases followed by series of recurring debits.
-   **[On-demand COF purchase](en_Gate__cof_merchant_side.md)**  
An article about processing via Gate recurring purchases with debiting of funds initiated by the merchant \(unscheduled\).
-   **[COF purchase with automatic debiting](en_Gate__cof_gate_side.md)**  
An article about processing via Gate recurring purchases with automatic debiting of funds \(according to a set schedule\).
-   **[Managing debiting series of a COF purchase](en_gate_payment_recurring_manage.md)**  
An article about the capabilities of managing debiting series of recurring purchases via Gate, including retrieval of information about the debiting series, updating its parameters, and canceling the recurring purchase.
-   **[Working with debiting retry attempts](en_gate_cof_retry_attempts.md)**  
An article about working with the automatic debiting retries as part of processing a recurring purchase.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Overview {#en_Gate__saved_cards_payments_type .concept}

An article with the general information about recurring purchases, their classification, and processing workflows.

## Definition {#section_ldx_hjk_w2b .section}

*COF purchase* is a payment type in which customer authorizes merchant to store customer's payment credentials for subsequent use for one or more later transfers of funds from customer to merchant. In COF purchases, no payment instrument verification \(for instance,card CVV entry\) is required.

In COF purchases, fund transfers from customer to merchant are called *debiting*.

## Overview {#section_bzg_ghw_slb .section}

COF purchase support may be useful for building long-term customer loyalty when you need to offer your customers easy and hassle-free checkout.

The payment platform supports the following COF payment types:

-   *One-click purchase* is initiated by customer occasionally without any schedule or amount limitation or terms. For instance, customer can make a one-click purchase of a movie to view it online.
-   *Autopurchase* is initiated by merchant without any schedule or amount limitation or terms. For example, when customer's mobile phone account balance falls below specific threshold, merchant may automatically top up the account.
-   *Regular purchase* is initiated by merchant based on specific schedule and fixed amount. The debiting terms may be stored either on the payment platform or in your web service. For example, weekly online subscription may be regularly debited to customer's account.

![](images/en_cof.svg)

To process any COF purchase, regardless of its type, you need to collect the customer's consent to subsequent storing and use of their payment details according to specific terms and conditions \(that conform to the requirements of global card networks \). As a rule, collecting such consent is carried out when the COF purchase is registered.

## Processing options {#section_fhj_2h1_v3b .section}

Any COF purchase needs to be *registered*. You can do it in a variety of ways: for example, by performing a one-step purchase or payment instrument verification with the use of the corresponding request with appropriate parameters \([details](en_gate_payment_recurring_registration.md)\). In addition, COF purchases can be registered elsewhere and subsequently migrated to the Ecommpay payment platform from an external acquirer \([details](en_gate_data_migration.md)\) or even performed without migrating their data to the platform.

Information about COF purchases already registered can be *stored* in the Ecommpay platform or elsewhere \(in the merchant's web service or on the side of the external acquirer\). Note that within one project only one way to store data can be configured. Thus, if for a specific project, you have already set up processing COF purchases with the payment details stored outside of the Ecommpay platform, then processing COF purchases with the payment details stored in the platform will not be allowed, and vice versa.

COF purchases can be *processed* as follows.

There are two processing options available for regular COF purchases with registration data stored in the Ecommpay platform:

-   [with automatic debiting](en_Gate__cof_gate_side.md) when each debit operation is initiated in the platform according to a previously configured schedule.
-   [with on-demand debiting](en_Gate__cof_merchant_side.md) when each debit operation is initiated by the merchant.

Other types of COF purchases \(i.e. they are not regular COF purchases or information about them is not stored in the platform\) can only be processed using the on-demand debiting option.

In addition, regardless of the selected processing option, COF purchases can be performed according to the standard workflow or with the auxiliary procedure of [submitting additional payment information](en_Gate_Clarification.md).

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)



---

# Registering COF purchase {#en_gate_payment_recurring_registration}

An article about registering via Gate purchases followed by series of recurring debits.

## Overview {#section_qx5_hhm_dlb .section}

To register a COF purchase with the payment platform, you need to save customer payment instrument credentials. You can do it in a variety of ways by processing payments via Gate, Payment Page \([details](en_pp_recurring.md)\), and Dashboard \([details](en_dbl_payments.md)\)as well as by migrating information about COF purchases from an external acquirer \([details](en_gate_data_migration.md)\).

You can register a COF purchase via Gate by sending a request for one-time purchase, payment link purchase, or for payment instrument verification with parameters indicating that the payment instrument credentials need to be saved.

Each COF purchase is registered for a defined period. If the merchant does not specify parameters defining this period, the platform applies default values corresponding either to the expiry date of the relevant payment card or to a period of 10 years from the month in which the COF purchase was registered \([details](en_gate_payment_recurring_registration.md#ul_jld_fw3_y3b)\). Once the period the COF purchase was registered for expires, the payment platform sends a callback with this information to merchant's web service. Any further debiting within this purchase is no longer possible; if web service attempts to initiate the debit operation, the payment platform will respond with a callback with the `3184` \(or `3301`\) error code.

**Note:** According to Visa and Mastercard recommendations issued in 2020, they temporary allow COF purchases with expired bank cards, provided the payment provider or the payment system support this option. In this case, purchases are possible both before and after card expiration date, if the COF registration date is set to the card expiration date. To prevent using expired bank cards for COF purchases, when registering COF purchase, set its expiry date to the date which is different from the card expiry date \(see [Updating debit series](en_gate_payment_recurring_manage.md#section_lpp_df2_5jb) for more information\).

COF purchase registration may be blocked for specific merchant projects or providers in which case the requests with registration demand may be declined. To prevent declining of such requests, you can contact support service at [support@ecommpay.com](mailto:support@ecommpay.com) and ask them to configure your project to ignore registration demands when processing COF purchases, if COF purchase registration is blocked.

If there are changes in the payment provider's service settings, you may need to register COF purchase again. In such cases, the merchant receives an email from the Ecommpay technical support with a list of IDs of COF purchases that should be re-registered. For this registration, merchant must notify customers of the termination of previous debits and the need to initiate new ones by unlinking the saved card, and then initiate registration in the platform. Each newly registered COF purchase receives a new ID, which is sent to the merchant in the callback with information on successful registration.

## Registration procedure {#section_p3r_frb_cjb .section}

To register a COF purchase, you need to send a request to initiate one of the following operations: `sale`, `auth`, `account verification`, or `invoice` and to populate the request with all the parameters required to process the operation *and* the parameters required to register the COF purchase.

The payment platform initiates and performs the requested operation including any auxiliary procedures which may be required. If credentials are stored on the payment platform, after the operation is successfully completed and is assigned the `success` status, a record about debiting series is created on the payment platform. The record is assigned the following attributes:

-   *ID* Once the record about debiting series is created, web service receives its ID in the callback inside the `id` parameter of the `recurring` object. You use this ID to perform and to manage COF purchases.
-   *Status* Any active debiting series record is assigned the `active` status. The status may change to `canceled` on merchant or customer demand and in some other cases.

If credentials are stored in the web service, a record about debiting series is not created.

The payment platform sends your web service a callback with operation result that contains ID of the debiting series record, if this record has been created. Such callback confirms that COF purchase is successfully registered.

## Registration when credentials are stored by web service {#section_smg_vqb_cjb .section}

There are several things you must consider when performing a COF purchase with customer instrument credentials stored by web service:

1.  You need to use a POST request to one of the following endpoints:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)—when processing a one-time one-step purchase
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)—when processing a one-time two-step purchase
    -   [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)—when verifying the payment instrument
    -   [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token) when verifying the payment instrument with the use of a token
2.  Your request must contain all the required parameters and objects.
3.  Also, your request must include the `stored_card_type` parameter and specify COF purchase type by using one of the following values:
    -   `3`—autopurchase
    -   `5`—regular purchase \(except for requests to the endpoint [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)\).

Thus, along all the required parameters, complete request must contain registration flags for selected COF purchase.

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNeR+CqGrNxYyilUwSm...=="
  },
  "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123",
      "stored_card_type": 3    // Registering autopurchase
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  },
  "payment": {
      "amount": 400,
      "currency": "USD"
  }
}
```

The payment platform includes the COF purchase registration information in its operation result callback to your web service. The payment platform uses the standard format for callbacks. For more information, see [Handling callbacks](en_platform_callbacks.md).

```language-json
{  
  "project_id":42,
  "payment":{
    "id":"567890",
    "type":"purchase",
    "status":"success",
    "date":"2019-05-14T12:52:45+0000",
    "method":"card",
    "sum":{
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{
    "number":"431422******0056",
    "token":"d927d3f006008edf5c07661",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{
    "id":"customer_12"
  },
  "scheme\_id":"MCS38A0790706",
  "operation":{
    "id":22136002040,
    "type":"sale",
    "status":"success",
    "date":"2019-05-14T12:52:45+0000",
    "created_date":"2019-05-14T12:52:42+0000",
    "request_id":"8c53d11-1160d2c",
    "sum_initial":{
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{
      "amount":400,
      "currency":"USD"
    },
    "provider":{
      "id":414,
      "payment_id":"00200011764",
      "date":"2019-05-14T12:52:55+0000",
      "auth_code":"231567", 
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success",
    "eci":"07"
  },
  "signature":"v7KN5D/aZAdeR+CqGrNxYyilUwSm...=="
}
```

## Registration when credentials are stored by the payment platform {#section_vdl_vqb_cjb .section}

There are several things you must consider when registering a COF purchase with customer instrument credentials stored by the payment platform:

1.  You need to use a POST request to one of the following endpoints:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)—when processing a one-time one-step purchase
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)—when processing a one-time two-step purchase
    -   [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)—when verifying the payment instrument
    -   [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)—when initiating a payment link purchase
    -   [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create)—when initiating a payment link purchase with the use of a token
2.  Your request must contain all the required parameters and objects.
3.  Also, your request must include a `recurring` object with the parameters of the COF purchase to register:
    -   `register`—indicator that specifies whether a COF purchase should be registered.
    -   `type`—type of the COF purchase to register, possible values:
        -   `C`—one-click purchase
        -   `U`—autopurchase
        -   `R`—regular purchase
    -   `time`—time of performing subsequent debits \(for a regular COF purchase\) in the `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.
    -   `period`—frequency of debits \(for a regular COF purchase\), possible values:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
        -   `Q`—quarterly
        -   `Y`—yearly
4.  You can also use other parameters of the `recurring` object:
    -   `amount`—fixed amount of subsequent debits \(for a regular COF purchase\) in the smallest currency unit.
    -   `interval`—multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter and should be assigned a numeric value from `1` to `100`. For example, if you need to charge the customer every third week, you can set `period` to `W` and `interval` to `3`.
    -   `start_date`—date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.
    -   `expiry_day`—calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_month`—month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_year`—year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).

        **Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

        -   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
        -   For other available methods—the corresponding parameter value is determined as follows:
            -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
            -   Month—the month in which the COF purchase was registered.
            -   Year—the year that is 10 years after the year in which the COF purchase was registered.
        Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

    -   `scheduled_payment_id`—identifier assigned to the payment within which scheduled debits are performed. It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project. Also, not to be confused with the debiting series record identifier specified in the `id` parameter of the `recurring` object that is passed in the callback with the COF purchase registration information.

        **Warning:** If the identifier that should be assigned to the COF purchase \(`scheduled_payment_id`\) matches the identifier of the payment made to register a COF purchase \(`payment_id`\), the request to register a COF purchase is declined.


Thus, along all the required parameters, complete request must contain registration flags for selected COF purchase and its type; for regular purchases, request must also contain debiting schedule.

Depending on the specific characteristics of providers involved in payment processing, the set of required parameters can vary. For the detailed information about the providers' requirements, contact the Ecommpay key account manager.

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "567890",
      "signature": "v7KN1ZZ5D/aZAeR+CqGrwSm...=="
  },
  "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123"
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  }
  "payment": {
      "amount": 400000,
      "currency": "USD"
  },
  "recurring": {
      "type": "R",
// Regular purchase
      "period": "W",
      "interval": 3,
// Debiting every third week
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
// Last debiting scheduled for May 5, 2025
      "time": "10:00:00",
// Debit at 10:00:00
      "register": true,
// COF purchase registration
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

Information about registering a COF purchase is communicated in callbacks with operation results sent from the payment platform to the web service. The format of these callbacks conforms to the standard one described in [this article](en_platform_callbacks.md).In addition, callbacks can be configured to include the `scheme_id` parameter that will contain the identifier of the operation that registered a COF purchase on the side of the global card network. To have it set up, you need to contact the Ecommpay technical support.

The following callback contains information about successful registration of a COF purchase with a debiting series record identifier `1001648059`.

```language-json
{  
  "project_id":42,
  "payment":{  
    "id":"567890",
    "type":"purchase",
    "status":"success",
    "date":"2019-05-14T12:52:45+0000",
    "method":"card",
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "token":"d927d3f006008edf5c07661",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{  
    "id":"customer_12"
  },
  "recurring":{  
    "id":1001648059,    // ID of debiting series record
    "currency":"USD",
    "valid_thru":"2019-05-20T00:00:00+0000"
  },
  "scheme\_id":"MCS38A0790706",
  "operation":{  
    "id":22136002040,
    "type":"sale",
    "status":"success",
    "date":"2019-05-14T12:52:45+0000",
    "created_date":"2019-05-14T12:52:42+0000",
    "request_id":"8c77279053d011-1160421d51e11f87d2c",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":414,
      "payment_id":"00200011764",
      "date":"2019-05-14T12:52:55+0000",
      "auth_code":"231567",
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success",
    "eci":"07"
  },
  "signature":"v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm...=="
}
```

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)



---

# On-demand COF purchase {#en_Gate__cof_merchant_side .concept}

An article about processing via Gate recurring purchases with debiting of funds initiated by the merchant \(unscheduled\).

## Overview {#section_knp_r41_v3b .section}

*On-demand COF purchase* is a payment type which uses a single initial request to make one \(recurring\) transfer of funds from customer to merchant by using previously stored payment credentials without validation of the payment instrument \(such ascard validation code\).

On-demand COF purchases can be processed if one of the following conditions is met:

-   These purchases were initially registered in the payment platform \([details](en_gate_payment_recurring_registration.md)\).
-   Information about these purchases was migrated from an external acquirer \([details](en_gate_data_migration.md)\).
-   Information about these purchases was not migrated to the platform, but you have coordinated their processing with your Ecommpay account manager, and it has been set up for the project.

In the Ecommpay payment platform, on-demand COF purchases are processed according to the payment model \([details](en_platform_recurring_model.md)\) and the workflow described in this article. Note that conditions pertinent to registration as well as steps of the registration flow do not apply to COF purchases registered anywhere else but the Ecommpay platform. In addition, the following applies to COF purchases that were registered elsewhere and the information of which was not migrated to the platform:

-   If the capability to perform such purchases is set up for the project, then other kinds of COF purchases \(registered in the platform or migrated to it\) cannot be processed within this project.
-   If payments are made with cards issued in the EEA, the merchant is responsible for registering COF purchases in compliance with the Strong Customer Authentication \(SCA\) requirement of the revised Directive on payment services \(PSD2\).

## The payment workflow {#section_mft_gvd_w3b .section}

To create a COF purchase:

1.  Register a COF purchase. For more information, see [Registering COF purchase](en_gate_payment_recurring_registration.md).
2.  Submit a request for [a COF purchase](en_Gate__cof_merchant_side.md#section_jbj_flf_dlb) with identifier of debiting series record.
3.  Accept [a callback with debiting result](en_Gate__cof_merchant_side.md#section_wxc_s41_v3b) from the payment platform.

For each subsequent debiting, you need to resubmit request for COF purchase and accept the callback with the debiting result.

![](images/en_gate_uml_oneclick.svg)

1.  Customer initiates debiting in the web service.
2.  The web service sends a request for debiting to the Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform processes the request.
5.  The payment platform sends to the web service the information about receiving the request and the correctness of the request.
6.  The payment platform sends request to perform payment to the payment system.
7.  The payment system processes the request and sends it to the issuer.
8.  The issuer processes the request and debits customer account or card.
9.  The issuer sends notification with payment results to the payment system.
10. The payment system sends the notification with payment results to the payment platform.
11. The payment platform sends callback with debiting results to the web service.
12. The web service sends debiting result to customer.
13. From this point forward, customer can initiate subsequent debiting that follow steps 1—12.

![](images/en_gate_uml_autopayment.svg)

1.  The web service sends a request for debiting to the Ecommpay URL.
2.  The request enters the payment platform.
3.  The payment platform processes the request.
4.  The payment platform sends to the web service the request acknowledgement and request correctness information.
5.  The payment platform sends the request to perform purchase to the payment system.
6.  The payment system processes the request and forwards it to the issuer.
7.  The issuer processes the request and debits customer account or card.
8.  The issuer sends notification with payment results to the payment system.
9.  The payment system sends the notification with payment results to the payment platform.
10. The payment platform sends callback with debiting results to the web service.
11. The web service sends debiting result to customer.
12. From this point forward, customer can initiate subsequent debiting each following steps 1 through 12.

The sections that follow discuss formats for requests and callbacks; for general information about using the API, see [Interaction concepts](en_gate_interaction_organisation.md). Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_payment_model.md).

## Request format {#section_jbj_flf_dlb .section}

This section describes format of the requests for COF purchases with on-demand debiting using *payment cards*.There are several things you must consider when submitting such requests:

1.  The request must be sent with the use of the POST method to one of the following endpoints:
    -   [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring)—for all types of COF purchases that were initially registered in the Ecommpay platform or that were migrated to the platform, regardless of where the payment details are stored \(in the payment platform or the merchant's web service\).
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)—for COF purchases with the payment details stored in the merchant's web service, regardless of where the COF purchase was initially registered.
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)—only for autopurchases and regular COF purchases with the payment details stored in the merchant's web service, regardless of where the COF purchase was initially registered.
    -   [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)—only for autopurchases that were initially registered in the Ecommpay platform or that were migrated to the platform, with the payment details stored in the merchant's web service.
2.  Your request must contain the following parameters and objects:
    -   `general`—object with general request identification information:
        -   `project_id`—project ID obtained from Ecommpay
        -   `payment_id`—payment ID, must be unique within the project
        -   `signature`—signature created after you specify all the required parameters \(For more information about signing requests, see [Signature generation and verification](en_platform_signature.md).\)
    -   `customer`—object with customer information:
        -   `ip_address`—customer IP address relevant for the initiated payment
        -   `id`—customer identifier unique within the project, the same identifier as the one used to register this COF purchase

            **Warning:** Using different customer identifiers for operations performed as part of the COF purchase is not allowed.

    -   `payment`—object with payment information:
        -   `amount`—payment amount in minor currency units
        -   `currency`—payment currency according to ISO-4217 alpha-3
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation
3.  Depending on the endpoint, you must add the following objects and parameters in the request:
    -   The request to the [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring) endpoint must contain the `id` parameter in the `recurring` object, and the value of this parameter must be the identifier of the debit series record received in the callback with registration information.
    -   The requests to the [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) endpoint must contain the `card` object with the following parameters:
        -   `pan`—card number
        -   `year`—card expiration year
        -   `month`—card expiration month
        -   `card_holder`—name of the cardholder, passed if this parameter is required for the specific project \(the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\)
        -   `stored_card_type`—purchase type \(`4` for autopurchase or `6` for regular purchase\)
        -   `scheme_id`—identifier of the initial operation of the COF purchase registration. This identifier is assigned by the global card network \(Mastercard or Visa\), is required when a COF purchase is registered in the European Economic Area, and can be specified in other cases.
    -   The requests to the [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token) endpoint must contain the `stored_card_type` parameter of the `card` object, and this parameter must have the value `4` \(autopurchase\).
4.  Additionally, you can use any other parameters as indicated in the specification.

Thus, a complete request must contain project ID, payment ID, signature, customer IP, payment amount and currency and either of the following:ID of debit series recordor payment card credentials and COF purchase type.

Depending on the specific characteristics of providers involved in payment processing, the set of required parameters can vary. For the detailed information about the providers' requirements, contact the Ecommpay key account manager.

```language-json
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMp5D/aZAeb0VMdeR+CqGSm...=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{  
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079    // ID of debit series record
  }
}
```

```language-json
{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "card": {
    "pan": "4314220000000056",
    "year": 2025,
    "month": 8,
    "card_holder": "JOHN SMITH",
    "stored_card_type": 4    // Automatic debiting
  }
}
```

```language-json
{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "token":"pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7",
  "card":{
    "stored_card_type": 4    // Automatic debiting
  }
}
```

## Callback format {#section_wxc_s41_v3b .section}

Results of processing COF purchases are communicated in callbacks with information about each performed debiting sent from the payment platform to the web service. The format of these callbacks conforms to the standard one described in [this article](en_platform_callbacks.md).In addition, callbacks can be configured to include the `scheme_id` parameter that will contain the identifier of the operation that registered a COF purchase on the side of the global card network. To have it set up, you need to contact the Ecommpay technical support.

The following callback contains information about debiting `4,00 USD` to card `431422******0056` of the customer with ID `customer_12` within the `42` project.

```language-json
{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "method":"card",
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "recurring":{  
    "id":1079,
    "currency":"USD",
    "valid_thru":"2022-10-31T00:00:00+0000"
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "created_date":"2019-09-04T12:57:53+0000",
    "request_id":"0b9f9e57a50-61da119c",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":414,
      "payment_id":"0020000000072964",
      "date":"2019-09-04T12:58:03+0000",
      "auth_code":"634R",
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success"
  },
  "scheme_id": "MCS38A0790706",
  "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...=="
}
```

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)



---

# COF purchase with automatic debiting {#en_Gate__cof_gate_side .concept}

An article about processing via Gate recurring purchases with automatic debiting of funds \(according to a set schedule\).

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)

## Overview {#en_gate_cof_gate_side_overview}

*COF purchase with automatic debiting* is a payment type which uses a single initial request to make a series of regularly recurring funds transfers \(debits\) from the customer to the merchant by using stored payment credentials without verification of the payment instrument\(i.e. by entering a card verification code\). The Ecommpay payment platform performs COF purchases with automatic debiting according to the payment model \([learn more](en_platform_sheduled_recurring_model.md)\). If one attempt to perform a scheduled debiting is not enough \(for example, if the customer's card account has insufficient balance\), the debiting can be retried in the payment platform automatically \([details](en_gate_cof_retry_attempts.md)\).

## Workflow {#en_gate_cof_gate_side_workflow}

### COF purchase with initiation of the first debit operation during registration {#section_oqf_hvd_w3b .section}

If the `scheduled_payment_id` parameter has been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

1.  Register a COF purchase. For more information, see [Registering COF purchase](en_gate_payment_recurring_registration.md).
2.  Accept [a callback with the debiting result](en_Gate__cof_gate_side.md) from the payment platform.
3.  Accept subsequent callbacks for each debit operation for this payment.

To update or cancel a COF purchase or to refund one or more debit operations, you need to submit the corresponding requests to the payment platform. \(For more information, see [Managing debiting series of a COF purchase](en_gate_payment_recurring_manage.md).\)

![](images/en_gate_uml_scheduled_recurring_auto.svg)

1.  According to the schedule, at the set time the payment platform sends the request for performing a recurrent debit operation to the payment system.
2.  The payment system processes the request and forwards it to the issuer.
3.  The issuer processes the debit operation and transfers the funds from the customer to the merchant.
4.  The issuer sends a notification with the debiting result information to the payment system.
5.  The payment system sends the notification with the debiting result information to the payment platform.
6.  The payment platform sends a callback with the debiting result to the web service.
7.  The customer receives the debiting result information from the web service.
8.  From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 1 through 7.

The sections that follow discuss formats for requests and callbacks; for general information about using the API, see [Interaction concepts](en_gate_interaction_organisation.md). Information about possible statuses of this payment type can be found [in the corresponding article](en_platform_payment_model.md).

### COF purchase with a separate initiation of the first debit operation {#section_dsl_jvk_wzb .section}

If the `scheduled_payment_id` parameter has not been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

1.  Register a COF purchase. For more information, see [Registering COF purchase](en_gate_payment_recurring_registration.md).
2.  Submit a request for [performing a COF payment](en_Gate__cof_gate_side.md#section_zcy_r41_v3b) with an identifier of the debit series record.
3.  Accept [a callback with the debiting result](en_Gate__cof_gate_side.md) from the payment platform.
4.  Accept subsequent callbacks for each debit operation for this payment.

![](images/en_gate_uml_scheduled_recurring.svg)

1.  The web service sends a request for debiting to the Ecommpay URL.
2.  The request enters the payment platform.
3.  The payment platform accepts and processes the request.
4.  The payment platform sends the request acknowledgement and request correctness information to the web service.
5.  The payment platform sends the request for performing a debit operation to the payment system.
6.  The payment system processes the request and forwards it to the issuer.
7.  The issuer processes the debit operation and transfers the funds from the customer to the merchant.
8.  The issuer sends a notification with the debiting result information to the payment system.
9.  The payment system sends the notification with the debiting result information to the payment platform.
10. The payment platform sends a callback with the debiting result to the web service.
11. The customer receives the debiting result information from the web service.
12. From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 5 through 11.

## Request format {#en_gate_cof_gate_side_request}

There are several things you need to consider when sending a request for a COF purchase with automatic debitingusing a payment card:

1.  To initiate each purchase, send a separate POST request to the [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring) endpoint.
2.  Each request must include the following objects and parameters:
    -   `general`—object with general request identification information:
        -   `project_id`—project identifierobtained from Ecommpay during integration.
        -   `payment_id`—payment identifier, unique within the project.
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in [Signature generation and verification](en_platform_signature.md)\).
    -   `customer`—object with customer information:
        -   `id`—customer identifier, unique within the project, the same identifier as the one used to register this COF purchase.

            **Warning:** Using different customer identifiers for operations performed as part of the COF purchase is not allowed.

        -   `ip_address`—customer IP addressrelevant for the initiated payment.
    -   `payment`—object with payment information:
        -   `amount`—payment amount in the smallest currency unit.
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format.
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority;
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution;
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments;
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation.
    -   `recurring`—object with the COF payment information:
        -   `id`—identifier of the debit seriesreceived in the callback with the COF purchase registration data or assigned when the COF purchase information was migrated from another acquirer.
3.  The set of parameters required for executing a payment can vary depending on the regional characteristics and other aspects of the payment services providers. Refer to your Ecommpay account manager to learn more about the providers' specifics and requirements.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct request must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer IP address, signature, and the identifier of the debiting series record.

``` {#codeblock_zxq_zfm_13c .language-json}
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"K5D/aZAMdeR+YyilUwS=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079
  }
}
```

## Callback format {#en_gate_cof_gate_side_callback}

The payment platform communicates results of processing each debit operation in callbacks sent to your web service.These callbacks are arranged in a standard format the detailed description of which can be found in [Handling callbacks](en_platform_callbacks.md).

The following callback contains information about processing `4.00 USD` debit operation for card `431422******0056` of the customer with identifier `customer_12` within project `42`. The capability of debiting retries is not available.

```language-json
{  
  "customer":{  
    "id":"customer_12"
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2026"
  },
  "payment":{  
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "method":"card",
    "date":"2023-06-07T06:18:02+0000",
    "status":"scheduled recurring processing",    // Payment status
    "type":"recurring",    // Payment type
    "id":"456789",
    "description":""
  },
  "project_id":42,
  "recurring":{  
    "valid_thru":"2023-07-31T00:00:00+0000",
    "currency":"USD",
    "id":1079    // Identifier of the debit series
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",    // Operation type
    "status":"success",    // Operation status
    "date":"2023-06-07T06:18:02+0000",
    "created_date":"2023-06-07T06:18:02+0000",
    "request_id":"5cfa0199c33071",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":6,
      "payment_id":"1192",
      "date":"2023-02-07T08:34:24+0000",
      "auth_code":"5253",
      "endpoint_id":6
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...=="
}
```

If the capability to perform debiting retry attempts is enabled, callbacks include the `recurring_retry` object. The description of its format can be found [in this article](en_gate_cof_retry_attempts.md).



---

# Managing debiting series of a COF purchase {#en_gate_payment_recurring_manage}

An article about the capabilities of managing debiting series of recurring purchases via Gate, including retrieval of information about the debiting series, updating its parameters, and canceling the recurring purchase.

The payment platform allows you to manage debiting for any COF purchase types by doing the following:

-   getting information about debiting series
-   updating COF purchase parameters: change debit amount and expiration date for all COF purchase types and modify debit schedule for regular COF purchases
-   cancelling COF purchase at any time

Note that customer can at any time contact the issuer and have COF purchase cancelled. In this case, any following debiting operation is cancelled and the stored payment instrument credentials are deleted from the payment platform.

In addition, you can manage settings of regular COF purchases by using [Dashboard](en_dbl_payments.md).

## Getting information about debiting series {#section_vkt_cf2_5jb .section}

There are several things you must consider when sending a request for information about debit series:

1.  You need to use a POST request to one of the [/v2/payment/recurring/info](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-recurring-info) endpoint.
2.  Your request must contain the following parameters and objects:
    -   `general`—object with general request identification information:
        -   `project_id`—project ID obtained from Ecommpay
        -   `signature`—signature created after you specify all the required parameters \(For more information about signing requests, see [Signature generation and verification](en_platform_signature.md).\)
    -   ID of the debit series inside the `id` parameter of the `recurring` object previously received in the callback with COF purchase registration information

Thus, complete request must contain project ID, signature, and ID of debit series.

```language-json
{  
  "general":{  
    "project_id":42,
    "signature":"v7KNMpfogMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}
```

The payment platform uses the standard format for response with debit series information.For more information about response format, see [Response format](en_gate_interaction_organisation.md).

The following response contains information about debiting `4,00 USD` to card `431422******0056` of the customer with ID `customer_12` within the `42` project. The response also notifies that subsequent debiting is possible.

```language-json
{  
  "project_id":42,
  "recurring":{ 
    "id":1079,    // Debit series ID
    "type": "R",
    "period": "W",
    "period_interval": 3,
    "start_date": "2020-10-20",
    "start_time": "10:00:00",
    "amount": 100,
    "last_payment_at": "0000-00-00 00:00:00",
    "valid_thru": "2025-05-25 00:00:00",
    "status": "active",
    "currency": "USD",
    "payment\_method": "card"
  }
}
```

## Updating debit series {#section_lpp_df2_5jb .section}

There are several things you must consider when sending a request for updating debit series:

1.  You need to use a POST request to one of the [/v2/payment/card/recurring/update](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring-update) endpoint.
2.  Your request must contain the following parameters and objects:
    -   `general`—object with general request identification information:
        -   `project_id`—project ID obtained from Ecommpay
        -   `payment_id`—payment ID, must be unique within the project
        -   `signature`—signature created after you specify all the required parameters \(For more information about signing requests, see [Signature generation and verification](en_platform_signature.md).\)
    -   `recurring`—object with the COF payment information:
        -   `id`—ID of debit series received in the callback with COF purchase registration data
3.  You need also use other parameters of the `recurring` object:
    -   `period`—frequency of debits \(for a regular COF purchase\), possible values:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly \(if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month\)
        -   `Q`—quarterly
        -   `Y`—yearly
    -   `interval`—multiplier to increase debiting frequency \(i.e. the interval of performing regular COF purchases\). This parameter is used in conjunction with the `period` parameter and should be assigned a numeric value from `1` to `100`.
    -   `time`—time of performing subsequent debits \(for a regular purchase\) in `hh:mm:ss` format. The parameter is used if the `period` parameter is specified in the request.
    -   `amount`—fixed amount of subsequent debits in the smallest currency unit.
    -   `start_date`—date on which the first debit operation is performed \(for a COF regular purchase\). This parameter is used in conjunction with the `scheduled_payment_id` parameter and should be specified in the `DD-MM-YYYY` format.
    -   `expiry_day`—calendar day on which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `31`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_month`—month in which the specified duration period of the COF purchase will end \(the value should be provided as an integer from `1` to `12`, without a leading zero, in accordance with the Gregorian calendar\).
    -   `expiry_year`—year in which the specified duration period of the COF purchase will end \(in the `YYYY` format, in accordance with the Gregorian calendar\).

        **Note:** If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:

        -   For standard card payments—the corresponding parameter value \(day, month, year\) is determined based on the expiry date of the specified payment card.
        -   For other available methods—the corresponding parameter value is determined as follows:
            -   Calendar day—the last calendar day of the relevant month \(as specified in the `expiry_month` parameter or corresponding to the COF purchase registration date\).
            -   Month—the month in which the COF purchase was registered.
            -   Year—the year that is 10 years after the year in which the COF purchase was registered.
        Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

    -   `scheduled_payment_id`—identifier assigned to the payment within which scheduled debits are performed. It must differ from the identifier of the payment made to register a COF purchase and must be unique within the project.

Thus, complete request must contain project ID, payment ID, signature, ID of debit series, and debit series parameters to update.

```language-json
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079,
    "interval":3,
    "period":"M",
    "time":"12:00:00"
  }
}
```

The payment platform uses the standard format for callbacks with information about updating debit series. For more information about callback format, see [Handling callbacks](en_platform_callbacks.md).

The following callback affirms that COF purchase is set to perform debiting every third month at 12:00:00.

```language-json
{  
  "project_id":123,
  "recurring":{
    "id":1079,               // ID of debit series record
    "currency":"USD",
    "status":"active",       // Debit series status
    "type":"R",
    "expiry_month":"5",      // Month when COF purchase expires
    "expiry_year":"2025",    // Year when COF purchase expires
    "period":"M",            // Debiting period
    "period_interval":3,
    "time":"12:00:00"        // Time to perform debiting
  },
  "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...=="
}
```

## Cancel COF purchase {#section_wkc_2f2_5jb .section}

There are several things you must consider when sending a request to cancel COF purchase:

1.  You need to use a POST request to one of the [/v2/payment/card/recurring/cancel](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring-cancel) endpoint.
2.  Your request must contain the following parameters and objects:
    -   `general`—object with general request identification information:
        -   `project_id`—project ID obtained from Ecommpay
        -   `payment_id`—payment ID, must be unique within the project
        -   `signature`—signature created after you specify all the required parameters \(For more information about signing requests, see [Signature generation and verification](en_platform_signature.md).\)
    -   ID of the debit series inside the `id` parameter of the `recurring` object previously received in the callback with COF purchase registration information

Thus, complete request must contain project ID, payment ID, signature, and ID of debit series.

```language-json
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"VftZ1ZZ5D/aMdeR+CqilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}
```

The payment platform uses the standard format for callbacks with information about cancelling COF purchase. For more information about callback format, see [Handling callbacks](en_platform_callbacks.md).

The following callback update that the COF purchase with ID `1079` has been cancelled.

```language-json
{  
  "project_id":42,
  "recurring":{  
    "id":1079,           // Debit series ID
    "currency":"USD",
    "status":"canceled", // Status indicates COF purchase is cancelled
    "type":"R",
    "expiry_month":"5",
    "expiry_year":"2025",
    "period":"M",
    "period_interval":3,
    "time":"12:00:00"
  },
  "signature":"MpfogAxwRItZ1Z/AeMde+GrNYyUwSm...=="
}
```

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)



---

# Working with debiting retry attempts {#en_gate_cof_retry_attempts}

An article about working with the automatic debiting retries as part of processing a recurring purchase.

**Parent topic:**[Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)

## Overview {#en_gate_cof_retry_attempts_overview}

### Introduction {#section_ep1_czr_yhc .section}

If a scheduled automatic debiting is declined, for example, in case when the customer's account has insufficient balance,initiating this debiting can be attempted again in the Ecommpay payment platform after a certain time period.You can add this capability for specific projects and for a specific group of payment methods upon agreement with your Ecommpay account manager. Note that the merchant is responsible for notifying the customers that this functionality is being used, specifically when a scheduled debiting was declined and retry attempts have been set up.

If retry attempts are not used for COF purchases, when a scheduled debiting in the series is declined, the next scheduled debiting is expected to be processed in the payment platform according to the schedule\([details](en_gate_cof_retry_attempts.md)\). Whether an additional debiting should occur or whether the series of debitings should be cancelled is decided by the merchant.

### Special aspects {#section_l3p_vzr_yhc .section}

When working with the debiting retries, consider the following:

-   For each project you can implementa specific retry schedule: either a default one by Ecommpay or a custom one.
-   Debiting retries can be used for a limited number of the globally accepted payment methods: Apple Pay, Google Pay, and standardcard payments.
-   Debiting retries can be used only for regular COF purchases when the debiting schedule is stored on the side of the payment platform\(type `R`\).
-   Debiting can be retried only if the previous debiting attempts were declined by the issuer or the payment system.
-   Using the functionality of debiting retries does not guarantee that the funds will be withdrawn eventually. If the allowed number of retries does not result in debiting,then this debit operation is deemed declined \(it is assigned the `decline` status\), and the COF purchase in question is subsequently processed in the platform according to its debiting schedule.

### Use {#section_zvq_21s_yhc .section}

The specifics of using debiting retries can be illustrated with the following examples.

![](images/universal/retry_attempt_1.svg "1—without retries")

![](images/universal/retry_attempt_2.svg "2—default retry schedule")

![](images/universal/retry_attempt_3.svg "3—default retry schedule, with cancellation ")

![](images/universal/retry_attempt_4.svg "4—custom retry schedule")

Suppose within a specific COF purchase automatic debitings areinitiated on Monday at 12:00 and, according to the schedule, are to be performed on November 02, 09, 16, and 23, but on November 09 and 16 scheduled debitings do not occur, then the options to respond to this situation can be as follows:

1.  If the functionality of debiting retries is not available for this purchase, thenregardless whether the scheduled debiting was completed or declined, the next scheduled debiting will be performed.
2.  If a default retry schedule from Ecommpay is used, then after the initial scheduled debiting is declined, the platform will retry it asmany times as determined by the schedule: the first two attempts will occur with a delay of 12 hours between them, the following attempts will occur every 24 hours, and the attempts will be stopped at least 24.5 hours before the next scheduled debiting on Monday.
3.  If a default retry schedule from Ecommpay is used, and the web service requests to stop subsequent debiting retries after three attempts are declined one after another, then if the initial debiting is declined, the platform will retry it up to three times in a row.
4.  If a custom retry schedule is used, then after the initial scheduled debiting is declined, the platform will retry it as many times as configured with a delay of 24 hours between consecutive attempts, and the attempts will be stopped at least 24.5 hours before the next scheduled debiting on Monday.

Since schedules of both regular COF purchases and debiting retry attempts can be flexibly configured, these scenarios can be used in a wide range of situations.However, it is also important to monitor statuses of all operations and maintain appropriate communication with customers depending on the operation statuses and retry schedule.

## Workflow {#en_gate_cof_retry_attempts_workflow}

The steps of the debiting retry procedure are as follows:

1.  When a scheduled debiting is initiallydeclinedby the payment system or the issuer, the Ecommpay payment platform checks if there is a possibility to retry the debiting once again. If this possibility is confirmed, the web service is sent a callback that contains the information about the declined debit operation with the `decline` operation status as well as the scheduled date and time of the retry attempt.
2.  At the scheduled time, the debiting retry attempt is performed automatically.
3.  Depending on the attempt result, the following steps are executed:
    -   If the attempt results in debiting the funds from the customer to the merchant, a callback containing the debiting result information \(with the `success` operation status \) is sent to the web service. The COF purchase series continues according to the existing schedule.
    -   If the attempt results in decline and the payment platform confirms the possibility to perform another attempt, a callback containing the information about the debiting decline \(with the `decline` operation status and the scheduled date and time of the next retry attempt\) is sent to the web service. Then step 2 is repeated.
    -   If the attempt results in decline and the payment platform does not confirm the possibility to perform another attempt, a final callback containing the information about the debiting decline \(with the `decline` operation status and without information about the next attempt\) is sent to the web service. The COF purchase series continues according to the existing schedule.In this case, whether an additional debiting should occur or whether the series of debit operations should be cancelled must be decided by the merchant.

The general workflow of this procedure is as follows.

![](images/en_gate_uml_scheduled_recurring_retry.svg)

1.  If a scheduled debiting has not initially resulted in transferring of funds, the payment platform checks if there is a possibility to retry debiting.
2.  The payment platform sends a callback to the web service containing the information about the debiting decline \(with the `decline` operation status \) and the scheduled date and time of the retry attempt.
3.  The web service informs the customer that the debit operation was declined and a retry attempt is scheduled.
4.  The payment platform sends a request to perform a debit operation to the payment system on the scheduled date and time.
5.  The payment system processes the request and forwards it to the issuer.
6.  The issuer processes the debit operation.
7.  The issuer sends a notification about the debiting result to the payment system.
8.  The payment system sends the notification about the debiting result to the payment platform.
9.  The payment platform checks if the retry attempt is needed and available. If necessary, the payment platform initiates subsequent retry attempts, and for each attempt, steps 2 through 8 are repeated.
10. The payment platform sends a debiting result callback to the web service: with the `decline` operation status if none of the retries resulted in debiting or `success` if one of the retries resulted in debiting.
11. The web service informs the customer about the debit operation result.
12. From this point forward, the payment platform can initiate subsequent scheduled debit operations, with each following steps 1 through 11.

The format of callbacks used in this workflow is described [below](en_gate_cof_retry_attempts.md).

## Setup {#en_gate_cof_retry_attempts_integration}

To set up the functionality of debiting retries:

1.  With your Ecommpay account manager, discuss and agree upon setting up this functionalityand whether testing is necessary.
2.  If you need testing, get notified by the Ecommpay specialists that the functionality is ready for being used in test mode,test this functionality, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the functionality has been added and fully set up.

## Managing retry schedules {#en_gate_cof_retry_attempts_schedule}

### Overview {#section_kk5_pds_yhc .section}

The payment platform allows you to implement one schedule of debiting retries for a specific project. The schedule applies to all regular COF purchases within this project. To set up, you can send requests via Gate \(more on this below\) or use the tools of the Dashboard interface \([details](en_dbl_payments.md)\). It can be a default schedule from Ecommpay or a custom schedule that you can set up on your own depending on the specific project

The main characteristics of these schedule types can be compared as follows.

-   In case of a default schedule, for each scheduled debiting there can be no more than 7 retry attempts carried out within 6 days.

    The time interval between an initial debiting and the first retry attempt as well as between the first and the second retry attempts equals 12 hours. If, according to the debiting schedule, the next debiting is to occur less than 12.5 hours after the retry attempt, the retry attempt is not performed. The remaining five retry attempts are carried out every 24 hours, with the restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt.

-   In case of a custom schedule, for each scheduled debiting there can be 1 to 10 retry attempts carried out within 10 days.

    The time interval between the retry attempts can vary, but it must be a multiple of 24 hours, and there is a restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt. For example, if the debiting is scheduled once a month, the four retry attempts can be set with the increasing time interval of 24, 48, 72, and 96 hours \(occurring on the first, third, sixth, and tenth day, in compliance with an overall 10 day time limit for retries and the restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt\).


The schedule implemented for any project can be customisedby modifying its specific parameters or by resetting them to default. Keep in mind that a retry attempt that was scheduled before the retry schedule was customised is performed according to the initially set date and time\(according to the previous schedule\). However, if any of these attempts is declined after the schedule was modified and it is possible to perform the next attempt of this debiting retry in the payment platform, then the new attempt is scheduled and performed according to the updated schedule.In either case, the information about each subsequent retry attempt is sent to the web service in the callback notifying that a debiting attempt was declined \([details](en_gate_cof_retry_attempts.md)\).

When working via the Gate API, keep in mind that requests for modifying retry schedules are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each request is fully processed within one HTTP session and uses only the resources of the payment platform. The response to the correct request contains an HTTP response status code \(`200`\) and the required data without detailed request processing information. If the request is incorrect, or there have been issues with its acceptance and processing, then the response contains an HTTP response status code, request processing status `error`, and the detailed description of the error that occurred. The description of the response format can be found [here](en_gate_interaction_organisation.md).

### Configuring a custom schedule {#section_ess_133_qhc .section}

To customise a retry schedulevia the Gate API for a specific project:

1.  Send an HTTP-POST request to the [/v2/recurring/retry-custom-schedule/save](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-save) endpoint.
2.  Receive a synchronous response communicating that the schedule was updated in the platform.

The request must contain the following objects and parameters:

-   `general`—object with the general identification information
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `signature`—request signaturegenerated after all required parameters are specified \(details can be found in the article [Signature generation and verification](en_platform_signature.md)\)
-   `interval_days`—array with the ordinal numerals indicating the days on which retry attempts are to be performed, counted from the day when the initial debiting was declined andspecified as an ascending sequenceof numbers from 1 to 10, with comma used as a delimiter\(for example, `[1,5,9]`\)

Thus, a correct request must contain the project identifier, signature, and the `interval_days` array. In the following example, the retry attempts are scheduled on the first, fifth, and ninth day after the initial debiting was declined.

``` {#codeblock_p2d_bk3_qhc .language-json}
{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}
```

``` {#codeblock_grz_wk1_c3c .language-json}
{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}
```

When the request to configure a retry scheduleis processed, the payment platform sends a response with the code `200 OK` to the web service.If the request is declined, the response contains a request processing status `error` and the description of the error that occurred, for example, `Recurring retry not enabled`.

### Checking the schedule {#section_gl4_qds_yhc .section}

To check the schedule of debiting retry attempts for a specific projectvia the Gate API:

1.  Send an HTTP-POST request to the [/v2/recurring/retry-custom-schedule/info](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-info) endpoint.
2.  Receive a synchronous response with information about the schedule.

The request must contain the following objects and parameters:

-   `general`—object with the general identification information
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `signature`—request signaturegenerated after all required parameters are specified \(details can be found in the article [Signature generation and verification](en_platform_signature.md)\)

Thus, a correct request must contain the project identifier and signature.

``` {#codeblock_ojj_vf3_qhc .language-json}

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}
```

``` {#codeblock_cbm_dvn_c3c .language-json}

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}
```

When the request to check a retry scheduleis processed, the payment platform sends a response with the code `200 OK` and required information to the web service.If the request is declined, the response contains a request processing status `error` and the description of the error that occurred. The response body contains the projects identifier and the `schedule` object.

If the retry schedule was customised for a specific project in the platform, the `schedule` object includes the following parameters:

-   `interval_days`—array with the ordinal numerals indicating the days on which retry attempts are to be performed, counted from the day when the initial debiting was declined andspecified as an ascending sequenceof numbers from 1 to 10, with comma used as a delimiter\(for example, `[1,5,9]`\)
-   `status`—indicator specifying whether the custom schedule is activated \(contains the value `active`if the custom schedule has been configured and not deactivated for the project\)

If a default retry schedule from Ecommpay is used for a specific project, the `schedule` object will be empty.

In the following example, the response communicates that for project `42` a custom schedule was configured, with the retry attempts set on the first, fifth, and ninth day after the initial debiting was declined.

``` {#codeblock_snw_5g3_qhc .language-json}
{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}
```

``` {#codeblock_h22_1xn_c3c .language-json}
{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}
```

In the following example, the response does not contain any data in the `schedule` object, which means that for project `42` a default schedule is used.

```language-json
{
  "project_id": 42,
  "schedule": {}
}
```

```language-json
{
  "project_id": 42,
  "schedule": {}
}
```

### Resetting the schedule to default values {#section_hf1_sds_yhc .section}

To reset the retry schedule to default values for a specific projectvia the Gate API:

1.  Send an HTTP-POST request to the [/v2/recurring/retry-custom-schedule/disable](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-disable) endpoint.
2.  Receive a synchronous response communicating that the request has been processed.

The request must contain the following objects and parameters:

-   `general`—object with the general identification information
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `signature`—request signaturegenerated after all required parameters are specified \(details can be found in the article [Signature generation and verification](en_platform_signature.md)\)

Thus, a correct request must contain the project identifier and signature.

``` {#codeblock_d4s_jtn_qhc .language-json}
{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}
```

``` {#codeblock_hdj_k5z_b3c .language-json}
{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}
```

When the request to reset the schedule to default valuesis processed, the payment platform sends a response with the code `200 OK` to the web service.If the request is declined, the response contains a request processing status `error` and the description of the error that occurred.

## Monitoring debiting retries {#en_gate_cof_retry_attempts_monitoring}

The debiting retries are performed automatically in the payment platform, according to a specificschedule and [the processing workflow](en_gate_cof_retry_attempts.md). On the side of the web service, you need to monitor the retries and maintain appropriate communication with customers depending on the debiting operation results.

To monitor the schedule and execution of each retry attempt, you can use callbacks sent from the platform \([details](en_platform_callbacks.md)\). In cases when retrying automatic debitings is enabled for the project, callbacks include the `recurring_retry` object that can include some or all of the following parameters:

-   `trigger_operation_id`—identifier of the debit operation that was retried. Specified when at least one retry attempt was performed.
-   `retry_count`—the number of the retry attempts already used up\(an integer from 1 to 7in case of the default schedule and from 1 to 10 in case of the custom one\). Specified when at least one retry attempt was performed.
-   `next_retry_exists`—an indicator that shows whether the next scheduled attempt is available. This parameter is set to `true`if the debiting resulted in decline and there is an available retry attempt \(the number of attempts and the time allocated for making them are not used up\). In all other cases this parameter is set to`false`. Specified in all cases.
-   `next_retry_date`—the scheduled date and time of the next retry attempt. Specified when the next retry attempt has been scheduled.

The following example of a callback contains information that no retry attempts were performed or scheduled for one of the debit operations in the series. Such callbacks are sent if the debiting resulted in funds transfer when it was first initiated or retry attempts cannot be performed.

``` {#codeblock_xsk_ybp_qhc .language-json}
"recurring_retry": {   
            "next_retry_exists": false 
            }
```

The following example of a callback contains information that the declined debiting can be retried and the first retry attempt has been scheduled \(`"next_retry_exists": true`\). In this case, the identifiers of the debit operation and the retry attempt are not specified because no retry attempts have been performed yet.

``` {#codeblock_usk_ybp_qhc .language-json}
"recurring_retry": {   
            "next_retry_exists": true,
            "next_retry_date": "2026-01-21T16:58:02+0000"  
            }
```

The following example of a callback contains information that the first attempt \(`"retry_count": 1`\) to retry debit operation `344589675` was declined and, as a result, the second attempt \(`"next_retry_exists" : true`\) has been scheduled for this debit operation at `2026-01-25T16:58:02+0000`.

``` {#codeblock_vsk_ybp_qhc .language-json}
"recurring_retry": {   
            "trigger_operation_id": 344589675,
            "retry_count": 1,
            "next_retry_exists": true,
            "next_retry_date": "2026-01-25T16:58:02+0000"  
            }
```

The following example of a callback contains information that the second attempt \(`"retry_count": 2`\) to retry debit operation `344589675` have been completed and no subsequent retry attempts have been scheduled \(`"next_retry_exists" : false`\). This can be either the case that the funds were transferred from the customer to the merchant \(then the operation status should be `success`\), or that there are no available retry attempts left as they have been used up without actual transfer of funds \(then the operation status should be `decline`\).

``` {#codeblock_wsk_ybp_qhc .language-json}
"recurring_retry": {     
            "trigger_operation_id": 344589675,
            "next_retry_exists": false,
            "retry_count": 2
            }
```

## Cancelling retries {#en_gate_cof_retry_attempts_cancel}

To cancel retrying a specific debiting via the Gate API:

1.  Send an HTTP-POST request to the [/v2/recurring/retry\_stop](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-stop) endpoint.
2.  Receive a synchronous response communicating that performing the subsequent retry attempts has been cancelled.

Keep in mind that these requests are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each such request is fully processed within one HTTP session. The response to the correct request contains the required data.The description of the response format can be found [here](en_gate_interaction_organisation.md).

The full sequence of processing request to cancel retry attempts is provided below.

![](images/en_gate_uml_scheduled_recurring_retry_stop.svg)

1.  The web service sends to the Ecommpay URL a request to cancel the retry attempts scheduled in the payment platform for the declined debiting.
2.  The request enters the payment platform.
3.  The payment platform processes the request and ceases to retry this debiting.
4.  The payment platform sends a response with the request processing result to the web service.
5.  The web service informs the customer about the debiting result.
6.  The payment platform initiates subsequent debit operations according to the existing COF purchase schedule.

Each request to cancel retrying the specific debiting must include the following objects and parameters:

-   `general`—object with general request identification information:
    -   `project_id`—project identifierobtained from Ecommpay during integration.
    -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the article [Signature generation and verification](en_platform_signature.md)\).
-   `recurring`—object with the COF payment information:
    -   `id`—identifier of the debit seriesreceived in the callback with the COF purchase registration data or assigned when the COF purchase information was migrated from another acquirer.
-   `trigger_operation_id`—identifier of the recurring debit operationfor which you need to cancel retries.

Thus, a correct request to cancel retries must contain the project identifier, signature, and the identifiers of the debiting series record and the relevant debit operation.

``` {#codeblock_erz_wk1_c3c .language-json}
{ 
  "general":{ 
    "project_id":42,
    "signature":"K5D/anjn7fv+YyilUwS=="
  },
  "recurring":{
    "id":1079
   },
  "trigger_operation_id":092384
}
```

``` {#codeblock_grz_wk1_c3c .language-json}
{ 
  "general":{ 
    "project_id":42,
    "signature":"K5D/anjn7fv+YyilUwS=="
  },
  "recurring":{
    "id":1079
   },
  "trigger_operation_id":092384
}
```

When the request to cancel debiting retriesis processed, the payment platform sends a response with the code `200 OK` to the web service.If the request is declined, the response contains a request processing status `error` and the description of the error that occurred.

## Useful links {#en_gate_cof_retry_attempts_useful_links}

The following articles can be useful when working with debiting retry attempts:

-   [Monitoring and performing payments](en_dbl_payments.md)—about working with payments via Dashboard, including working with regular COF purchases and managing attempts to retry debit operations executed as part of regular COF purchases.
-   [COF purchase with automatic debiting](en_Gate__cof_gate_side.md)—about processing regular COF purchases via Gate, including general information, description of processing workflows and data formats for working with standard card payments.
-   [Interaction concepts](en_gate_interaction_organisation.md)—about interacting with the payment platform via the Gate API, including description of interaction workflows and general requirements to data formats.
-   [Handling callbacks](en_platform_callbacks.md)—about working with callbacks that allow receiving up-to-date information significant for processing of each payment, including description of callback types and data formats.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks in the process of interacting with the platform.



---

# Purchase refunds {#en_Gate_Refund .concept}

An article about refunding different types of purchases via Gate.

In the context of the Ecommpay payment platform, *refund* is a repayment of the money customer previously paid in a purchase operation. Refund *does not apply*, if the money were not previously actually transferred from customer to merchant, for example, if customer's money are held as a result of an authorization hold operation, the amount will be returned through releasing the authorization hold, but not through a refund. For more information, see [Two-step purchase](en_gate_payment_auth.md)\).

To perform refunds, you can use Gate and/or Dashboard. This section discusses how to perform refunds by using Gate.Note that general information is relevant for both cards and other payment instruments while the technical information applies only to card operations. For technical information about other payment instruments, see Methods.

## General information {#section_uxb_p52_dlb .section}

The payment platform supports refund for one-time purchases and COF purchases. In general, there is no time limit for making a refund after purchase is complete, though some payment methods may impose timeout after which refund may be no longer possible or require additional fee.

To make a refund using Gate, you need to submit the corresponding request to the `/v2/payment/\{payment\_method\}/refund` endpoint. When doing so, you need to observe all the special aspects and limitations as described in other sections in this documentation.

In general, depending on the refund amount, one of the following operations is performed:

-   `reversal`—the refund is initiated for the initial purchase amount *and* before the current business day closing
-   `refund`—the refund is initiated in either of the following scenarios: the refund is initiated for a fraction of the initial purchase amount on the same business day *or* the refund is initiated after the purchase business day closing for either fraction or total initial amount.

Though, there is an exception in this rule for the purchases with Visaor American Express cards: operation type depends only on timing:

-   `reversal` operation is created, if the refund is initiated before the current business day closing.
-   `refund` operation is created, if the refund is initiated after the current business day is closed.

**Note:** The business day here is understood as the time period which is used for clearing purposes. Normally, this is 24 hours, though it may be adjusted to account for day-light saving time. Business day start and end times may differ because of different factors, therefore it is advised to contact the Ecommpay support to get the most accurate information.

To sum up: refund is supported for one-time and COF purchases, it is started by using a single request which initiates either `refund` or `reversal` operation.

![Diagram of relations between request for refund, payment type, and operation](images/en_gate_model_refund.svg "Diagram of relations between request for refund, payment type, and operation")

Once a refund is complete, the payment platform sends to the web service a callback with refund completion result and the information about the current purchase status. After refund, purchase status can be one of the following:

-   `success`—purchase is complete, refund is not performed.
-   `reversed`—refund is performed in full before the current business day completion.
-   `refunded`—refund is performed in full after the current business day completion.
-   `partially reversed`—refund is performed for a fraction of the initial purchase amount before the current business day completion \(applicable only to Visaand American Express cards\).
-   `partially refunded`—refund is performed for a fraction of the initial purchase amount. \(For Visaand American Express cards, refund is performed after the current business day completion.\)
-   `scheduled recurring processing`—refund is performed for full or partial amount of the initial COF purchase. Note that this does not affect any future COF purchases.

## Special aspects {#section_o1n_dwl_5jb .section}

The refund performing period depends on the issuing bank or payment provider which performs the operation, and may take a long time.

Any refund changes the payment amount. The callback includes information about the actual payment amount still available for further refunds. The actual payment amount is calculated as the initial purchase amount minus all the amounts repaid to customer. Suppose that the initial purchase amount is `13.70 USD`. Then, if you make a `10.00 USD`  refund, the actual payment amount will be `3.70 `USD. If you make another refund for `3.70 USD`, the actual payment amount will be zero. The rule also applies to any recurrent purchases where the actual payment amount is the total of all purchases minus all refunds.

Depending on payment method, some refund aspects can differ, for instance additional commission may be charged for late refunds. For more information about special refund aspectsfor specific payment methods, see [Methods](en_pm_about.md) or contact your account manager at Ecommpay.

## Limitations {#section_g2m_fpf_5jb .section}

When performing refunds, you need to observe the following limitations:

-   The initial purchase must include at least one money transfer and the purchase status must be one of the following: `success`, `scheduled recurring processing`, or `partially refunded`.

    If the initial purchase did not result in any money transfer or if the purchase status is not one of the listed above statuses, the refund request is declined and the payment platform sends to your web service a callback with the `3281` error code.

-   Refund currency must me the same as the initial purchase currency.

    If the currency in your refund request differs from the initial purchase currency, the refund is declined and the payment platform sends to your web service a callback with the `3284` error code. \(For more information about error codes, see [Handling operation processing information](en_platform_payment_info_codes.md).\)

-   The time between consecutive attempts to send refund request must not be too small.

    If you send a repeated refund request within two minutes after the previous attempt, the refund will be declined and the payment platform will send your web service a callback with the `3285` error code.

-   The merchant account balance must be adequate to perform the refund.

    To check your account balance, you can use [Data API](https://api-data.ecommpay.com/)\(see [Using Data API](en_dbl_api_protocol.md) for details\) or Dashboard \(see [Financial accounting](en_dbl_balances.md) for details\). Alternatively, you can contact your account manager at Ecommpay.

-   Specific region requirement for refunds and requirements imposed by payment service providers and payment processors must be observed.

    For example, in Republic of Belarus, only one refund operation is allowed for each purchase.For more information about special refund features of specific payment methods, see [Methods](en_pm_about.md) or contact your account manager at Ecommpay.

-   There must be no chargeback claims pending for the purchase for which refund is requested.

    If there are any chargeback claim pending for the purchase, the refund request is declined and the payment platform sends to your web service a callback with the `3288` error code.


Additionally, the following limitations apply to partial refunds:

-   Partial refund amount cannot exceed the initial purchase amount, otherwise the refund request is declined and the payment platform sends to your web service a callback with the `3283` error code.
-   After processing a partial refund of a card payment, the actual payment amount should be at least 0.01 USD.

    The actual amount is checked on the payment platform side after the refund is initiated, the rates are used if the payment currency is other than USD. If the requirement is not met, the refund request is declined and a callback wit the `3117` error code is sent to the web service.

-   New partial refund can be initiated only if any previous partial refund in complete, otherwise the refund request is declined and the payment platform sends to your web service a callback with the `3285` error code.

For the information about request and callback formats for card operations, see below. For the information about request and callback formats for other payment methods, see [Methods](en_pm_about.md).

## Request format {#section_jwj_mf1_sjb .section}

Refund request format complies with general request format regulations as described in [Interaction concepts](en_gate_interaction_organisation.md), and the target endpoint for the request is [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund). The request body must contain the following objects and parameters:

-   `general`—object with general request information, contains the following parameters:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID for which refund need to be performed
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)\).
-   `payment`—object with payment information which contains the following parameters:
    -   `description`—description of the reason for refunding. This parameter is relevant only for refund operations. Passing this parameter does not modify in any way the description of the initial purchase if such description was included in the initial purchase request.

        The description of the reason for refunding can be passed in callbacks as a value of the `operation_description` parameter. This parameter is not used by default, but it can be added to the data set passed in callbacks upon coordination with the technical support specialists.


The parameter set listed above allows you to make only a full refund. To make a partial refund, you need to add the following parameters in the `payment` object:

-   `amount`—refund amount in minor currency units, must be not larger than the actual purchase balance
-   `currency` — payment currency in the ISO-4217 alpha-3 format, must be same as the initial purchase currency

Additionally, you can use any other parameters as specified in the Gate API specification.

To sum up: any refund request must include project and payment IDs, signature, refund description, as well as currency code and amount, if required.

```language-json
{
  "general": {
    "project_id": 239,
    "payment_id": "payment2",
    "signature": "of8k9xeKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },
  "payment": {
    "description": "refund",
// For partial refund:
    "amount": 1000,
    "currency": "USD"
  }
}
```

## Callback format {#section_ens_mf1_sjb .section}

Callback with refund result complies with general callback format regulations described in [Handling callbacks](en_platform_callbacks.md). The actual payment amount information is contained in the `payment` object, the information about the amount repaid to the customer is included in the `operation` object. Also, callback may include refund description in the `operation_description` object, if the support service have activated this option when onboarding.

**Note:** If several refunds are performed for a single purchase, each refund operation is assigned a separate identifier. The identifier is placed in the `operation_id` parameter inside the `operation` object.

Below, you will find examples of callbacks for two refund scenarios for an initial purchase with amount `13.70 USD`:

1.  Partial `10.00 USD` refund with the `partially refunded` status that makes the actual payment amount equal `3.70 USD`.
2.  Full `13.70 USD` refund with the `refunded` status that makes the actual payment amount equal `0.00 USD`.

Each example shows the purchase description included in the initial payment request and a description of refund reason.

```language-json
{ 
  "project_id":239,
  "payment":{ 
    "id":"payment2",
    "type":"purchase", // Purchase type: one-time purchase
    "status":"partially refunded", // Purchase status after partial return
    "date":"2019-11-13T14:52:14+0000",
    "method":"card",
    "sum":{ 
      "amount":370, // Actual payment amount
      "currency":"USD" // Payment currency code
    },
    "description":"Thai massage session" // Payment description
  },
  "account":{ 
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "operation_description":"Deficient service", // Refund reason
  "operation":{ 
    "id":3862,
    "type":"refund", // Operation type
    "status":"success", // Operation status
    "date":"2019-11-13T14:52:15+0000",
    "created_date":"2019-11-13T14:52:12+0000",
    "request_id":"0c4457b5fe8dada59-e7b58eceb8aecfa791-00049391",
    "sum_initial":{ 
      "amount":1000, // Refund amount
      "currency":"USD" // Refund currency code (same as initial purchase currency)
    },
    "sum_converted":{ 
      "amount":1000,
      "currency":"USD"
    },
    "code":"0",
    "message":"Success",
    "provider":{ 
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

```

```language-json
{ 
  "project_id":239,
  "payment":{
    "id":"payment2",
    "type":"purchase", // Payment type: one-time purchase
    "status":"refunded", // Payment status after full refund
    "date":"2019-11-13T13:52:09+0000",
    "method":"card",
    "sum":{ 
      "amount":0, // Actual payment amount
      "currency":"USD" // Payment currency
    },
    "description":"Thai massage session" // Payment description
  },
  "account":{
    "number":"431422******0056",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "customer":{
    "id":"1478"
  },
  "operation_description":"Service cancellation", // Refund reason
  "operation":{
    "id":3861,
    "type":"refund", // Operation type
    "status":"success", // Operation status
    "date":"2019-11-13T13:52:09+0000",
    "created_date":"2019-11-13T13:52:08+0000",
    "request_id":"67a97cd6b14f1aa0543c81e18cd270b66-aadc6e790206d5-00038611",
    "sum_initial":{ 
      "amount":1370, // Refund amount
      "currency":"USD" // Refund currency code (same as initial purchase currency)
    },
    "sum_converted":{
      "amount":1370,
      "currency":"USD"
    },
    "code":"0",
    "message":"Success",
    "provider":{
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

```

Here is a example in which a refund of `7.99 EUR` is performed for a COF purchase with multiple purchases totaling `7.99 EUR`. This makes the actual payment amount equal to `0.00 EUR`. In this case, the payment status does not change because more purchases are expected for the payment. \(For more information about payment statuses, see [Payment processing](en_platform_payment_model.md).\)

```language-json
{ 
  "project_id":239,
  "payment":{ 
    "id":"payment3",
    "type":"recurring", // Payment type: COF purchase
    "status":"scheduled recurring processing", // Payment status after refund
    "date":"2019-11-13T17:23:26+0000",
    "method":"card",
    "sum":{ 
      "amount":0, // Actual payment amount
      "currency":"EUR" // Payment currency
    },
    "description":"Thai massage session" // Payment description
  },
  "account":{ 
    "number":"431422******0056",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "customer":{ 
    "id":"1478"
  },
  "recurring":{ 
    "id":1061,
    "currency":"EUR",
    "valid_thru":"2027-05-31T00:00:00+0000"
  },
  "operation_description":"Refund for payment3 order", // Refund reason
  "operation":{ 
    "id":3861,
    "type":"refund", // Operation type
    "status":"success", // Operation status after successful refund
    "date":"2019-11-13T17:23:26+0000",
    "created_date":"2019-11-13T17:23:25+0000",
    "request_id":"bb36c8b4bce2c4-0198d59676189b0e344d1-00056689",
    "sum_initial":{ 
      "amount":799, // Refund amount
      "currency":"EUR" // Refund currency code (same as initial payment currency)
    },
    "sum_converted":{ 
      "amount":799,
      "currency":"EUR"
    },
    "code":"0",
    "message":"Success",
    "provider":{ 
      "id":414,
      "payment_id":"",
      "endpoint_id":6
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}
```

Here is an example in which a refund of `60.00 USD` for a one-time purchase is declined because of insufficient funds on merchant's account. This is indicated by the `3028` error returned by the payment platform. \(For more information about error codes, see [Handling operation processing information](en_platform_payment_info_codes.md).\) Note that the amount and status of the payment do not change.

```language-json
{ 
  "project_id":239,
  "payment":{ 
    "id":"payment7",
    "type":"purchase", // Payment type: one-time purchase
    "status":"success", // Payment status after refund decline
    "date":"2019-12-29T15:29:47+0000",
    "method":"card",
    "sum":{ 
      "amount":6000, // Payment amount
      "currency":"USD" // Payment currency
    },
    "description":"Thai massage session" // Payment description
  },
  "account":{ 
    "number":"431422******0056",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "operation_description":"Error", // Refund reason
  "operation":{ 
    "id":3869,
    "type":"reversal", // Operation type
    "status":"decline", // Payment status after refund decline
    "date":"2019-12-29T15:32:29+0000",
    "created_date":"2019-12-29T15:32:29+0000",
    "request_id":"713446e4b43-06bfc7eed42c4c854697846a-00059692",
    "sum_initial":{ 
      "amount":6000, // Refund amount
      "currency":"USD" // Refund currency code (same as payment currency)
    },
    "sum_converted":{ 
      "amount":6000,
      "currency":"USD"
    },
    "code":"3028", // Error code
    "message":"Insufficient funds on merchant balance", // Error description
    "provider":{ 
      "id":120,
      "payment_id":"",
      "endpoint_id":120
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}
```

## Related links {#section_bgg_xhl_5jb .section}

-   [Payment processing](en_platform_payment_model.md)—general information about supported payment types and possible statuses.
-   [Methods](en_pm_about.md)—detailed information about payments using various payment methods.
-   [Handling callbacks](en_platform_callbacks.md)—information about callbacks and how to use them.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—error codes used by the payment platform.
-   [Monitoring and performing payments](en_dbl_payments.md)—information about payments and operations performed by using Dashboard.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Payouts {#en_Gate_payout .concept}

An article about processing payouts via Gate.

**Note:** This article covers processing payouts via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of performing payouts:

-   [Payout](en_platform_payout_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of processing payouts in the Ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of performing payouts via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

## Overview {#section_htd_ylv_cjb .section}

*Payout* is a payment type which uses one request to make a one-time transfer of funds from merchant to customer.

Basically, the payment platform performs payouts on demand \(one-time payments\)and P2P \(person-to-person\) payouts; though, you can implement bulk payouts by using Dashboard. In the latter case, you can have the required payouts generated automatically. For more information about bulk payouts, see [Monitoring and performing payments](en_dbl_payments.md).

Basically, payout initiation request contains payment instrument details. However,if you perform payout on a payment card you can perform payout by token that is associated with the payment card details. To enable this option, you need to perform an initial payment \(purchase\) to create a token.For more information about using tokens, see [Using tokens](en_Gate_Token.md).

## The payout workflow {#section_lsx_3jl_ggb .section}

To perform a payout by using Gate the web service is required to do the following:

1.  Send the payout request to the following endpoint `/v2/payment/{payment method}/payout[/token]`.
2.  If necessary, complete the additional procedure of payment information submission that is used when any payment stakeholder requires additional information. The procedure is not currently supported for alternative payment methods.For more information, see [Submission of additional payment information](en_Gate_Clarification.md).
3.  Receive the callback with payout results from the payment platform.

The following diagram provides the information about the basic payout processing case \(without the completion of the additional procedure\).

![](images/en_uml_gate_payout.svg)

1.  A customer initiates a payout.
2.  The web service sends the payout request by using Gate to the payment platform.
3.  The payment platform receives the payout request.
4.  The payment platform performs the initial request processing that includes validation of the required parameters and signature.
5.  The payment platform sends to the web service the response with request receipt confirmation and correctness check result.
6.  The payment platform performs the internal payment request processing and sends it to the payment environment.If you process the payout by using payment card, the payment environment is a bank service. If you process the payout by using alternative payment instrument, one is the payment system service.
7.  The payout is processed on the payment service side.
8.  The payment platform receives the payout result notification.
9.  The payment platform sends the callback to the web service.
10. The customer receives the payment result from the web service.

The sections that follow discuss in more details the request format and the parameters to be used in requests for payouts to payment cards, as well as provide information about the format of callbacks which contain payout results. Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_payment_model.md).

## Request format {#section_t11_mfk_1jb .section}

There are several things you need to consider when using payout requests to payment cards:

1.  You perform payout by sending the request by using POST \(HTTP\) method to one of the following endpoints:
    -   when making a payout by card number—[/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout),
    -   when making a payout by the token that is associated with payment card details—[/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token),
    -   when making a P2P payout—[/v2/payment/individual/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-individual-payout).
2.  The following objects and parameters must be specified in the request:
    -   Object `general`—general request identification information:
        -   `project_id`—the project ID obtained from Ecommpay
        -   `payment_id`—payment ID unique within the merchant project
        -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object `customer`—customer information:

        -   `id`—the ID of the customer within the merchant project
        -   `first_name`—customer first name
        -   `middle_name`—customer middle name or patronymic
        -   `last_name`—customer last name
        -   `ip_address`—IP address
        **Note:**

        The first name, the middle name \(or patronymic\), and the last name of the customer must be specified for all cards with the exception of those issued in the Russian Federation. For the latter, passing these parameters is not required, but in certain cases not providing them may lead to declined payments. To increase the probability of payment acceptance by issuers, it is recommended to pass both the first and the last name of the payout recipient, or at least one of these parameters. For up-to-date information about specifying the first name, the patronymic, and the last name for payouts to cards issued in Russia, contact your Ecommpay account manager.

        The first name, the middle name \(or patronymic\), and the last name must be specified in Basic Latin characters for all cards with the exception of CUP cards for which this information must be provided in Chinese characters.

        In case of payouts that originate from physical persons and that are processed as part of the programs supported for the Mastercard MoneySend service, it is required that the first and last names of the payout recipient are specified in the `recipient` object. Therefore, it is not necessary to specify this information in the `customer` object \([more](en_Gate_payout.md#li_ucr_fj5_tqb)\). This requirement applies to all cards regardless of where they were issued.

    -   Object `payment`—payment information:
        -   `amount`—payout amount in minor units
        -   `currency`—payout currency in the ISO-4217 alpha-3 format
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority;
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution;
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments;
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation.
3.  The request must contain the following information about the payment card which will be used in the payout:
    -   For a payout by card number—the card number in the `pan` parameter of the `card` object.

        In case of global payouts, together with the card number you may need to provide the expiration date and the name of the cardholder in the `year`, `month`, and `card_holder` parameters of the object `card`. To learn more about global payouts, contact your Ecommpay account manager.

    -   For a payout by token—the token of the card received from Ecommpay in the `token` parameter.
4.  In the case of a payout to any Visa card, the request should contain the date of birth of the sender, specified in `DD-MM-YYYY` format in the `day_of_birth` parameter in the `sender` object.

5.  In the case of a payout to a Visa card issued in Canada, the request must contain the `recipient` object with the payout recipient's address data:
    -   `country`—recipient's country code in ISO 3166-1 alpha-2
    -   `city`—recipient's city
    -   `address`—recipient's address
    -   if the specified country code is [CA](references/en/countries/CA.md) or [US](references/en/countries/US.md), also pass the `state` parameter that provides information about the recipient's state, province, or any other region
6.  In the case of a payout processed as part of the Visa Money Transfer program to a card issued in Brazil or Qatar, the request must contain the sender's phone number in the `phone` parameter of the `sender` object.
7.  In the case of a payout to a Mastercard, the value of the `address` parameter passed in the `customer` object cannot exceed 50 characters.
8.  In the case of a payout that originates from a physical person and that is processed as part of the programs supported for the Mastercard MoneySend service, the request must contain the information about the payout recipient's name in the `first_name` and `last_name` parameters of the `recipient` object and the information about the payout sender in the `sender` object:
    -   number of the sender's payment instrument—`pan` for the sender's card or `wallet_id` for the sender's electronic wallet
    -   `first_name`—sender's first name
    -   `last_name`—sender's last name
    -   `address`—sender's address
    -   `city`—sender's city
    -   `zip`—sender's postal code
    -   `country`—sender's country code in ISO 3166-1 alpha-2
    -   if the specified country code is [CA](references/en/countries/CA.md) or [US](references/en/countries/US.md), also pass the `state` parameter that provides information about the sender's state, province, or any other region
9.  In the case of a P2P payout it is recommended to specify the sender data:
    -   `first_name`—first name
    -   `last_name`—last name,
    -   `citizenship`—citizenship
    -   `residence`—country of residence
    -   `birthplace`—place of birth
    -   Object `billing`—sender billing address information
10. If required, you can also add any other additional parameters and objects Gate supports.

Thus, to perform a payout on a payment card, the correct payout request must include project and payment IDs, signature, the ID and IP-address of the customer, amount and currency of the payout, as well as the number or token of the card \(for crediting\), as shown in the following example:

```language-json
{
    "general": {
        "project_id": 874,
        "payment_id": "1553840734526111",
        "signature": "1wR1YgDoDlJppOdLzFOFKY4YonbWmspbFh7x1o1ut5PxxTIJfQ==",
    },
    // Card number when payout by the card number
    "card": {
        "pan": "5413330000000019"
    },
    "customer": {
        "id": "1",
        "ip_address": "185.123.193.224"
    },
    "payment": {
        "amount": 15000,
        "currency": "EUR"
    },
    // Card token when payout by the token
    "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7"
}
```

```language-json
{
    "general": {
        "project_id": 100,
        "payment_id": "Payment 12",
        "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJgu...=="
  },
    "card": {
        "pan": "4242424242424242",   
        "year": 2020,    
        "month": 11
    },
    "customer": {
        "ip_address": "127.0.0.1",
        "id": "New",
        "phone": "999123456",
        "first_name": "John",
        "middle_name": "Jr",
        "last_name": "Jonson",
        "datetime": "2017-10-04T19:06:31+05:00",
        "birthplace": "Manchester",
        "identify": {
            "doc_number": "4666 123456",
            "doc_type": "Passport",
            "doc_issue_date": "20.12.2012",
            "doc_issue_by": "12346"
        },
        "billing": {
            "country": "GB",
            "city": "London",
            "address": "Level st, 23",
            "postal": "112233"
        },
        "day_of_birth": "05-06-1981"
        },    
    "sender": {
        "phone": "39999999999",
        "first_name": "Jack",
        "middle_name": "Willy",
        "last_name": "Jackson",
        "datetime": "2018-12-05T19:06:31+05:00",
        "birthplace": "Manchester",
        "residence": "BL",
        "citizenship": "LV",
        "identify": {
            "doc_number": "1234 654321",
            "doc_type": "Passport",
            "doc_issue_date": "07-08-2014",
            "doc_issue_by": "23456"
        },
        "billing": {
            "country": "GB",
            "city": "London",
            "address": "Level st, 25",
            "postal": "406879"
        },
        "day_of_birth": "07-08-1993"
    },
    "payment": {
        "amount": 5000,
        "currency": "GBP"
    }
}
```

## Callback format {#section_wsx_3jl_ggb .section}

The standard format for callbacks is used to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `100.00 USD` payout made to the card number `553691******0802` of the `customer_10` customer in the `874` project.

```language-json
{
    {
        "project_id": 874,
        "payment": {
            "id": "3013",
            "type": "payout",
            "status": "success",
            "date": "2019-06-24T11:08:49+0000",
            "method": "card",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "541333******0019"
        },
        "customer": {
            "id": "customer_10"
        },
        "operation": {
            "id": 14,
            "type": "payout",
            "status": "success",
            "date": "2019-06-24T11:08:49+0000",
            "created_date": "2019-06-24T11:07:42+0000",
            "request_id": "71228f54d21e776a481",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "provider": {
                "id": 1496,
                "payment_id": "60-1c6072de6000",
                "date": "2019-06-24T11:08:47+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+TaK4UzSgifLxgB6c9TSeb/peLxw=="
    }
}
```

The following example of callback is for a payout rejected due to the maximum payout limit being exceeded.

```language-json
{
    {
        "project_id": 874,
        "payment": {
            "id": "3013",
            "type": "payout",
            "status": "decline",
            "date": "2019-06-24T11:08:49+0000",
            "method": "card",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "541333******0019"
        },
        "customer": {
            "id": "customer_10"
        },
        "operation": {
            "id": 14,
            "type": "payout",
            "status": "decline",
            "date": "2019-06-24T11:08:49+0000",
            "created_date": "2019-06-24T11:07:42+0000",
            "request_id": "71228f54d21e776a481",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "provider": {
                "id": 1496,
                "payment_id": "60-1c6072de6000",
                "date": "2019-06-24T11:08:47+0000",
                "auth_code": ""
            },
             "code": "3104",
            "message": "Payment Constraint Invalid Payout Amount"
        },
        "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...=="
    }
}
```

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Payment instrument verification {#en_gate_account_verification .concept}

An article about verifying a payment instrument via Gate by debiting a zero amount or placing a hold on funds.

**Note:** This article covers payment instrument verification via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of payment instrument verification:

-   [Payment instrument verification](en_platform_account_verification_model.md)—an article in the section [Payment processing](en_platform_payment_model.md) that provides a general description of performing payment instrument verification in the Ecommpay payment platform and covers information about statuses that can be used in the process.
-   articles of the [Payment methods](en_pm_about.md) section containing a description of payment instrument verification via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

To find out whether you can use payment instrument verification, refer to your Ecommpay account manager.

## Overview {#section_nmn_ctf_fjb .section}

Payment instrument verification is a payment type in which the customer card or account is validated by either transferring a dummy \(zero\) amount from customer to merchantor by authorizing a specific amount \(non-zero\) on the customer card or account and then voiding the transfer or the authorization. The authorization amount can be changed on merchant's request. Normally, the authorized amount is released shortly after the operation, but in some instances the authorized amount can be held up to 45 days.

You can use verification to register any subscriptions without debiting funds for the first \(trial\) period or you can use it before perform a payout. For more information about COF purchases, see [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md).Payment instrument verification functionality can also be relevant for processing MO/TO \(Mail Order/Telephone Order\) payments which imply that customers provide payment card details over the phone, by email, or other means of communication. For more information about MO/TO payments, see [MO/TO payment processing](en_Gate_moto.md).

For additional fraud and chargeback risk assessment, you can use the capability of cardholder name verification together with the card verification \([details](en_gate_cardholder_name_verification.md)\).

## The payment instrument verification workflow {#section_qmn_ctf_fjb .section}

To perform the payment instrument verification by using Gate the web service is required to do the following:

1.  Send the request by using the POST \(HTTP\) method to the endpoint `/v2/payment/\{payment method\}/account_verification[/token]`.
2.  If necessary, complete the additional procedures:
    -   *3‑D Secure authentication*. This authentication is intended to provide security to online payments with payment cards. For more information on the authentication workflow, as well as request and callback formats, see [3‑D Secure authentication](en_gate_payment_3ds.md).
    -   *Additional payment information submission*. This procedure is intended for cases, where the initial request did not contain the information necessary for any payment process stakeholders. For more information on this procedure, see [Submission of additional payment information](en_Gate_Clarification.md).
3.  Receive the callback with verification results from the payment platform.

The following diagram outlines the basic case of verification workflow \(without the completion of the additional procedure\).

![](images/en_gate_account_verification.svg)

1.  A customer enters the payment instrument details on the web service side.
2.  The web service sends the payment instrument verification request by using Gate to the payment platform.
3.  The payment platform receives the verification request.
4.  The payment platform performs the initial request processing that includes validation of the required parameters and signature.
5.  The payment platform sends to the web service the response with request receipt confirmation and correctness check result.
6.  The payment platform performs the internal payment request processing and sends it to the payment environment. If you process the payment card verification, the payment environment is a bank service.If you process the alternative payment instrument verification, one is the payment system service.
7.  The payment instrument verification is processed.
8.  The payment platform receives the verification result notification.
9.  The payment platform sends the callback to the web service.

The sections that follow discuss in more details the request format and the parameters to be used in requests for payment card verification, as well as provide information about the format of callbacks the verification results. Information about possible statuses of this payment type can be found in [the corresponding article](en_platform_payment_model.md).

## Request format {#section_xmn_ctf_fjb .section}

There are several things you need to consider when using payment card verification requests:

1.  Send the request by using POST \(HTTP\) method to one of the following endpoints:
    -   when performing verification by card number—[/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)
    -   when performing verification by the token that is associated with payment card details—[/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)
2.  The following objects and parameters must be specified in the request:
    -   Object `general`—general request identification information:
        -   `project_id`—the project ID obtained from Ecommpay
        -   `payment_id`—payment ID unique within the merchant project
        -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object `customer`—customer information:
        -   `ip_address`—IP address
        -   `id`—the ID of the customer within the merchant project
    -   Object `payment`—payment information:
        -   `amount`—payment amount, the value is 0
        -   `currency`—payment currency in the ISO-4217 alpha-3 format
3.  The request must contain the following customer's payment card information:
    -   when passing complete card credentials—the following data in the `card` object:
        -   `pan`—card number
        -   `year`—year of expiration date
        -   `month`—month of expiration date
        -   `card_holder`—name of the cardholder, passed if this parameter is required for the specific project \(the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\)
        -   `cvv`—card verification code \(as indicated on the card\).This parameter is not necessary for processing of MO/TO payments. For more information, see [MO/TO payment processing](en_Gate_moto.md).
    -   when passing the token—token received from Ecommpay in the `token` parameter and the card verification code in the `cvv` parameter\(this parameter is not necessary for processing of MO/TO payments. For more information, see [MO/TO payment processing](en_Gate_moto.md)\).
4.  If required, you can also add any other additional parameters and objects Gate supports.

**Note:** The payment amount must be zero.

Thus, the correct payment card verification request must include project and payment IDs, signature, the customer's payment card details, the ID and IP-address of the customer, as shown in the following example:

```language-json
{
  "general":{
    "project_id":874,
    "payment_id":"15538406111",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"185.123.193.224",
    "id":"customer_10"
  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },

//when indicating complete card credentials:
  "card":{
    "pan":"4314220000000056",
    "year":2021,
    "month":9,
    "card_holder":"John Smith",
    "cvv":"123"
  },

//when indicating the token of a stored payment card:
  "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654",
  "cvv":"123"

//when COF payment registration is made:
  "recurring":{
    "register":true
  }
}
```

## Callback format {#section_fnn_ctf_fjb .section}

The standard format for callbacks is used to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about the successful verification of the `431422******0056` card of the customer `customer_10` in the `874` project. The card is verified and is registered for COF purchases.

```language-json
{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"success",
    "date":"2019-09-10T13:45:59+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"431422******0056",
    "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":8861226,
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "recurring":{
    "id":10505,
    "currency":"EUR",
    "valid_thru":"2022-09-30T00:00:00+0000"
  },
  "operation":{
    "id":4314220000000056,
    "type":"account verification",
    "status":"success",
    "date":"2019-09-10T13:45:59+0000",
    "created_date":"2019-09-10T13:45:57+0000",
    "request_id":"5cb898347e62b2c1-52dac6c8c",
    "sum_initial":{
      "amount":0,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "provider":{
      "id":120,
      "payment_id":"306449667",
      "date":"2019-09-10T13:45:59+0000",
      "auth_code":"188591",
      "endpoint_id":120
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"P9g0U+eF2QWs2A=="
}
```

The following example of callback is for a card payment verification that is rejected by the payment system without explanation.

```language-json
{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"decline",
    "date":"2019-09-16T06:06:53+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "operation":{
    "id":4314220000000056,
    "type":"account verification",
    "status":"decline",
    "date":"2019-09-16T06:06:53+0000",
    "created_date":"2019-09-16T06:06:47+0000",
    "request_id":"9120271eb02-83e0e70fc0a0a3c1b4d",
    "sum_initial":{
      "amount":0,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "provider":{
      "id":120,
      "payment_id":"308822001",
      "date":"2019-09-16T06:06:49+0000",
      "auth_code":"",
      "endpoint_id":120
    },
    "code":"10100",
    "message":"Declined by external provider"
  },
  "signature":"P9g0U+eaZ9EeNiWiaQWs2A=="
}
```

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Auxiliary procedures {#en_gate_procedures}

Articles about auxiliary procedures that can be required during processing specific payments via Gate.

This section provides the information about the procedures that can be required for processing certain payments.

-   [3‑D Secure authentication](en_gate_payment_3ds.md)—about customer authentication with the use of protocol 3‑D Secure 2 for ensuring secure payment processing.
-   [3‑D Secure authentication on merchant side](en_gate_merchant_3ds.md)—about an additional variant of customer authentication with the use of the 3‑D Secure protocol on the merchant web service side.
-   [Authentication on merchant's request](en_gate_payment_merch_auth.md)—about the procedure of additional customer authentication that can be used as an alternative to the 3‑D Secure authentication and is performed upon the merchant's request.
-   [Using the Address Verification Service](en_Gate_avs.md)—about the procedure of verifying the customers' postal codes and addresses to ensure secure processing of payments with the use of the American Express, Mastercard, and Visa cards.
-   [Using the Verification of Payee service](en_verification_of_payee.md)—about the procedure of verifying the customers' names when they issue a request to receive the funds, in order to ensure that bank transfers using the SEPA payment scheme comply with the European Union Instant Payments Regulation.
-   [Submission of additional payment information](en_Gate_Clarification.md)—about the procedure of providing additional data that can be requested by payment systems in separate cases.
-   [Currency conversion](en_Gate_Conversion.md)—about processing payments in different currencies for the customer and the merchant with the conversion involved.

-   **[3‑D Secure authentication](en_gate_payment_3ds.md)**  
An article about primary workflows of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Gate, performed through the Ecommpay platform.
-   **[3‑D Secure authentication on merchant side](en_gate_merchant_3ds.md)**  
An article about an additional option of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Gate, performed through third-party solutions and initiated by the merchant.
-   **[Authentication on merchant's request](en_gate_payment_merch_auth.md)**  
An article about the procedure of authenticating customers upon merchant's request that can be used as an alternative to the 3‑D Secure authentication for processing card payments via Gate.
-   **[Using the Address Verification Service](en_Gate_avs.md)**  
An article about the procedure of verifying customers' postal codes and addresses for processing American Express, Mastercard, and Visa payments via Gate.
-   **[Using the Verification of Payee service](en_verification_of_payee.md)**  
An article about the procedure of verifying customers' names when payouts to bank accounts using the SEPA payment scheme are initiated via Gate.
-   **[Submission of additional payment information](en_Gate_Clarification.md)**  
An article about the procedure of specifying additional data that can be requested by payment systems during payment processing via Gate.
-   **[Currency conversion](en_Gate_Conversion.md)**  
An article about processing payments via Gate in different currencies with currency conversion.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# 3‑D Secure authentication {#en_gate_payment_3ds}

An article about primary workflows of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Gate, performed through the Ecommpay platform.

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)

## Overview {#en_gate_payment_3ds_overview}

### General information {#section_dlj_gv3_zvb .section}

3‑D Secure \(Three-Domain Secure\) customer authentication is aimed at preventing fraud in processing of online card payments. This authentication procedure can be carried out in a variety of ways: the customer may be required to provide a one-time PIN \(OTP\) code, the customer's identity may be verified via facial recognition, the customer's fingerprint may be verified on their device, or the customer's involvement may be bypassed altogether based on the payment, device, and customer data. The choice of the authentication mechanism is decided on a case-by-case basis by the issuer.

**Note:** Global card networks such as American Express, Mastercard, and Visa as well as Ecommpay currently support the second version of the 3‑D Secure protocol, 3‑D Secure 2. The article contains the information about working with this protocol version.

3‑D Secure involves the interaction of three domains:

-   *Acquirer domain*: in the context of the Ecommpay payment platform interoperability, it includes the merchant's web service, the payment platform, and its 3DS Server.
-   *Interoperability domain*: it includes the Directory Servers \(DS\) of global card networks.
-   *Issuer domain*: it includes the issuer's Access Control Servers \(ACS\) and the authentication page \(ACS page\).

The domains exchange messages that are required to authenticate the customer. These messages include the authentication request \(Authentication Request Message, AReq\) and the corresponding response \(Authentication Response Message, ARes\) as well as the customer authentication request \(Challenge Request, CReq\) and the response containing the authentication result information \(Challenge Response, CRes\).

Note that the information about the possibility of cardholder authentication is stored on the Access Control Server, and this information can be obtained only after a request to process a card payment has been sent. Moreover, the web service and the payment platform do not have control over customer actions on the authentication page; they can only receive the authentication result.

### 3‑D Secure authentication flows {#section_hpc_mkj_zvb .section}

3‑D Secure supports the following authentication flows:

-   *Challenge flow*—authentication that requires the customer to perform certain actions in order to confirm their identity. Customers can be authenticated with the use of one-time code or biometric data if this capability is supported by the issuer, for example.
-   *Frictionless flow*—authentication that does not involve interaction with the customer. Customers are authenticated with the use of data that the issuer already has.

![](images/3ds2_flow.svg)

The merchant cannot select the authentication flow. While the merchant can indicate which flow selection is preferable, the final decision is made by the issuer. In addition to specifying the preferred flow, the merchant can pass a range of optional parameters in the payment request which increases the possibility of the frictionless flow selection and thereby helps increase acceptance rates and enhances customer experience.Information about these and other parameters can be found [below](en_gate_payment_3ds.md).

### Special aspects {#en_gate_payment_3ds_special_aspects}

#### Out of scope payments {#section_a1n_mxl_ndc .section}

As a rule, the 3‑D Secure authentication is mandatory for card payments. It is dictated by the requirements of the Payment Services Directive 2 \(PSD2\) that includes the requirement of Strong Customer Authentication \(SCA\) to be applied to such payments.

Payments that do not fall under the scope of the SCA mandated by PSD2 include:

-   Payments made with cards issued in a country that is not located in the European Economic Area.
-   Payments made with anonymous prepaid cards: for example, a gift card or a prepaid virtual card.
-   MO/TO \(Mail Order/Telephone Order\) payments.
-   Merchant-initiated transactions \(MIT\). In the Ecommpay payment platform such payments include autopurchases and regular purchases \(`recurring` payment type\)as well as operations to change the authorised amount \(`incremental` operation type\).
-   Most alternative payments.

The payment platform supports the capability to identify payments that belong to any of the aforementioned categories. As a result, they are not subject to 3‑D Secure.

#### Exemptions {#section_fmt_mxl_ndc .section}

Under PSD2, there are several exemptions to SCA when the authentication is deemed not necessary by the issuer. The exempt payments can be categorised as follows:

-   Low value payments \(Low value exemption\)—if it is a payment for an amount below 25 [GBP](references/en/currencies/GBP.md) \(within Great Britain\) or 30 [EUR](references/en/currencies/EUR.md) \(within the EEA\). Along with that, there should be no more than five payments since the most recent successful authentication attempt, and the total amount of these payments should not exceed 85 [GBP](references/en/currencies/GBP.md) or 100 [EUR](references/en/currencies/EUR.md) respectively.
-   Low risk payments \(Transaction Risk Analysis exemption\)—if it is a payment processed by an acquirer with the fraud rates that fall below the thresholds defined in PSD2.
-   Payments to trusted merchants \(Trusted beneficiaries exemption\)—if it is a payment to a merchant that was added by the cardholder \(or with the cardholder's consent\) to a trusted list.
-   Secure corporate payments \(Corporate payments exemption\)—if it is a payment initiated by a company with the use of procedures and protocols that ensure high level of fraud protection \(such as Electronic Banking Internet Communication Standard, EBICS\).

The Ecommpay payment platform supports working with the SCA exemptions for Mastercard and Visa payments of the first two categories: low value and low risk.

#### Working with the SCA exemptions {#section_ncz_mxl_ndc .section}

Applying exemptions may keep the customer payment experience seamless and increase the payment acceptance rates. However, the merchant is held liable for possible fraud in case of exempt payments.

If this capability is enabled, the relevant exemptions are applied automatically with the exception of the specific payments for which the merchant indicates that the authentication is necessary. At the same time, keep in mind that should the issuer deem it necessary, the exempt payment can still be processed with the authentication. In this case, the issuer can respond with a soft decline which means the authentication is required. Following a soft decline, standard authentication without exemptions is performed, and as a rule, the challenge flow is used. Moreover, exemptions do not apply in case of the COF purchase registration for which 3‑D Secure is mandatory.

Information about applied exemptions is passed in the payment result callbacks and shown in the payment information tabs in Dashboard. If you have any questions about setting up and working with the SCA exemptions, refer to your Ecommpay account manager.

### User scenarios {#en_gate_payment_3ds_user_scenarios}

Depending on the 3‑D Secure authentication flow and other factors \(for example, the design of the preloader page and the interface used for initiating the payment\), the authentication process can vary for different customers.

To illustrate, if the challenge flow is used and the customer is redirected to the ACS page to enter the one-time code, the user scenario may include the following steps.

![](images/ecommpay/en_gate_3ds_interface_1.svg "Entering payment information")

![](images/ecommpay/en_gate_3ds_interface_2.svg "Preloader page")

![](images/ecommpay/en_gate_3ds_interface_3.svg "ACS page")

![](images/ecommpay/en_gate_3ds_interface_4.svg "Preloader page")

![](images/ecommpay/en_gate_3ds_interface_5.svg "Final page")

In case of the frictionless flow, the user scenario will not include the steps of customer redirection to the ACS page and return to the web service.

## Authentication workflows {#en_gate_payment_3ds_workflow}

### Overview {#section_yzt_ynr_zvb .section}

Similar to user scenarios, the 3‑D Secure workflows on the side on the web service and other parties can vary. In case of the web service, the authentication process is determined by the external decisions concerning the need for collecting additional data about the customer's device and the authentication flow. Each of such decisions can lead to the necessity to perform a specific procedure in addition to the basic steps of processing a payment.

|authentication flows|without collection of data|with collection of data|
|--------------------|--------------------------|-----------------------|
|frictionless flow|-   basic actions

|-   basic actions
-   collection of data

|
|challenge flow|-   basic actions
-   redirection

|-   basic actions
-   collection of data
-   redirection

|

The merchant cannot select any of these authentication scenarios on their own. However, they can influence the decisions made by other participants by passing recommended parameters and specifying which authentication flow \(frictionless or challenge\) is preferred for specific payments.

### General workflow {#section_ndr_hx4_ljc .section}

The following is a general workflow of processing a payment with the 3‑D Secure authentication.

![](images/en_gate_3ds_workflow.svg)

1.  The payment platform processes the initial payment request and determines whether the 3‑D Secure authentication is required \(according to payment processing rules and requirements\).
2.  The payment platform queries the 3DS Server whether the 3‑D Secure authentication is supported for the specified card and whether collecting the customer's device characteristics is necessary.
3.  The 3DS Server establishes whether 3‑D Secure is supported and whether collecting additional data is necessary.
4.  The 3DS Server sends the response to the payment platform indicating whether 3‑D Secure is supported and whether collecting the customer's device characteristics is necessary.
5.  The payment platform processes the response. If collecting additional data is not needed, step 6 is performed. If collecting additional data has been requested, the authentication procedure includes the following steps:
    1.  The payment platform sends the callback with the data for the iframe element to collect the customer's device characteristics to the web service.
    2.  The web service sends a synchronous response acknowledging the receipt of the callback to the payment platform.
    3.  The web service opens the iframe element to collect the customer's device characteristics.
    4.  The iframe script collects the data about the customer's device and sends it to issuer's Access Control Server.
    5.  The issuer sends a data receipt notification to the web service.
    6.  The web service sends the authentication initiation request to the URL provided by Ecommpay.
    7.  The payment platform receives the request.
    8.  The payment platform accepts and validates the request.
    9.  The payment platform sends the response acknowledging the receipt of the request and containing the result of the validity check to the web service.
6.  The payment platform forwards the authentication request to the 3DS Server.
7.  The 3DS Server forwards the request to the Directory Server.
8.  The Directory Server forwards the request to the Access Control Server.
9.  The issuer authenticates the customer. If the issuer selects the frictionless flow, the Access Control Server sends a message with the authentication result to the payment platform \(the message is forwarded through the Directory Server and the 3DS Server\). If the issuer selects the challenge flow, the authentication procedure includes the following steps:
    1.  The Access Control Server sends a message with the customer redirection data that includes the ACS URL to the payment platform through the Directory Server and the 3DS Server.
    2.  The payment platform sends the customer redirection data to the web service.
    3.  The web service redirects the customer to the authentication page.
    4.  The authentication page is displayed to the customer who then performs the actions required for authentication.
    5.  The issuer authenticates the customer.
    6.  The Access Control Server sends a message with the authentication result to the 3DS Server through the Directory Server.
    7.  The 3DS Server sends the message acknowledging the receipt of the result to the Access Control Server through the Directory Server.
    8.  The Access Control Server redirects the customer to the web service and sends the authentication result to the web service.
    9.  The preloader page hosted on the web service is displayed to the customer.
    10. The web service sends the payment completion request with the authentication result to the URL provided by Ecommpay.
    11. The payment platform receives the request.
    12. The payment platform accepts and validates the request.
    13. The payment platform sends a synchronous response acknowledging the receipt of the request and containing the result of the validity check to the web service, following which the payment platform processes the authentication result and performs necessary actions to complete the payment.

Information about the format of callbacks and requests used in this workflow can be found [below](en_gate_payment_3ds.md). General information about using the Gate API is provided in [Interaction concepts](en_gate_interaction_organisation.md). Note that this workflow can also include other procedures and steps that do not have anything to do with the process of authentication and that are described in corresponding articles of this documentation.

### Collecting the customer's device characteristics {#section_dfg_2gf_njc .section}

When the issuer requires collection of additional data about the customer's device characteristics, the payment platform sends [an appropriate callback](en_gate_payment_3ds.md#section_jnw_q24_cjb) to the web service. If you receive this callback:

1.  Check the integrity of data in the callback by verifying the signature.
2.  Confirm accepting and validating the callback by sending a `200 OK` synchronous response to the platform.
3.  Open the iframe element to collect the customer's device characteristics using the data received in the callback \([details](en_gate_payment_3ds.md#fig_zly_wq2_bjb)\).
4.  Accept [the message acknowledging receipt of data](en_gate_payment_3ds.md#section_d4n_vky_svb) from the issuer's Access Control Server.
5.  Send [the authentication initiation request](en_gate_payment_3ds.md#section_o1k_yky_svb) to the payment platform.

**Note:** You can decrease the frequency of having to use this procedure by issuer's request if you configure your web service to collect and send information about the customer's device in advance \([details](en_gate_payment_3ds.md)\).

### Redirecting the customer to the ACS page {#section_jjy_3jf_njc .section}

If the issuer selects the challenge flow with redirection of the customer to the ACS page, the payment platform sends [an appropriate callback](en_gate_payment_3ds.md#section_drq_xq1_1jb) to the web service. If you receive this callback:

1.  Check the integrity of data in the callback by verifying the signature.
2.  Confirm accepting and validating the callback by sending a `200 OK` synchronous response to the platform.
3.  Redirect the customer to the authentication page using the data received in the callback \([details](en_gate_payment_3ds.md#fig_k3g_qr2_bjb)\) within 30 seconds after the callback was received.
4.  Accept [the authentication result](en_gate_payment_3ds.md#section_cjg_rss_njb) from the issuer.
5.  Send [a payment completion request](en_gate_payment_3ds.md#section_gps_1fc_t3b) with the authentication result within 30 minutes after the callback that indicates the need for redirection was received.
6.  If the cascading payments option is enabled \([details](en_gate_cascading.md)\) and your web service receives an additional callback containing the `cascading_with_redirect` parameter \(set to `true`\), your web service is required to do the following:
    1.  Repeat step 1-2 of this procedure, accepting and validating the callback.
    2.  Display an authentication attempt error message to the customer.
    3.  Receive the customer's consent for retrying authentication.
    4.  Repeat steps 3-5 of this procedure.

**Note:** You can decrease the frequency of having to use this procedure by issuer's request if you configure your web service to collect and send recommended data in advance \([details](en_gate_payment_3ds.md)\).

## Specifying the customer's device characteristics {#en_gate_payment_3ds_collecting_data}

To improve user experience and increase payment acceptance rates, strive to minimise the number of actions the customers need to perform in the process of authentication. To do so, you are recommended to pass certain optional parameters in requests for processing payments that will require 3‑D Secure. These parameters help decrease the likelihood that procedures to collect additional data about the customer's device and to redirect the customer to the ACS page will be needed. Alongside the information about the customer and the payment listed [below](en_gate_payment_3ds.md), you should include the following information about the customer's device and browser:

-   Information about the device collected on the client side of the web service:
    -   `accept_header`—value of the HTTP Accept request header
    -   `accept_language_header`—value of the Accept-Language HTTP request header that specifies the preferred localisation language
    -   `browser`—value of the HTTP User-Agent request header
    -   `ip_address`—IP address of the customer during the payment session
-   Information about the device retrieved from the request sent from the browser to the web service:
    -   `color_depth`—colour depth of the customer's device, bits per pixel
    -   `java_enabled`—indicator that specifies whether the customer's browser supports Java
    -   `js_enabled`—indicator that specifies whether the customer's browser supports JavaScript
    -   `language`—code of the customer's browser language
    -   `screen_res`—screen resolution of the customer's device, in pixels, with an `x` character as a delimiter \(for example, `1920x1080`\)
    -   `timezone_name`—name of the time zone the customer's browser is set to \(for example, `Australia/Adelaide`\)
    -   `timezone_offset`—difference between a date as evaluated in the UTC time zone and the same date as evaluated in the browser time zone, specified in minutes, \(for example, `570`\)

``` {#codeblock_awz_lkh_43c .language-json}
    "customer": {
    "ip_address": "188.113.253.90",
    "browser": "Mozilla/5.0 (Linux; Android 14; SM-A155F Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.67 Mobile Safari/537.36",
    "screen_res": "1920x1080",
    "language": "en_US",
    "accept_header": "*/*",
    "accept_language_header": "en-GB,en;q=0.8,fr;q=0.3",
    "color_depth": 24,
    "java_enabled": false,
    "js_enabled": true,
    "timezone_offset": "570"
  }
```

To collect these data, configure your web service to perform the following steps.

1.  Determine the customer's device characteristics on the client side of the web service.

    ``` {#codeblock_asd_qkh_43c .language-javascript}
    function collectClientData() {
        return {
            // screen resolution of the device 
            screen_res: `${screen.width}x${screen.height}`,
             
            // code of the browser language
            language: navigator.language,
             
            // colour depth of the browser
            color_depth: screen.colorDepth,
             
            // indicates whether Java is enabled in the browser
            java_enabled: navigator.javaEnabled(),
             
            // indicates whether JavaScript is enabled in the browser
            js_enabled: true,
             
            // differnce between the browser time zone and the UTC
            timezone_offset: new Date().getTimezoneOffset().toString(),
        };
    }
    ```

2.  Send the collected data from the client side to the server side of the web service.

    ``` {#codeblock_af1_rkh_43c .language-javascript}
    async function sendClientDataToServer(endpoint = '/api/collect-client-data') {
        try {
            const clientData = collectClientData();
              
            const response = await fetch(endpoint, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Accept': '*/*'
                },
                body: JSON.stringify(clientData)
            });
              
            const result = await response.json();
            return result;
        } catch (error) {
            console.error('Failed to send data:', error);
            throw error;
        }
    }
    ```

3.  On the server side of the web service, add the data collected from the request sent from the customer's browser to the web service as well as other parameters necessary for sending the request, generate the signature, and send the request to the Ecommpay URL.

    ``` {#codeblock_xk5_rkh_43c .language-php}
    interface CustomerData
    {
        public function getIpAddress(): ?string;
     
        public function getAcceptHeader(): ?string;
     
        public function getAcceptLanguageHeader(): ?string;
     
        public function getScreenRes(): ?string;
     
        public function getBrowser(): ?string;
     
        public function getLanguage(): ?string;
     
        public function getColorDepth(): ?int;
     
        public function getJavaEnabled(): ?bool;
     
        public function getJsEnabled(): ?bool;
     
        public function getTimezoneOffset(): ?string;
    }
     
    interface CardData
    {
        public function getPan();
     
        public function getYear();
     
        public function getMonth();
     
        public function getCardHolder();
     
        public function getCvv();
    }
     
    interface PaymentData
    {
        public function getPaymentId(): string;
     
        public function getAmount(): int;
     
        public function getCurrency(): string;
     
        public function getCardData(): CardData;
     
        public function getCustomerData(): CustomerData;
    }
     
    interface HttpClient
    {
        public function sendRequest(array $request): bool;
    }
     
    interface Signer
    {
        public function sign(array $params): string;
    }
     
    final class PaymentController
    {
        public function __construct(
            private Signer $signer,
            private HttpClient $httpClient,
            private int $projectId,
        ) {}
     
        public function processPayment(PaymentData $paymentData): void
        {
            $paymentRequest = [
                'general' => [
                    'project_id' => $this->projectId,
                    'payment_id' => $paymentData->getPaymentId(),
                ],
                'customer' => $this->prepareCustomerData($paymentData->getCustomerData()),
                'payment' => [
                    'amount' => $paymentData->getAmount(),
                    'currency' => $paymentData->getCurrency(),
                ],
                'card' => [
                    'pan' => $paymentData->getCardData()->getPan(),
                    'year' => $paymentData->getCardData()->getYear(),
                    'month' => $paymentData->getCardData()->getMonth(),
                    'card_holder' => $paymentData->getCardData()->getCardHolder(),
                    'cvv' => $paymentData->getCardData()->getCvv(),
                ],
            ];
     
            $paymentRequest['general']['signature'] = $this->signer->sign($paymentRequest);
     
            $this->httpClient->sendRequest($paymentRequest);
        }
     
        private function prepareCustomerData(CustomerData $customerData): array
        {
            return array_filter([
                'ip_address' => $customerData->getIpAddress(),
                'browser' => $customerData->getBrowser(),
                'screen_res' => $customerData->getScreenRes(),
                'language' => $customerData->getLanguage(),
                'accept_header' => $customerData->getAcceptHeader(),
                'accept_language_header' => $customerData->getAcceptLanguageHeader(),
                'color_depth' => $customerData->getColorDepth(),
                'java_enabled' => $customerData->getJavaEnabled(),
                'js_enabled' => $customerData->getJsEnabled(),
                'timezone_offset' => $customerData->getTimezoneOffset(),
            ]);
        }
    }
    ```

    ``` {#codeblock_sk4_skh_43c}
    package main
     
    import "encoding/json"
     
    // CustomerData interface
    type CustomerData interface {
        GetIpAddress() *string
        GetAcceptHeader() *string
        GetAcceptLanguageHeader() *string
        GetScreenRes() *string
        GetBrowser() *string
        GetLanguage() *string
        GetColorDepth() *int
        GetJavaEnabled() *bool
        GetJsEnabled() *bool
        GetTimezoneOffset() *string
    }
     
    // CardData interface
    type CardData interface {
        GetPan() interface{}
        GetYear() interface{}
        GetMonth() interface{}
        GetCardHolder() interface{}
        GetCvv() interface{}
    }
     
    // PaymentData interface
    type PaymentData interface {
        GetPaymentId() string
        GetAmount() int
        GetCurrency() string
        GetCardData() CardData
        GetCustomerData() CustomerData
    }
     
    // HttpClient interface
    type HttpClient interface {
        SendRequest(request map[string]interface{}) bool
    }
     
    // Signer interface
    type Signer interface {
        Sign(params map[string]interface{}) string
    }
     
    // PaymentController struct
    type PaymentController struct {
        signer     Signer
        httpClient HttpClient
        projectId  int
    }
     
    // NewPaymentController constructor
    func NewPaymentController(signer Signer, httpClient HttpClient, projectId int) *PaymentController {
        return &PaymentController{
            signer:     signer,
            httpClient: httpClient,
            projectId:  projectId,
        }
    }
     
    // ProcessPayment processes the payment
    func (pc *PaymentController) ProcessPayment(paymentData PaymentData) {
        cardData := paymentData.GetCardData()
     
        paymentRequest := map[string]interface{}{
            "general": map[string]interface{}{
                "project_id": pc.projectId,
                "payment_id": paymentData.GetPaymentId(),
            },
            "customer": pc.prepareCustomerData(paymentData.GetCustomerData()),
            "payment": map[string]interface{}{
                "amount":   paymentData.GetAmount(),
                "currency": paymentData.GetCurrency(),
            },
            "card": map[string]interface{}{
                "pan":         cardData.GetPan(),
                "year":        cardData.GetYear(),
                "month":       cardData.GetMonth(),
                "card_holder": cardData.GetCardHolder(),
                "cvv":         cardData.GetCvv(),
            },
        }
     
        // Add signature
        general := paymentRequest["general"].(map[string]interface{})
        general["signature"] = pc.signer.Sign(paymentRequest)
     
        // Send request
        pc.httpClient.SendRequest(paymentRequest)
    }
     
    // prepareCustomerData filters and prepares customer data
    func (pc *PaymentController) prepareCustomerData(customerData CustomerData) map[string]interface{} {
        result := make(map[string]interface{})
     
        if v := customerData.GetIpAddress(); v != nil {
            result["ip_address"] = *v
        }
        if v := customerData.GetBrowser(); v != nil {
            result["browser"] = *v
        }
        if v := customerData.GetScreenRes(); v != nil {
            result["screen_res"] = *v
        }
        if v := customerData.GetLanguage(); v != nil {
            result["language"] = *v
        }
        if v := customerData.GetAcceptHeader(); v != nil {
            result["accept_header"] = *v
        }
        if v := customerData.GetAcceptLanguageHeader(); v != nil {
            result["accept_language_header"] = *v
        }
        if v := customerData.GetColorDepth(); v != nil {
            result["color_depth"] = *v
        }
        if v := customerData.GetJavaEnabled(); v != nil {
            result["java_enabled"] = *v
        }
        if v := customerData.GetJsEnabled(); v != nil {
            result["js_enabled"] = *v
        }
        if v := customerData.GetTimezoneOffset(); v != nil {
            result["timezone_offset"] = *v
        }
     
        return result
    }
    ```


**Note:** Note that the code samples presented above are for information purposes only and cannot be used as is without additional review and modification to comply with the relevant requirements of the web service, including [the PCI DSS compliance](en_faq_integration.md#fig_fgk_rgs_4nb).

## Payment request format {#en_gate_payment_3ds_formats_request}

### Overview {#section_s2w_md3_mxb .section}

The format of requests for processing payments that will require 3‑D Secure must correspond to the format described in [Interaction concepts](en_gate_interaction_organisation.md). At the same time, each request may require a different parameter set as follows:

-   Without exception, you must include the parameters that are required for the payment type to be initiated \(more information can be found in the articles about payment types\) and the parameters listed below as [required](en_gate_payment_3ds.md#section_zgh_4d3_mxb) for performing 3‑D Secure.
-   If the frictionless flow is preferred, you are recommended to specify as many optional parameters listed below as [possible](en_gate_payment_3ds.md#section_agb_wd3_mxb) for performing 3‑D Secure.
-   Additionally, you can use any other parameters out of the supported parameter set for the payment type to be initiated.

### Required parameters {#section_zgh_4d3_mxb .section}

In requests for processing payments that will be subject to 3‑D Secure, pass the required parameters for the specific payment type and additionally include the following required objects and parameters.

|Parameter|Description| |
|---------|-----------|--|
|`acs_return_url`  
 object

|Object that contains the web service URLs used for authentication.|1|
|`return_url`  
 string

|The URL to redirect the customer to the web service after authentication.|1-11|
|`3ds_notification_url`  
 string

|The URL the web service uses for accepting data receipt acknowledgement from ACS.|1-21|
|`customer`  
 object

|Object that contains customer data.|2|
|`ip_address`  
 string

|Customer's IP address.|2-12|
|`screen_res`  
 string

|Screen resolution of the customer's device, in pixels, with an `x` character as a delimiter \(for example, `1920x1080`\).|2-22|
|`email`  
 string

|Customer's email.|2-32|
|`phone`  
 string

|Customer's phone number, contains between 4 and 24 digits.|2-42|
|`card`  
 object

|Object that contains the customer's card details.|3|
|`card_holder`  
 string

|The name of the cardholder, spelled as specified on the card.|3-13|

``` {#codeblock_gmn_gbx_x3c .language-json}
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {   // information about the customer
      "ip_address": "248.121.176.220",   // IP address of the customer
      "id": "customer_12",
      "screen_res": "1920x1080",   // screen resolution of the customer's device
      "phone": "44991234567",   // customer's phone number
      "email": "john_smith@email.com"   // customer's email
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",   // name of the cardholder
      "cvv": "123"
  },
  "acs_return_url": {   // information about the web service URLs
    "return_url": "https://3DS_result_url",   // URL to redirect the customer to after authentication
    "3ds_notification_url": "https://3DS_result_url"   // URL for accepting receipt acknowledgement
  }

```

### Recommended parameters {#section_agb_wd3_mxb .section}

In requests for processing payments that will be subject to 3‑D Secure, you are recommended to specify parameters listed below because it can increase the possibility of frictionless flow selection that bypasses interaction with the customer and does not require the procedure of collecting additional data about the customer's device. The web service can pass all or some of the parameters, depending on the availability of specific data. The bare minimum of the parameters that affect the issuer's decision when selecting the 3‑D Secure flow includes the billing address of the customer and the customer's device and browser characteristics.

|Parameter|Description|tree|
|---------|-----------|----|
|`customer`  
 object

|Object that contains customer data.|2|
|`accept_header`  
 string

|Value of the HTTP Accept request header as received from the customer's browser.|2-12|
|`accept_language_header`  
 string

|Value of the Accept-Language HTTP header used in the requests sent from the customer's browser to the web service. It specifies the preferred languages of the browser and contains language codes and corresponding q-values that signify the order of preference \(for example, `en-GB,en;q=0.8,fr;q=0.3`\).|2-192|
|`browser`  
 string

|Value of the HTTP User-Agent request header as received from the customer's browser.|2-22|
|`color_depth`  
 integer

|The colour depth of the screen as supported by the customer's device, bits per pixel.|2-32|
|`java_enabled`  
 boolean

|Indicates whether the customer's browser supports Java.|2-42|
|`js_enabled`  
 boolean

|Indicates whether the customer's browser supports JavaScript.|2-52|
|`language`  
 string

|The code of the customer's browser language.|2-62|
|`timezone_name`  
 string

|The name of the time zone the customer's browser is set to \(for example, `Australia/Adelaide`\).|2-82|
|`timezone_offset`  
 string

|The difference between a date as evaluated in the UTC time zone and the same date as evaluated in the browser time zone, specified in minutes, \(for example, `570`\).|2-92|
|`address_match`  
 boolean

|Indicates whether the customer's billing address matches the address specified in the `shipping` object.

 Possible values:

-   `true`—addresses match
-   `false`—addresses do not match

|2-102|
|`home_phone`  
 string

|Customer's home phone number, contains between 4 and 24 digits \(for example, `44991234567`\).|2-112|
|`work_phone`  
 string

|Customer's work phone number, contains between 4 and 24 digits \(for example, `44997654321`\).|2-122|
|`account`  
 object

|Object with the customer's account information kept on file by the merchant.|2-132|
|`additional`  
 string

|Additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters.|2-13-12-13|
|`activity_day`  
 integer

|Number of payment attempts in the last 24 hours, 3 characters maximum \(`999`\).|2-13-22-13|
|`activity_year`  
 integer

|Number of payment attempts in the last 365 days, 3 characters maximum \(`999`\).|2-13-32-13|
|`age_indicator`  
 string

|Number of days since the customer account was created. Possible values:-   `01`—guest checkout
-   `02`—0 days \(the account was created at the moment of making a payment\)
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|2-13-42-13|
|`auth_data`  
 string

|Additional login information in free text, can contain up to 255 characters.|2-13-52-13|
|`auth_method`  
 string

|Indicates how the customer was authenticated during their most recent login to the web service. Possible values:-   `01`—no authentication
-   `02`—logging in with authentication data kept on file by the merchant
-   `03`—logging in with the federated identity credentials \(for example, Google Account or Facebook ID\)
-   `04`—logging in with the use of FIDO authenticator \(Fast Identity Online\)

|2-13-62-13|
|`auth_time`  
 string

|Date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format.|2-13-72-13|
|`date`  
 string

|Account creation date in the `DD-MM-YYYY` format.|2-13-82-13|
|`change_date`  
 string

|Date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format.|2-13-92-13|
|`change_indicator`  
 string

|Number of days since the most recent change to the account, except for the password change or password reset. Possible values:-   `01`—0 days \(the account was updated on the day when the payment was made\)
-   `02`—fewer than 30 days
-   `03`—between 30 and 60 days
-   `04`—more than 60 days

|2-13-102-13|
|`pass_change_date`  
 string

|Date of the most recent password change or reset in the `DD-MM-YYYY` format.|2-13-112-13|
|`pass_change_indicator`  
 string

|Number of days since the most recent password change or reset. Possible values:-   `01`—the password was not changed or reset
-   `02`—0 days \(the password was changed or reset on the day when the payment was made\)
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|2-13-122-13|
|`payment_age`  
 string

|Card record creation date in the `DD-MM-YYYY` format.|2-13-132-13|
|`payment_age_indicator`  
 string

|Number of days since the payment card details were saved to a customer's account. Possible values:-   `01`—guest checkout
-   `02`—0 days \(card details were saved on the day when the payment was made\)
-   `03`—fewer than 30 days
-   `04`—between 30 and 60 days
-   `05`—more than 60 days

|2-13-142-13|
|`provision_attempts`  
 integer

|Number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum \(`999`\).|2-13-152-13|
|`purchase_number`  
 integer

|Number of purchases made via the customer's account in the last 6 months, 4 characters maximum \(`9999`\).|2-13-162-13|
|`suspicious_activity`  
 string

|Indicates the presence of suspicious activity. Possible values:-   `01`—no suspicious activity detected
-   `02`—suspicious activity detected

|2-13-172-13|
|`billing`  
 object

|Object with information about the customer's billing address.|2-162|
|`address`  
 string

|Street of the customer's billing address.|2-16-12-16|
|`city`  
 string

|City of the customer's billing address.|2-16-22-16|
|`country`  
 string

|Country of the customer's billing address in the ISO 3166-1 alpha-2 format.|2-16-32-16|
|`postal`  
 string

|Postal code of the customer's billing address.|2-16-42-16|
|`region_code`  
 string

|State, province, or region code in the ISO 3166-2 format, for example, `DEV` for Devon.If you specify this parameter, you also need to specify and populate the `billing_country` parameter.

|2-16-52-16|
|`shipping`  
 object

|Object with shipping details.|2-172|
|`address`  
 string

|Shipping address, can contain up to 150 characters.|2-17-12-17|
|`address_usage`  
 string

|Date when the specified shipping address was used for the first time, in the `DD-MM-YYYY` format.|2-17-22-17|
|`address_usage_indicator`  
 string

|Number of days since the specified shipping address was used for the first time. Possible values:-   `01`—first-time use
-   `02`—fewer than 30 days
-   `03`—between 30 and 60 days
-   `04`—more than 60 days

|2-17-32-17|
|`city`  
 string

|Shipping city, can contain up to 50 characters.|2-17-42-17|
|`country`  
 string

|Shipping country code in the ISO 3166-1 alpha-2 format \(for example, [GB](references/en/countries/GB.md)\).|2-17-52-17|
|`delivery_email`  
 string

|The email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters.|2-17-62-17|
|`delivery_time`  
 string

|Delivery time. Possible values:-   `01`—digital same day delivery
-   `02`—same day delivery
-   `03`—next day delivery
-   `04`—delivery more than one day after the purchase was made

|2-17-72-17|
|`name_indicator`  
 string

|Indicates whether the customer's name matches the recipient's name. Possible values:-   `01`—names match
-   `02`—names do not match

|2-17-82-17|
|`postal`  
 string

|Shipping postal code, can contain up to 16 characters.|2-17-92-17|
|`region_code`  
 string

|State, province, or region code in the ISO 3166-2 format, for example, `DOR` for Dorset.If you specify this parameter, you also need to specify and populate the `country` parameter in the `shipping` object.

|2-17-102-17|
|`type`  
 string

|Delivery option selected by the customer. Possible values:-   `01`—delivery to the cardholder's billing address
-   `02`—delivery to a different verified address
-   `03`—delivery to the address that is not verified and does not match the billing address
-   `04`—store delivery
-   `05`—digital delivery
-   `06`—no delivery needed \(for example, event ticket purchase\)
-   `07`—other

|2-17-112-17|
|`mpi_result`  
 object

|Object that contains information about the previous authentication attempt of the customer.|2-182|
|`acs_operation_id`  
 string

|The identifier that the issuer assigned to the previous operation of the customer and returned in the `acs_operation_id` parameter of the callback with payment processing result. Can contain up to 36 characters.|2-18-12-18|
|`authentication_flow`  
 string

|The flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the `authentication_flow` parameter returned in the callback with payment processing result.

 Possible values:

 -   `01`—frictionless flow
-   `02`—challenge flow

|2-18-22-18|
|`authentication_timestamp`  
 string

|Date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result.|2-18-32-18|
|`payment`  
 object

|Object with payment information.|3|
|`challenge_indicator`  
 string

|Indicates whether the challenge flow is preferred. Possible values:-   `01`—no preferences
-   `02`—not using the challenge flow is preferred
-   `03`—using the challenge flow is preferred
-   `04`—using the challenge flow is required
-   `05`—do not use the challenge flow, the merchant has performed the risk analysis
-   `06`—do not use the challenge flow, use the Data Only flow
-   `07`—do not use the challenge flow, Strong Customer Authentication has been applied otherwise
-   `08`—do not use the challenge flow, the merchant is included in cardholder's trusted beneficiaries list
-   `09`—using the challenge flow is required, prompt the cardholder to add the merchant to the trusted beneficiaries list

|3-13|
|`challenge_window`  
 string

|The dimensions of a window in which the authentication page opens. Possible values:-   `01`—250 x 400 px
-   `02`—390 x 400 px
-   `03`—500 x 600 px
-   `04`—600 x 400 px
-   `05`—full screen

|3-23|
|`preorder_date`  
 string

|The date the preordered merchandise or service will be available in the `DD-MM-YYYY` format.|3-33|
|`preorder_purchase`  
 string

|Indicates whether the purchase is a preorder. Possible values:-   `01`—not a preorder
-   `02`—a preorder

|3-43|
|`reorder`  
 string

|Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:-   `01`—first-time purchase
-   `02`—repeat purchase

|3-53|
|`gift_card`  
 object

|Object with information about a purchase made with a prepaid or gift card.|3-63|
|`amount`  
 integer

|The amount of the purchase made with a prepaid or gift card in the smallest units of currency.|3-6-13-6|
|`currency`  
 string

|Currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format \(for example, [GBP](references/en/currencies/GBP.md)\).|3-6-23-6|
|`count`  
 integer

|Number of prepaid or gift cards used for making the purchase.|3-6-33-6|

## Format of intermediate messages {#en_gate_payment_3ds_formats_messages}

### Callback format when collecting additional data is needed {#section_jnw_q24_cjb .section}

When the issuer requires collecting additional data about the customer's device, you need to accept an intermediate callback from the payment platform and use the data included in the `iframe` object of the `threeds2` object to generate an iframe element on the page of the web service. Such callbacks are arranged in a standard format \([details](en_platform_callbacks.md)\), while the `iframe` object contains the data to be used as follows: specify the value of the `url` parameter from the iframe data as the value of the `action` attribute and specify the values of other parameters inside the corresponding `input` tags of the iframe code.

``` {#codeblock_uxh_lgl_njc .language-json}
{ 
  "threeds2":{ 
    "iframe":{ 
      "url":"https://example.com",
      "params":{
        "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
        "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
      }
    }
  }
}
```

``` {#codeblock_vxh_lgl_njc .language-xml}
<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="width: 1px; height: 1px; 
display: none;" src="javascript:false;" xmlns="http://example.com/xhtml"> <!--.--> </iframe>
<form id="tdsMmethodForm" name="tdsMmethodForm" action="https://example.com" method="post" 
target="tdsMmethodTgtFrame" xmlns="http://example.com/xhtml">
    <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ"
    />
    <input type="hidden" name="threeDSMethodData" value="eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
    />
</form>
<script type="text/javascript" xmlns="http://example.com/xhtml">
    document.getElementById("tdsMmethodForm").submit();
</script>
```

### Format of the message acknowledging receipt of additional data {#section_d4n_vky_svb .section}

Messages that acknowledge receipt of additional data about the customer's device are arranged in the format chosen by the issuer. The issuer's Access Control Server sends a message with an acknowledgement to the web service URL provided in the initial payment request \(in the `3ds_notification_url` parameter\). If you have questions about working with these messages, refer to the Ecommpay technical support.

``` {#codeblock_dhp_jbs_y3c .language-xml}
threeDSMethodData:eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImRiNmFjM2UwLWI5ZWQtNWQ3NS04MDAwLTAwMDAwMDAwMTA0MiJ9
threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455
```

### Format of the authentication initiation request {#section_o1k_yky_svb .section}

To initiate the authentication, if it is necessary after collecting the customer's device characteristics, send a HTTP POST request to the [/v2/payment/card/3ds\_check\_iframe](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-check-iframe) endpoint. The request must contain the following objects and parameters:

-   `general`—the object containing the general identification information of the request:
    -   `project_id`—the project identifier.
    -   `payment_id`—the payment identifier.
    -   `signature`—the request signature generated after all required parameters have been specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
-   `threeds_completion_indicator`—the parameter that indicates whether [the message acknowledging the receipt of data](en_gate_payment_3ds.md#section_d4n_vky_svb) was received within 10 seconds after the iframe element was opened. If the acknowledgement was received within 10 seconds, pass `true`; if not, pass `false`.

Thus, a correct request for the 3‑D Secure authentication initiation contains a project identifier, a payment identifier, an indicator of timely receipt of the acknowledgement message, and a signature.

``` {#codeblock_wgr_nxr_y3c .language-json}
{ 
  "general":{ 
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "threeds_completion_indicator":true
}
```

### Callback format when redirection is needed {#section_drq_xq1_1jb .section}

To redirect the customer from your web service to the ACS URL, you need to accept an intermediate callback from the payment platform and use the data included in the `redirect` object of the `threeds2` object. Such callbacks are arranged in a standard format \([details](en_platform_callbacks.md)\), while the `redirect` object contains the data to be used as follows: specify the value of the `url` parameter as the value of the `action` attribute and specify the values of other parameters inside the corresponding `input` tags of the HTML code.

``` {#codeblock_wxh_lgl_njc .language-json}
{ 
  "threeds2":{ 
    "redirect":{ 
      "url":"https://example.com/ACS",
      "params":{
        "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
        "threeDSSessionData":"240000549"
      }
    }
  }
}
```

``` {#codeblock_xxh_lgl_njc .language-xml}
<!DOCTYPE html SYSTEM "about:legacy-compat">
<html class="no-js" lang="en" xmlns="http://example.com/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta charset="utf-8" />
    <title>3D Secure Processing</title>
    <link href="https://example.com/mpi.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div id="main">
      <div id="content">
        <div id="order">
          <h2>3D Secure Processing</h2>
          <img src="https://example.com/preloader.gif" alt="Please wait.." /> <img src="https://
example.com/verifiedbyvisa.png" alt="Verified by VISA" />
          <div id="formdiv">
            <script type="text/javascript">
              function hideAndSubmitTimed(formid) { timer=setTimeout("hideAndSubmit('"+formid+"');",
100);} function hideAndSubmit(formid) { var formx=document.getElementById(formid); tif (formx!=null)
{ formx.style.visibility="hidden"; formx.submit(); } }
            </script>
            <div>
              <form id="webform0" name="red2ACSv2" method="POST" action="https://
example.com/ACS" accept_charset="UTF-8"> 
<input type="hidden" name="_charset_" value="UTF-8" /> 
<input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9" /> 
<input type="hidden" name="threeDSSessionData" value="240000476" /> 
<input type="submit" name="submitBtn" value="Please click here to continue" /> 
              </form>
            </div>
          </div>
          <script type="text/javascript">
           thideAndSubmitTimed('webform0');
          </script>
          <noscript>
            <div align="center"> <b>Javascript is turned off or not supported!</b> <br/> </div>
          </noscript>
        </div>
      </div>
    </div>
  </body>
</html>
```

### Format of the message with the authentication result {#section_cjg_rss_njb .section}

Messages with authentication results are arranged in the format chosen by the issuer. They should contain the `cres` parameter that then is passed to the platform from the web service in the payment completion requests.

``` {#codeblock_yxh_lgl_njc}
**cres**=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554
```

``` {#codeblock_zxh_lgl_njc}
**cres**=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&threeDSSessionData=240000622
```

### Format of the payment completion request {#section_gps_1fc_t3b .section}

To resume processing of the payment, once the challenge flow has been completed, send a request to the [/v2/payment/card/3ds\_result](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-result) endpoint using the POST HTTP method. The request must contain the following objects and parameters:

-   `general`—the object containing the general identification information of the request:
    -   `project_id`—the project identifier.
    -   `payment_id`—the payment identifier.
    -   `signature`—the request signature generated after all required parameters have been specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
-   `cres`—the parameter containing the customer's 3‑D Secure authentication result sent [in the message from the Access Control Server](en_gate_payment_3ds.md#section_cjg_rss_njb).

Thus, a correct request for payment completion following the 3‑D Secure authentication contains project and payment identifiers, the signature, and the authentication result.

``` {#codeblock_ayh_lgl_njc .language-json}
{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"  // Authentication result data
}
```

## Format of callbacks with payment results {#en_gate_payment_3ds_formats_callback}

To communicate the result of the payment that involved the 3‑D Secure authentication, the payment platform sends a callback to the web service. The callback is arranged in a standard format described in [Handling callbacks](en_platform_callbacks.md) and contains the `mpi_result` object with the following parameters:

-   `mpi_operation_id`—operation identifier on the 3DS Server side
-   `ds_operation_id`—operation identifier on the Directory Server side of the global card network
-   `acs_operation_id`—operation identifier on the issuer's Access Control Server side
-   `mpi_timestamp`—authentication time and date
-   `cardholder_info`—the message you are recommended to display when notifying the customer about the payment result
-   `authentication_flow`—authentication flow indicator: `01` for the frictionless flow, `02` for the challenge flow.

If the authentication was not performed due to [an applied exemption](en_gate_payment_3ds.md#section_fmt_mxl_ndc), the `operation` object of the callback can also contain the `non_3ds_reason` parameter with the value `tra, lve` \(for low risk or low value payments\).

These parameters are not passed by default. To add them to the callbacks you receive, contact the Ecommpay technical support.

```language-json
{  
  "account":{  
    "number":"431422******0056",
    "token":"f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{  
    "id":"customer_12",
    "phone":"44991234567"
  },
  "payment":{  
    "date":"2019-01-11T13:02:42+0000",
    "id":"456789",
    "method":"card",
    "status":"success",
    "sum":{  
      "amount":400000,
      "currency":"USD"
    },
    "type":"purchase",
    "description":""
  },
  "project_id":42,
  "operation":{  
    "id":969000002636,
    "type":"sale",
    "status":"success",
    "date":"2019-01-11T13:02:42+0000",
    "created_date":"2019-01-11T13:01:45+0000",
    "request_id":"c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
    "sum_initial":{  
      "amount":400000,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400000,
      "currency":"USD"
    },
    "provider":{  
      "id":408,
      "payment_id":"330157196",
      "date":"2019-01-11T13:02:32+0000",
      "auth_code":"",
      "endpoint_id":"612266625"
    },
    "mpi_result":{
      "mpi_operation_id":"",
      // Operation identifier on the 3DS Server side
      "ds_operation_id":"",
      // Operation identifier on the Directory Server side of the global card network
      "acs_operation_id":"",
      // Operation identifier on the issuer's Access Control Server side
      "mpi_timestamp":"YYYYMMDDHHMM",
      // Authentication time and date
      "cardholder_info":"Additional authentication is needed for this transaction",
      // Information about authentication that you are recommended to display to the customer
      "authentication_flow":"02"
      // Authentication flow indicator
    },
    "code":"0",
    "message":"Success",
    "eci":"07"
  },
  "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```



---

# 3‑D Secure authentication on merchant side {#en_gate_merchant_3ds}

An article about an additional option of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Gate, performed through third-party solutions and initiated by the merchant.

## General information {#section_i3t_kkq_qmb .section}

Customer 3‑D Secure authentication can be performed either on the Ecommpay payment platform side or on the merchant side. If authentication is performed on the merchant's side, the authentication result must be sent to the payment platform in order to make a payment. Repeated authentication on the payment platform side will not occur.

To enable the capability, contact technical support \([support@ecommpay.com](mailto:support@ecommpay.com)\).

## Sending the 3‑D Secure authentication result {#section_vfr_mkq_qmb .section}

Information about the 3‑D Secure authentication result is passed in the `authentication_data` object in a request for performing a one-time purchase, including purchases that use a token or saved card data, or a request for card verification. Data is passed in the following parameters:

|Parameter|Type|Mandatory|Description|
|---------|----|---------|-----------|
|`cavv`|string|Mandatory if `authentication_status=Y or A`|Cardholder authentication verification value \(base64 encoded, 20 bytes in a decoded form\)|
|`ds_operation_id`|string|Mandatory if `threeds_version=3ds_2`|The unique operation identifier assigned by the Directory Servers|
|`eci`|string|Mandatory if `authentication_status=Y or A`|The electronic commerce indicator, for more information, see the section [Electronic Commerce Indicators](en_ECI_codes.md)|
|`threeds_version`|string|Optional|Indicator of the 3‑D Secure authentication:-   `3ds_2`
-   `non_3ds`

|
|`threeds_full_version`|string|Optional|The version of the 3‑D Secure protocol, for example 2.3.1|
|`xid`|string|Mandatory|Transaction identifier resulting from authentication processing \(base64 encoded, 20 bytes in a decoded form\)|
|`authentication_status`|string|Mandatory, except if `enrollement_status=N or U`|Cardholder authentication status. Possible values are:

 -   `Y`—the cardholder was successfully authenticated by their card issuer
-   `A`—the cardholder authentication was attempted
-   `U`—the card issuer was unavailable during the authentication attempt

|
|`authentication_status_reason_code`|string|Optional|Code of the authentication status reason|
|`authentication_flow`|string|Optional|Scenario of 3‑D Secure authentication-   `Frictionless`,
-   `Challenge`

|

```
{
   "general":{
      "project_id":200,
      "payment_id":"id_15514400636",
      "signature":"PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQ...=="
   },
   "card":{
      "pan":"some_string",
      "year":2025,
      "month":12,
      "card_holder":"JOHN JOHNSON",
      "cvv":"some_string"
   },
   "customer":{
      "id":"123",
      "ip_address":"217.1.1.0"
   },
   "payment":{
      "amount":1000,
      "currency":"EUR"
   },
   "authentication_data":{
      "cavv":"kEMQyiH/ASySYhP1hAErbWFO+mih",
      "ds_operation_id":"f780a79f-a5e1-44d8-bfa3-5f89432fdb79",
      "eci":"06",
      "threeds_version":"3ds_2",
      "xid":"MDAwMDAwNzYxODEwMDAwMDE3MDE=",
      "authentication_status":"A",
      "authentication_flow":"Frictionless",
      "threeds_full_version":"2.3.1",
      "authentication_status_reason_code":"01"
   }
}
```

## Related topics {#section_xsx_3jl_ggb .section}

The following topics can be useful when implementing payments through Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)
-   [Signature generation and verification](en_platform_signature.md)
-   [Payment processing](en_platform_payment_model.md)
-   [Handling operation processing information](en_platform_payment_info_codes.md)
-   [3‑D Secure authentication](en_gate_payment_3ds.md)

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)



---

# Authentication on merchant's request {#en_gate_payment_merch_auth}

An article about the procedure of authenticating customers upon merchant's request that can be used as an alternative to the 3‑D Secure authentication for processing card payments via Gate.

## General information {#section_zq3_2q2_zhb .section}

Customer authentication performed by the provider on merchant's request is intended to provide additional security for online payments by payment cards. Such authentication is usually used as a replacement for 3‑D Secure in addition to it. This can be appropriate when the 3‑D Secure authentication is not reliable enough, e.g. when issuers use outdated ways of authentication. Customer authentication on merchant's request implies submitting the validation code, which is contained in the information about the debiting of customer funds. The information is received by the customer in a SMS or a bank statement.

The payment platform supports authentication on merchant's request only for some providers, to enable this authentication a merchant project has to be configured. To do this, contact Ecommpay technical support at [support@ecommpay.com](mailto:support@ecommpay.com).

When performing a customer authentication by the payment system on merchant's request, the merchant web service is required to do the following:

-   receive a callback from the payment platform containing the information about the change of payment status to `awaiting merchant auth`.
-   obtain user consent.
-   send the authentication request.
-   receive the validation code from the customer.
-   send the request containing the validation code to the payment platform.

Detailed information on authentication on merchant's request is provided in the sections that follow.

## Workflow {#section_pjt_5jb_v3b .section}

Authentication on merchant's request is possible when performing one-step and two-step purchases by payment cards. *Information* about the necessity of such authentication is contained in callbacks. As a general rule, after receiving a callback a response must be sent to the payment platform. Callbacks contain information about the change of payment status to `awaiting merchant auth`.

The following scenario must be implemented on the web service side in order to successfully *react* to such callbacks: the web service must *obtain* the customer's consent to the authentication, *send* the authentication request to the payment platform, *receive* the validation code from the customer, *send* the request containing code to the payment platform to continue payment processing.

The time-out value for this request is unlimited, taking into account the results of authentication. The overall time of payment processing may not exceed the maximum allowed amount, which is set on the provider's side. If the payment is not successful or declined during this time, it automatically assumes the `decline` status.

After the payment platform receives the request containing the validation code, the payment processing continues.

![](images/en_gate_scheme_merchant_auth.svg)

1.  The payment is processed in the payment platform.
2.  The payment platform sends the callback to the web service informing about the necessity of authentication.
3.  The customer is redirected to the web page containing the information on the authentication.
4.  The user agrees to the authentication.
5.  The web service sends the request for authentication initiation to the specified Ecommpay URL.
6.  The payment platform receives the request.
7.  The payment platform processes the request.
8.  The payment platform sends the response with request receipt confirmation and correctness check result to the web service.
9.  The payment platform sends the request for authentication initiation request to the provider service.
10. The provider processes the request and sends the validation code to the customer.
11. The customer enters the validation code.
12. The web service sends the request for authentication completion and continuation of payment processing to the specified Ecommpay URL.
13. The payment platform receives the request.
14. The payment platform processes the request.
15. The payment platform sends the response with request receipt confirmation and correctness check result to the web service.
16. The web service sends the request for authentication completion and continuation of payment processing to the provider service.

The sections that follow discuss in more details the request and callback formats. For general information on how to use the API, see [Interaction concepts](en_gate_interaction_organisation.md).

## Format of callback informing about the necessity of authentication {#section_gzw_wbd_w3b .section}

The information about the necessity of authentication is contained in a callback, which uses a standard format. For more results, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback, with information about the payment and operation assuming the `awaiting merchant auth` status before the payment processing request is received.

```language-json
{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"purchase",
    "status":"awaiting merchant auth", // Payment status
    "date":"2019-02-20T15:33:11+0000",
    "method":"card",
    "sum":{  
      "amount":400000,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{  
    "id":"customer_12"
  },
  "operation":{  
    "id":171200003265,
    "type":"sale",
    "status":"awaiting merchant auth", // Operation status
    "date":"2019-02-20T15:33:11+0000",
    "created_date":"2019-02-20T15:33:02+0000",
    "request_id":"617c2626f873151a1cf5873ceb7cca0ade292ee-646d...ec",
    "sum_initial":{  
      "amount":400000,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400000,
      "currency":"USD"
    },
    "provider":{  
      "id":4,
      "payment_id":"3301571985",
      "auth_code":"",
      "endpoint_id":4
    },
    "code":"9999",
    "message":"Awaiting processing",
    "eci":"06"
  },
  "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

## Format of request for authentication initiation {#section_r2m_h52_zhb .section}

To initiate an authentication on merchant's request a request must by sent to the payment platform by using the POST \(HTTP\) request to the following endpoint [/v2/payment/card/merchant\_auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-merchant-auth). This request must include the `general` object, containing general request identification information and request type indicator:

-   `project_id`—the project ID obtained from Ecommpay
-   `payment_id`—payment ID unique within the project
-   `type`—indicator of request type, must have the `start` value
-   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)

Thus a correct request must include the project and payment IDs, indicator of request type \(`start`\) and signature.

```language-json
{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}
```

## Format of request for continuation of payment processing {#section_mm2_xv1_v3b .section}

Taking into account the result of authentication, to continue payment processing a request using the POST \(HTTP\) method must be sent to the endpoint [/v2/payment/card/merchant\_auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-merchant-auth). The request must contain the following objects and parameters:

1.  Object `general`—general request identification information:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID unique within the project
    -   `type`—indicator of request type, must have the `finish` value
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
2.  `confirmation_code`—validation code received from the customer.

Thus a correct request must include the project and payment IDs, indicator of request type \(`finish`\), signature and validation code.

```language-json
{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "confirmation_code": "835"
}
```

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)



---

# Using the Address Verification Service {#en_Gate_avs .concept}

An article about the procedure of verifying customers' postal codes and addresses for processing American Express, Mastercard, and Visa payments via Gate.

Address Verification Service \(AVS\) is a service that allows you to check whether a customer who makes a payment by a bank card is the actual cardholder. The AVS check is performed by matching the address specified by a customer while performing a payment with the cardholder address according to the bank card Issuer.

AVS verification is mandatory for payments with Visa and Mastercard cards performed in the UK, and optional in the USA, Australia, Canada and New Zealand. For American Express, AVS verification is mandatory in the USA and Canada and optional in other countries.Therefore, you may be required to add more mandatory parameters in the request for payment: customer postal code in the `avs_post_code` parameter and customer address in `avs_street_address`. You can submit these parameters in a additional parameters request. For more information, see [Submission of additional payment information](en_Gate_Clarification.md). If the data is missing, fails to pass the validation or is empty, you will receive a message with the corresponding decline code. The result of the AVS verification is passed in the `avs_result` callback parameter.

There are two schemes of work with AVS: sending the AVS parameters in each payment request or sending the AVS parameters in a clarification request, if AVS is enabled for the country of the card Issuer in the project settings.

**Note:** The requirement to provide AVS parameters persists even if the payment is made by a token or a saved bank card.

## Results of checking with AVS {#section_gq3_n12_pfb .section}

Below is a table of possible codes that can be returned, with additional information and descriptions for them.

|Code|Value|Description|
|----|-----|-----------|
|W, Z|Partial match|Post code matches, but street address does not|
|A|Partial match|Street address matches, but post code does not|
|X, Y|Exact match|Address and post code match|
|N|No match|Street address and post code do not match|
|S, U|Address information unavailable.|Address information is unavailable for this account or an issuing bank does not support the AVS|
|R|System unavailable|System is unavailable at the moment, retry|

|VISA|A, N, R, U, Y, Z|
|MasterCard|A, N, R, S, U, W, X, Y, Z|
|American Express|A, N, R, S, U, Y, Z|

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)



---

# Using the Verification of Payee service {#en_verification_of_payee}

An article about the procedure of verifying customers' names when payouts to bank accounts using the SEPA payment scheme are initiated via Gate.

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)

## Overview {#en_verification_of_payee_overview}

In accordance with the European Union's [Instant Payments Regulation \(IPR\)](https://www.ecb.europa.eu/paym/retail/instant_payments/html/instant_payments_regulation.en.html), for bank transfers using the [SEPA](https://www.ecb.europa.eu/paym/retail/sepa/html/index.en.html) payment scheme in the Single Euro Payments Area \(SEPA\), the names of recipients must undergo the Verification of Payee check. This regulation applies to cases where the sender and recipient are registered in SEPA member countries. As part of this verification, the spelling of the recipient's name provided by the merchant must be compared with the spelling recorded by the bank for the owner of the specified account, and based on the result of this verification that the merchant must make the decision whether to transfer the funds.

When applied during payment processing via the payment platform, the Verification of Payee is carried out with the participation of the service provider and may be relevant for certain payment methods, such as [Payouts to bank accounts in the SEPA](pm_bankpayout_sepa.md). When using such methods, you can configure how verification results are processed: on the web service or payment platform side \(details below\), as well as the period during which verification status information is considered valid.During this period additional verifications for identical cases are not required \(operations regarding verified pairs of customers and accounts\). By default, this period is 10 days.

To set up the Verification of Payee procedure contact your Ecommpay account manager.Using this procedure does not affect the calculation of payment fees. If you have any questions about the Verification of Payee procedure regarding specific methods, please refer to the descriptions of these methods in this documentation or contact Ecommpay technical support specialists.

## Workflows {#en_verification_of_payee_workflow}

The merchant can select and use one of the available Verification of Payee workflows for each project.

-   Processing of verification results on the platform side can be organised by using one of the predefined algorithmsfor approving and declining operations based on the final verification status. This option requires the merchant to agree to a suitable algorithm and allows accounting for verification results via the analysis of final operation callbacks.
-   Processing of verification results on the web service side can be organised by using any algorithm\(taking into account not only the final status of each verification, but also, for example, the amount of the initiated operation and the history of interactions with a specific customer\). This option requires the merchant to configure and implement the appropriate algorithms, as well as to organise additional interactions between the web service and the platform for each operation including the verification procedure.

To enable each of the workflows, as well as to switch between them, contact your Ecommpay account manager.The setup procedure for each workflow is described in more detail below, in the relevant sections of this article.

## Setup {#en_verification_of_payee_enable}

To have the Verification of Payee procedure set up, merchants should complete the following steps:

1.  Coordinate the process with your Ecommpay account manager: discuss the setup procedure and the relevant workflow, as well as the need to change the validity period of the verification results \(by default, it is 10 days\) and whether it is necessary to test the procedure.
2.  If it was agreed that testing is required, wait to be notified by the Ecommpay specialists when the testing can begin. After that, inform the account manager that you are ready to launch the procedure in your production environment.
3.  Receive the notification from the Ecommpay specialists about the completion of the procedure setup.

## Statuses {#en_verification_of_payee_statuses}

When you use the Ecommpay payment platform, the final status of each Verification of Payee check is indicated by one of the following statuses:

-   `MATCH`—indicates a full spelling match between therecipient's name specified in the request and the name recorded by the bank for the owner of the specified account.
-   `CLOSE_MATCH`—indicates a partial spelling match between therecipient's name specified in the request and the name recorded by the bank for the owner of the specified account.
-   `NO_MATCH`—indicates a complete spelling mismatch between therecipient's name specified in the request and the name recorded by the bank for the owner of the specified account.
-   `VERIFICATION_NOT_POSSIBLE`—indicates the impossibility of verification due to errors on the service provider side.
-   `VOP_ERROR`—indicates the impossibility of verification due to errors in the interaction between the platform and the provider service.

The interpretation of full and partial matches, as well as complete mismatches in name spellings, is applied in accordance with the IPR. It should also be noted that many banks tend to reject operations set to the `VERIFICATION_NOT_POSSIBLE` verification status, even if such operations can be processed on the platform side and their risk level is low based on other criteria.

## Processing on the platform side {#en_verification_of_payee_platform}

### Algorithms {#section_xkv_bhf_w3c .section}

When processing the Verification of Payee verification results on the Ecommpay payment platform side, it is permissible to select and use one of the following operation approval algorithms \(with subsequent processing after the final verification status is set and matches one of the approved ones\).

-   Algorithm 1 is based on the following rules:
    -   `MATCH` status indicates that the corresponding operation can be processed.
    -   `CLOSE_MATCH`, `NO_MATCH`, `VERIFICATION_NOT_POSSIBLE` and `VOP_ERROR` statuses indicate that the corresponding operation cannot be processed.
-   Algorithm 2 is based on the following rules:
    -   `MATCH` and `CLOSE_MATCH` statuses indicate that the corresponding operation can be processed.
    -   `NO_MATCH`, `VERIFICATION_NOT_POSSIBLE` and `VOP_ERROR` statuses indicate that the corresponding operation cannot be processed.
-   Algorithm 3 is based on the following rules:
    -   `MATCH`, `CLOSE_MATCH` and `VERIFICATION_NOT_POSSIBLE` statuses indicate that the corresponding operation can be processed.
    -   `NO_MATCH` and `VOP_ERROR` statuses indicate that the corresponding operation cannot be processed.
-   Algorithm 4 is based on the following rule: all statuses \(including the `NO_MATCH` status\) as well as statuses indicating the impossibility of verification indicate that the corresponding operation can be processed.

These rules can be briefly presented in the form of a table.

|Status|Approval algorithms|
|1|2|3|4|
|------|-------------------|
|--|--|--|--|
|`MATCH`|+|+|+|+|
|`CLOSE_MATCH`|–|+|+|+|
|`NO_MATCH`|–|–|–|+|
|`VERIFICATION_NOT_POSSIBLE`|–|–|+|+|
|`VOP_ERROR`|–|–|–|+|

### Result monitoring {#section_qb4_bhf_w3c .section}

Information about the Verification of Payee result for any operation within this workflow can be obtained via a final callback containing information about the operation completion. Callbacks in such cases use a standard format, described in the article [Handling callbacks](en_platform_callbacks.md). Information about the final status of this verification is specified in the parameters of the `provider_extra_fields` object. In cases where operations are declined, you can additionally rely on the final response codes for verification information, such as these:

-   `20450`—when an operation is declined due to a failed verification\(for the `VERIFICATION_NOT_POSSIBLE` status in algorithms 1–2 and the `VOP_ERROR` status in algorithms 1–3\).
-   `20451`—when an operation is declined due to the final verification status not matching the approved status\(for the `CLOSE_MATCH` status in algorithm 1 and the `NO_MATCH` status in algorithms 1–3\).

The following is an example of a callback with information about a `10.00 EUR` payout made in the `239` project. The `vop_status` parameter of the `provider_extra_fields` object included in this callback indicates the `CLOSE_MATCH` status of the verification.

``` {#codeblock_jvs_lwq_q3c .language-json}
{
        "provider_extra_fields": {
            "customer_name": "John Smit",
            "operation_id_in_ps": "TX55DE3DEFC161XT",
            "vop_status": "CLOSE_MATCH",
            "vop_message": "Reasons: NAME_MISMATCH; Details: The account details are a close match.; Matched: name: JOHN SMITH"
        },
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "LV35HA******6833"
        },
        "project_id": 239,
        "payment": {
            "id": "Test payment 02042026-111",
            "type": "payout",
            "status": "success",
            "date": "2026-04-02T11:12:47+0000",
            "method": "world",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "test payout"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16711,
                "payment_id": "P21132ZU06",
                "auth_code": "",
                "date": "2026-04-02T11:11:51+0000"
            },
            "id": 94413010223457,
            "type": "payout",
            "status": "success",
            "date": "2026-04-02T11:12:47+0000",
            "created_date": "2026-04-02T11:11:43+0000",
            "request_id": "7eee81073a807f30094414"
        },
        "signature": "<signature>"
    }
```

The following is an example of a callback with information about a payout declined due to complete mismatch of the names, which is indicated by the `NO_MATCH` status.

``` {#codeblock_vtb_nwq_q3c .language-json}
{
        "provider_extra_fields": {
            "vop_status": "NO_MATCH",
            "vop_message": "Reasons: NAME_MISMATCH, ACCOUNT_MISMATCH; Details: The account and name do not match."
        },
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "LV35HA******6833"
        },
        "project_id": 155543,
        "payment": {
            "id": "Test payment 02042026-115",
            "type": "payout",
            "status": "decline",
            "date": "2026-04-02T11:22:20+0000",
            "method": "world",
            "sum": {
                "amount": 1,
                "currency": "EUR"
            },
            "description": "test payout"
        },
        "operation": {
            "sum_initial": {
                "amount": 1,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "20451",
            "message": "Payout or refund cannot be processed based on the Verification of Payee result",
            "provider": {
                "id": 16711,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 43116010187149,
            "type": "payout",
            "status": "decline",
            "date": "2026-04-02T11:22:21+0000",
            "created_date": "2026-04-02T11:22:18+0000",
            "request_id": "21356"
        },
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    }
```

## Processing on the web service side {#en_verification_of_payee_webservice}

### Overview {#section_b3h_w55_s3c .section}

When processing Verification of Payee results on the web service side, additional interactions between the web service and the platform must be organized for each transaction involving the verification procedure. This involves a series of steps between accepting a customer request to receive funds and initiating the corresponding operation in the platform:

-   Send a Verification of Payee request\(with the required parameters and signature\) to the Ecommpay URL.
-   Receive a synchronous response from the payment platformcontaining the information about initiating the verification.
-   After at least 10 seconds, send a request to receive verification result information\(with the required parameters and signature\) to the Ecommpay URL.
-   Receive a synchronous response from the payment platformcontaining the information about the verification status.

After this process, in each case, a decision must be made on the web service side regarding the permissibility of the operation\(in accordance with the implemented internal algorithm\), and this operation must be initiated in the platform or the customer must be notified of the error.

The full sequence and special aspects of the Verification of Payee process are provided below.

![](images/en_vop_uml_gate.svg)

1.  A customer initiates a request for funds.
2.  The web service sends the request for Verification of Payee by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the Verification of Payee request.
4.  The payment platform processes the request, validates the required parameters and initiates the verification.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its processing, as well as the information about the initiation of the verification.
6.  The payment platform performs sends the verification request to the provider service.
7.  The Verification of Payee is performed on the provider service side.
8.  The provider service sends information about the verification result to the payment platform.
9.  Not less than 10 seconds after receiving the response containing the information about the verification initiation, the web service sends the request for the verification result information by using Gate to the specified Ecommpay URL.
10. The payment platform receives the verification information request.
11. The payment platform processes the request, validates the required parameters and searches for the requested information.
12. The payment platform sends the response to the web service with information about the receipt of the request and its validity, as well as the information about the status of the verification.
13. The web service processes the received information and performs the subsequent actions based on the verification status, informing the customer about the status of their request to receive funds.

Information about the formats of requests and responses used during this process is presented further in this section.

### Verification of Payee request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending Verification of Payee requests:

1.  To initiate each verification, send a separate POST request to the [/v2/verification-of-payee/create](https://api-developers.ecommpay.com/api-specification/verification-of-payee-service/post-v2-verification-of-payee-create) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `account`—customer account information:
        -   `customer_name`—full name or title of the account holder
        -   `number`—account number

``` {#codeblock_dxp_wqx_jfc .language-json}
{
  "general": {
    "project_id": 12345,
    "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "EUR"
  },
  "account": {
    "customer_name": "John Doe",
    "number": "DOMESTIC_ACC_NUMBER_12345678"
  }
}
```

### Verification of Payee initiation response format {#section_jvp_kv5_s3c .section}

A response to the Verification of Payee request is formatted according to the guidelines listed in [Interaction concepts](https://developers.ecommpay.com/en/en_gate_interaction_organisation.html#en_gate_interaction_organisation). Note that:

-   If the verification was initiated, the following parameters are included in the `vop` object:
    -   `id`—the verification identifierassigned on the provider side.
    -   `status`—the intermediate verification status, the value is `processing`.
-   If the verification was not initiated due to errors on the provider or platform side, the `vop` object is not included in the response.

``` {#codeblock_icd_1mb_g3c .language-json}
{
  "status": "success",
  "request_id": "3213123",
  "project_id": 12345,
  "vop": {
    "id": 777888,
    "status": "processing"
  }
}
```

### Request format for receiving verification information {#section_n53_zv5_s3c .section}

There are several things you need to consider when sending verification information requests:

1.  To request information on each verification, send a separate POST request to the [/v2/verification-of-payee/result](https://api-developers.ecommpay.com/api-specification/verification-of-payee-service/post-v2-verification-of-payee-result) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `vop`—Verification of Payee information:
        -   `id`—verification identifierobtained from Ecommpay in the verification initiation response

``` {#codeblock_oxy_ylz_r3c .language-json}
{
  "general": {
    "project_id": 12345,
    "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJb=="
  },
  "vop": {
    "id": 777888
  }
}
```

### Verification of Payee information response format {#section_qr1_lw5_s3c .section}

A response to the Verification of Payee information request is formatted according to the guidelines listed in [Interaction concepts](https://developers.ecommpay.com/en/en_gate_interaction_organisation.html#en_gate_interaction_organisation). Wherein, depending on the situation, the following parameters can be included in the `vop` object in such responses:

-   `id`—identifier of the required verification
-   `status`—a verification status indicator that can take one of the following values:
    -   `processing`—if the final verification status is not receivedfrom the service provider
    -   `completed`—if the final verification status is receivedfrom the service provider
    -   `decline`—if verification is impossibledue to errors in the interaction between the platform and the service provider
-   `result`—the final verification status \([details](en_verification_of_payee.md); not included in the response if the `status` parameter is `processing`\)
-   `details`—additional details to the final verification status from the service provider \(not included in the response if the `status` parameter is `processing` or if the result parameter is `VOP_ERROR`\)

In cases where the final status is `VOP_ERROR`, you are recommended to contact technical support specialists to clarify information about the verification and whether it can be performed.

``` {#codeblock_m4y_gzq_23c .language-json}
{
  "general": {
    "project_id": 12345,
    "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
  },
  "vop": {
    "id": 777888,
    "status": "completed",
    "result": "CLOSE_MATCH",
    "details": "Reasons: CLOSE_MATCH; Details: The account details match.; Matched: name: John Doe, accountType: personal account"
  }
}
```

## Useful links {#en_verification_of_payee_add_info}

The following articles can be useful when using Verification of Payee:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.



---

# Submission of additional payment information {#en_Gate_Clarification .concept}

An article about the procedure of specifying additional data that can be requested by payment systems during payment processing via Gate.

## Overview {#section_m3x_r1k_m3b .section}

Normally, when performing payment, mandatory parameters that are required to initiate the payment provide enough information. A payment system or the payment platform may require your web service to submit some optional parameters that otherwise are not required, this may be due to regional or country-specific requirements or additional fraud testing procedures. The additional payment information submission procedure implemented on the payment platform allows you to handle these cases. When performing the procedure, the payment platform require your web service to provide additional mandatory data and waits for the data to be submitted. Also, the payment platform is flexible as to the ways this additional information is requested and accepted from the web service.

Additional information the payment platform requests typically concerns the customer and the payment method. If the payment is performed by using payment cards, the payment platform may request the parameters of the `avs_data`—Address Verification Service requirements, [AVS](en_Gate_avs.md)—or any parameters of the `customer` objects.If the payment is performed by using alternative payment method, the payment platform may request any optional parameters of the initial payment request.

If you provide all the mandatory and optional parameters in each payment initiation request, you will never be required to submit additional information. Otherwise, you should implement the scenario in which during the payment processing, the payment platform requests additional information and you submit the information.

The following sections provides more details about the workflow.

## The workflow {#section_k4j_qjk_m3b .section}

The payment platform or provider, as well as a payment system may require additional payment information.

There are two ways the payment platform requests any additional information:*callbacks and responses*. Normally, the payment platform requests additional data in callbacks; in which case you are not required to issue any additional requests. Alternatively, you can issue a request for payment status and have the payment platform respond with a response that specifies what additional information is required.

Then, the web service needs to generate and send *the request* that contains additional information. After the payment platform discovers that additional information is required, it waits for submission of the additional information for 30 minutes. If the payment platform does not receive the request with the additional information within these 30 minutes, the payment is automatically declined. Although, your web service can resend the request with partial or even empty additional data, in this case, the 30-minutes time-out is reset. This way, you can prolong payment processing, if you need more time to collect all the additional data. Note though, that you can not prolong payment processing beyond the payment processing threshold.

*The parameter set* inside the request body may vary—you can specify all the parameters, part of the parameters, or no parameters at all, but you always must specify the `additional_data` object inside the request. If the request the payment system receives does not contain the object, the payment system considers the request incorrect and sends an error response. If the request contains all the required parameters, the payment platform responds with the `200 OK` response. If the request contains the `additional_data` object with no the required parameters or only a part of required parameters, the payment platform responds with a callback or a response that lists with the rest of the required parameters.

As soon as the payment platform obtains all the required information, the payment platform continues to process payment.

![](images/en_clarification_uml.svg)

During interaction with the payment platform, your web service is required to do the following:

1.  Receive a callback or a response with the `clarification_fields` object that lists the required parameters.
2.  Send the request that contains all the required objects and parameters including the `additional_data` object *and* signature to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint by using POST HTTP method.
3.  Receive and handle the `200 OK` response.

The payment platform responds with the `200 OK` response when payment platform receives all the required parameters with correct values. If not, the payment platform requests additional data again starting at *step 1*.

The information about the format of a callback and a response that may list with parameters and the request format are covered in greater details below.

## Callback and response format {#section_oyf_d4j_m3b .section}

There are two ways the payment platform requests any additional information: callbacks and responses to a request for payment status.

*The callbacks*that the payment platform sends to request additional payment information use the standard format described in [Handling callbacks](en_platform_callbacks.md). Note that in this case, the callbacks contain the `clarification_fields` object that lists with required parameters.The following is the example of the callback that is used to request the customer postal code and address that AVS requireswhen payment processing by using payment card.

```language-json
POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: example.com

{
    "sum_request": {
        "amount": 45000,
        "currency": "USD"
    },
    "request_id": "80bdc0831c3f8e1",
    
    "payment": {
        "id": "",
        "method": "card",
        "date": "2019-07-29T11:19:33+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "provider_id": 3
    },
    "sum_real": {
        "amount": 45000,
        "currency": "USD"
    },
    "status": "awaiting clarification",        // The payment status
    "customer": {
        "id": "4314220000000056"
    },
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "JUDY DOE",
        "expiry_month": "03",
        "expiry_year": "2021"
    },
    "clarification_fields": {                  // The additional information requested
        "avs_data": [
            "avs_post_code",
            "avs_street_address"
        ]
    },
    "general": {
        "project_id": 11,
        "payment_id": "EPr-bf14",
        "signature": "99q4lpCEuNpxp3ugvxF1qPbinWUIwNSLaxcVbF0A=="
    },
    "description": "",
    "operations": [
        {
            "id": 7282148104130,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T11:19:33+0000",
            "processing_time": null,
            "sum": {
                "amount": 45000,
                "currency": "USD"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ]
}
```

*The responses* that the payment platform sends to request additional payment information use the same format that the callbacks use.The following is the example of the response to the request that a merchant web service sends to the [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status) endpoint. The response is used to request the customer email, first and last name, billing address, and the day of birth.

```language-json
HTTP/1.1 200 OK                       
Server: api.com
Date: Wed, 29 July 2019 09:27:45 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 875
Connection: keep-alive
Keep-Alive: timeout=60
Cache-Control: no-cache
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Origin: *
X-Powered-By: PHP/7.0.32
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
    "sum_request": {
        "amount": 500,
        "currency": "CNY"
    },
    "request_id": "563c42d4846d105e77",
    "payment": {
        "method": "cup-card",           
        "date": "2019-07-29T09:27:45+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "status": "awaiting clarification",      // The payment status
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "id": "E2E_01_0868",
        "cascading_with_redirect": false,
        "provider_id": 1145
    },
    "sum_real": {
        "amount": 500,
        "currency": "CNY"
    },
    "customer": {
        "id": "7826"
    },
    "clarification_fields": {                     // The additional information requested
        "customer": [ 
            "email",
            "first_name",
            "last_name",
            "billing.address",
            "billing.city",
            "billing.country",
            "billing.postal",
            "day_of_birth"
        ]
    },
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "MYiga7aoW0UBFBfeTdIiF0QFOokEfyuSA=="
    },
    "description": "",
    "operations": [
        {
            "id": 1315207090506,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T09:27:45+0000",
            "processing_time": null,
            "request_id": "563c42d4846d105e77",
            "sum": {
                "amount": 500,
                "currency": "CNY"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ]
}
```

## Request format {#section_vgx_ww5_zgb .section}

Your web service needs to submit the requested additional payment information in a request to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint by using POST HTTP method. The request must contain the following:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project ID obtained from Ecommpay
    -   `payment_id`—payment ID unique within the project
    -   `signature`—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md).
-   `additional_data` — object that contains additional payment information that payment platform requests. The object may list all the parameters, part of the parameters, or no parameters at all.

    **Note:** The `interface_type` object is optional.


Thus, a correct request must include project and payment IDs, signature and additional payment information.In the following example, the requested additional information includes the customer postal code and address that the payment platform requests in the callback example above.

```language-json
{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "avs_data":{
        "avs_post_code": "99546",
        "avs_street_address": "01 Main Street, CA"
    }
  }
}
```

The following is the example that contains two request bodies. In this way, a merchant web service prolongs payment processing, when it needs more than 30 minutes to collect all the additional data. In the example, a merchant web service sends the first request with empty additional data just to prolong payment processing. Then, a merchant web service resends the request with all the requested additional data that includes the customer email address, first and last name, billing address and date of birth that the payment platform requests in the response example above.

```language-json
// The request body that the merchant web service sends
// to prolong the payment processing.
{
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "5uco0y4eeTdf59R/1SQXdfepidfw=="
    },
    "additional_data": {
    }
}

// The request body that the merchant web service sends
// to submit the additional information the payment system requests.

{    
    "general": {
        "project_id": 245,
        "payment_id": "E2E_01_0868",
        "signature": "5u5468co0fgfgfg/1fgfSfggdffg=="
    },
    "additional_data": {
        "customer": {
            "email": "test@testmail.com",
            "first_name": "杨",
            "last_name": "思荣",
            "billing": {
                 "address": "和飞机的事",
                 "city": "市区-东城区",
                 "country": "CN",
                 "postal": "156114"
            },
            "day_of_birth": "12-12-1990"
        }
    }
}
```

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)



---

# Currency conversion {#en_Gate_Conversion .concept}

An article about processing payments via Gate in different currencies with currency conversion.

## Overview {#section_g2z_3kl_bbb .section}

In general, a payment may involve three currencies: customer account currency, payment currency, and merchant account currency. If all three currencies are the same, there is no need for currency conversion; otherwise you need to convert the payment amount between currencies.

Suppose that the customer uses their dollar-denominated card to pay a certain amount in euros to the merchant whose account is denominated in pound. The payment amount is consecutively converted from dollars to euros and then from euros to pounds. The first conversion operation is performed by the issueror by the alternative payment system. The second conversion operation is performed by the Ecommpay payment platform.

You can also perform the conversion on your side and send the converted amount in the desired currency in the requests for operations performing.

For payments that use Gate, the Ecommpay payment platform offers *Automatic payment currency selection*: the customer cannot select payment currency while the exchange rate is dictated by the payment system.This option is available for payouts and one-time purchases by using all payment methods. Automatic payment currency selection uses exchange rates set by Ecommpay. To learn more about exchange rates, contact your account manager.

You can get the information about conversion operations performed by the payment platform from the callbacks with payment results, from Dashboard, or from regular reports sent to email addresses you specify. We recommend that you use this information for reconciliation with Ecommpay because issuersand alternative payment systems use the merchant account currency to keep record of the merchant transactions.

It should be also taken into account that the operation amount and the amount actually debited from the customer's account may not be the same, since currency exchange rates usually differ on the date when the payment was initiated and the date when the funds were actually debited. For conversion and compensation in such cases, the customer should contact the card issueror the organization where the account is opened.

To find out which payment methods in which currencies support conversion, please refer to the description of this method or to the Ecommpay key account manager.

## Setup {#section_u2c_qrk_kjb .section}

You do not need to update your web service to support automatic payment currency selection.

## Usage {#section_zh4_qrk_kjb .section}

Automatic payment currency selection does not require any additional efforts and is automatically performed during payment procedure.

Any conversion information is added in payment result callbacks into two objects embedded into the `operation` object: the `sum_initial` object contains the amount and the currency before conversion while the `sum_converted` object contains the amount and the currency after the conversion operation. For more information about these objects, see [Handling callbacks](en_platform_callbacks.md).

Below you will find the example of payment with a conversion operation in which `100 USD` are converted into `519,41 PHP` debited to merchant account denominated in Philippine peso.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines banks",
            "sum":{ 
              "amount":10000, // Initially requested amount
              "currency":"USD" // Initial requested currency
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount":10000, // Initially requested amount
                "currency":"USD" // Initially requested currency
            },
            "sum_converted": {
                "amount":519410, // Amount after conversion
                "currency":"PHP" // Automatically selected target currency
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}
```

**Parent topic:**[Auxiliary procedures](en_gate_procedures.md)



---

# Additional capabilities {#en_Gate_Additional_capabilities .concept}

Articles about additional capabilities of Gate for boosting payment acceptance rates, customer convenience, and the quality of the provided services.

This section provides the information about various capabilities that can be implemented upon the merchant request for improving the provided service.

## Monitoring payment processing {#section_cvs_fgd_stb .section}

The information about the capability of getting up-to-date information about particular payments processedvia the Gate API—[Checking current payment information](en_Gate_payment_status_request.md).

## Boosting payment acceptance rates {#section_frq_sfd_stb .section}

The information about the capabilities that can be used for ensuring high acceptance rates:

-   [Cascade payment processing](en_gate_cascading.md)—about the capability of making additional purchase processing attempts \(when relevant\).
-   [Processing purchases with partial authorisation](en_gate_partial_approval.md)—about the capability of processing purchases with the payment amount partially approved by the issuer.
-   [Checking payment method availability](en_gate_available_methods.md)—about the capability of getting payment method availability information for processing a payment.

## Using payment data {#section_zzs_ghd_stb .section}

The information about the capabilities of saving and using customer payment data, with the use of arbitrarily assigned identifiers \([Saving payment data](en_gate_saved_data.md)\) and standardised tokens \([Using tokens](en_Gate_Token.md)\), network tokens \([Using Mastercard and Visa network tokens](en_gate_tokens.md)\), and the information about the capability of migrating payment data to the platform \([Migrating information about COF purchases and payment card tokens](en_gate_data_migration.md)\).

## Supporting specific scenarios {#section_qbd_yhd_stb .section}

The information about the capabilities of using the Gate API in specific casesrelevant for different industries, types of business, and other situations:

-   [MO/TO payment processing](en_Gate_moto.md)—about the capability of processing purchases with the use of the customer's payment data received via email, phone, or other communication channels.
-   [Cardholder name verification](en_gate_cardholder_name_verification.md)—about the capability of matching the spelling of the cardholder's name against the one held by the card issuer.
-   [Using Mastercard MoneySend and Visa Direct services](en_gate_money_transfer_services.md)—about the capability of transferring funds between customers and merchants via the Mastercard MoneySend and Visa Direct services.
-   [Debt repayment](en_Gate_debt_repayments.md)—about the capability of processing payments for accepting loan and credit repayments.
-   [Using addendum with airline tickets data](en_gate_addendum.md)—about the capability of using the extended set of parameters \(*financial detail addendum*\) when processing air travel payments.
-   [Specifying extended purchase data for subsequent merchant use](en_gate_additional_data.md)—about the capability of passing relevant purchase information to be used by merchants at their discretion.

## Informing customers {#section_fqq_mmd_stb .section}


The information about the capabilities that can be used for informing customers:

-   [Using dynamic merchant descriptor](en_gate_descriptor.md)—about the capability of providing customers with information about merchants via issuer services.
-   [Sending notifications to customers](en_gate_receipts.md)—about the capability of informing customers about payment processing and related events via email notifications.

-   **[Checking current payment information](en_Gate_payment_status_request.md)**  
An article about the capability of obtaining via Gate up-to-date information about specific payments regardless of the interface that was used to initiate them.
-   **[Cascade payment processing](en_gate_cascading.md)**  
An article about the capability of making additional attempts to process a payment via Gate.
-   **[Checking payment method availability](en_gate_available_methods.md)**  
An article about the capability of obtaining via Gate payment method availability information for processing a specific payment.
-   **[Processing purchases with partial authorisation](en_gate_partial_approval.md)**  
An article about the capability of processing purchases via Gate with the payment amount partially approved by the issuer.
-   **[Saving payment data](en_gate_saved_data.md)**  
An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of arbitrarily assigned identifiers.
-   **[Using tokens](en_Gate_Token.md)**  
An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of standardized internal tokens.
-   **[Using Mastercard and Visa network tokens](en_gate_tokens.md)**  
An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of Mastercard and Visa network tokens.
-   **[Migrating information about COF purchases and payment card tokens](en_gate_data_migration.md)**  
An article about the capability of migrating information about recurring purchases and payment card tokens from other acquirers to the Ecommpay platform.
-   **[MO/TO payment processing](en_Gate_moto.md)**  
An article about the capability of processing via Gate purchases with the use of the customer's payment data received through email, phone, or other communication channels.
-   **[Cardholder name verification](en_gate_cardholder_name_verification.md)**  
An article about the capability of matching the spelling of the cardholder's name against the one held by the card issuer during payment processing via Gate.
-   **[Using Mastercard MoneySend and Visa Direct services](en_gate_money_transfer_services.md)**  
An article about the capability of transferring funds between customers and merchants via the Mastercard MoneySend and Visa Direct services.
-   **[Debt repayment](en_Gate_debt_repayments.md)**  
An article about the capability of processing loan repayments via Gate.
-   **[Using addendum with airline tickets data](en_gate_addendum.md)**  
An article about the capability of using the extended set of parameters \(financial detail addendum\) when processing air travel payments via Gate.
-   **[Specifying extended purchase data for subsequent merchant use](en_gate_additional_data.md)**  
An article about the capability of capturing relevant purchase information via Gate for internal merchant use.
-   **[Using optional parameters for payments processing](en_Gate_extra_params.md)**  
An article about the capability of using additional parameters that are relevant to merchants and cannot be found in the the Gate API.
-   **[Using dynamic merchant descriptor](en_gate_descriptor.md)**  
An article about the capability of providing customers with information about merchants via issuer services.
-   **[Sending notifications to customers](en_gate_receipts.md)**  
An article about the capability of informing customers about payment processing and related events via email notifications.

**Parent topic:**[Gate](en_Gate_Integration_About.md)



---

# Checking current payment information {#en_Gate_payment_status_request .concept}

An article about the capability of obtaining via Gate up-to-date information about specific payments regardless of the interface that was used to initiate them.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Overview {#en_gate_payment_status_request_overview}

While working with the Ecommpay payment platform, you can monitor up-to-date payment processing information using different capabilities \(to learn more, see a dedicated [overview](en_platform_payment_information_overview.md)\). Alongside other interfaces, specialised requests to the `payment/status` endpoint group of the Gate API can be used for this purpose. These requests allow you to promptly retrieve information about specific payments at the time that is relevant to the merchant's web service and can be deeply integrated into the service functionality.

To retrieve payment status information via the Gate API, two search options are available:

-   *Search by payment ID*. This is the primary option and it can be used at any time. The response content when using this option depends on whether the target payment has been registered in the platform.
    -   If the payment has been registered, the response to the payment status request contains up-to-date information about the payment.
    -   If the payment has not been registered \(for example, when Payment Page was opened and the customer closed it without confirming the payment\), the response to the payment status request contains information that the payment has not been registered.
-   *Search by request ID*. This is a supplementary option that, for correct information retrieval, should be used no earlier than 2 seconds after sending the request to process the target payment. Using this option can be relevant, for instance, when a payment request has not been accepted due to identified errors in the request format or content. In such cases, the response to the payment status request contains information about the errors that prevented the payment from being initiated.

**Note:** Generally, searching by request ID is not recommended as a replacement for the primary search by payment ID. Retrieving information about any payment after the request has been accepted is preferably done using the payment ID.

Regardless of the search option, all payment status requests are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each such request is fully processed within one HTTP session and uses only the resources of the payment platform. The response to the correct request contains an HTTP response status code \(`200`\) and the required data without detailed request processing information. If the request is incorrect, or there have been issues with its acceptance and processing, then the response contains an HTTP response status code, request processing status `error`, and the detailed description of the error that occurred. To learn more about HTTP response status codes, see [Interaction concepts](en_gate_interaction_organisation.md), and to learn more about the response codes that provide information on operation processing in the payment platform, see [Handling operation processing information](en_platform_payment_info_codes.md).

## Checking payment information by payment ID {#en_gate_payment_status_request_by_payment_id}

### Request format {#section_xxz_2nm_rkb .section}

A request to check payment status by payment ID is formatted according to the guidelines listed in [Interaction concepts](en_gate_interaction_organisation.md). It is sent to the endpoint [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status), and its body must contain a `general` object with the following identification information:

-   `project_id`—a project ID assigned by Ecommpay at the stage of integration;
-   `payment_id`—an ID of the payment to be monitored;
-   `signature`—a request signature generated after required parameters listed above have been specified. To learn more, see [Signature generation and verification](en_platform_signature.md).

```language-json

{
    "general":{
       "project_id":50,
       "payment_id":"ORDER_ID_302bis",
       "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}
```

### Response format {#section_ayz_2nm_rkb .section}

A response to the payment status request is formatted according to the guidelines listed in [Interaction concepts](en_gate_interaction_organisation.md). If the request has been successfully accepted and processed, the response header contains the status line indicating the protocol and its version \(`HTTP/1.1`\), the response status code and the explanatory phrase \(for instance, `200 OK`\). The body of such response contains the following data:

-   a project identifier and a signature;
-   information about the payment status and all operations initiated within this payment;
-   additional datathat can vary depending on the payment method used and can be customised for different payment methods with the assistance of the technical support specialists.

The basic set of parameters passed in the response to the payment status request is listed [in the Gate API specification](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status).

### Response examples {#section_n3y_r2w_jlb .section}

The following response contains information about a completed two-step purchase. It includes:

-   response status code indicating that the payment status request has been successfully processed \(`200`\);
-   status of the payment in question \(`success`\);
-   code of the payment method used \(`card`\);
-   information about the `auth` and `capture` operations contained in the `operations` array.

```language-json
HTTP/1.1 200 OK                                    //response status line
...                                                         //header fields 
{ 
  "project_id":50,
  "payment":{ 
    "id":"ORDER_ID_302bis",
    "type":"purchase",                                      //payment type
    "status":"success",                                     //payment status 
    "date":"2019-12-12T15:46:51+0000",
    "method":"card",                                        //payment method code
    "sum_real":{ 
      "amount":33,
      "currency":"USD"
    },
    "description":"Booking"
  },
  "customer":{ 
    "id":"6361696170"
  },
  "account":{ 
    "number":"4314220000000056",
    "type":"visa",
    "card_holder":"Michael Nurenberg",
    "expiry_month":"03",
    "expiry_year":"2024"
  },
  "operations":[ 
    { 
      "id":9435219675496,
      "type":"auth",                                         //operation type
      "status":"success",                                    //operation status
      "date":"2019-12-11T15:46:37+0000",
      "created_date":"2019-12-11T15:46:35+0000",
      "request_id":"bcRFZRJkmfcf-178c3d843c99-00009436",
      "sum":{ 
        "amount":33,
        "currency":"USD"
      },
      "code":"0",              //code specifying the status of the auth operation
      "message":"Success",                           //phrase explaining the code 
      "eci":"07",
      "provider":{ 
        "id":615,
        "payment_id":"2015611",
        "auth_code":"7213535217",
        "endpoint_id":615,
        "date":"2019-12-11T15:46:36+0000"
      },
      "operation_fee":{         //object with information about the operation fee
        "amount":31,
        "currency":"USD"
      }
    },
    { 
      "id":9435219671141,
      "type":"capture",                                         //operation type
      "status":"success",                                       //operation status
      "date":"2019-12-12T15:46:51+0000",
      "created_date":"2019-12-12T15:46:48+0000",
      "request_id":"2f114083cfb0f6d12c2-2ac890ebadb793-05015382",
      "code":"0",            //code specifying the status of the capture operation
      "message":"Success"                             //phrase explaining the code
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}
```

The following response contains information about a one-step purchase in progress which includes:

-   response status code indicating that the payment status request has been successfully processed \(`200`\);
-   status of the payment in question \(`awaiting redirect result`\);
-   code of the payment method used \(`Malaysian Banks`\);
-   information about the `sale` operation contained in the `operations` array

```language-json
HTTP/1.1 200 OK                                    //response status line
...                                                         //header fields
{ 
  "project_id":72,
  "payment":{ 
    "id":"ORDER_ID_tetan_M_2007_2012",
    "type":"purchase",                                      //payment type
    "status":"awaiting redirect result",                    //payment status
    "date":"2019-12-11T15:59:10+0000",
    "method":"Malaysian banks",                             //payment method code
    "sum":{ 
      "amount":25000,
      "currency":"MYR"
    },
    "description":"Book premium"
  },
  "customer":{ 
    "id":"Scott",
    "phone":"44177118324"
  },
  "operations":[ 
    { 
      "id":65747461,
      "type":"sale",                                          //operation type
      "status":"awaiting redirect result",                    //operation status
      "date":"2019-12-11T15:59:10+0000",
      "created_date":"2019-12-11T15:59:06+0000",
      "request_id":"97c7dd03080b4293603f28e64-0c415bc3e876c911f2d87-00006979",
      "sum_initial":{ 
        "amount":25000,
        "currency":"MYR"
      },
      "sum_converted":{ 
        "amount":25000,
        "currency":"MYR"
      },
      "code":"9999",            //code specifying the status of the sale operation
      "message":"Awaiting processing",                //phrase explaining the code
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      },
      "operation_fee":{        //object with information about the operation fee
        "amount":25,
        "currency":"MYR"
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}
```

The following is the response to the incorrect request. If the request contains an error, the response includes:

-   response status code indicating the reason for the error that occurred \(`400 Bad Request`\);
-   request processing status \(`error`\);
-   detailed description of the error that occurred: error code \(`2004`\) and the explanatory phrase \(`Required field not provided`\).

```language-json
HTTP/1.1 400 Bad Request                    //response status line
...                                                  //header fields
{
   "status":"error",                                 //request processing status
   "code":"2004",                                    //code specifying the status 
   "message":"Required field not provided"           //phrase explaining the code
}
```

For comparison, the following is the example of the response with the information about a declined payment. This response contains:

-   response status code indicating that the payment status request has been successfully processed \(`200`\);
-   status of the payment in question \(`decline`\);
-   information about the `sale` operation which includes operation processing error code \(`20502`\) and the explanatory phrase \(`Error during operation validation`\).

```language-json
HTTP/1.1 200 OK                                   //response status line
...                                                        //header fields
{
  "project_id":912103,
  "payment":{
    "id":"ORDER_ID_2018nbl",
    "type":"purchase",                                     //payment type
    "status":"decline",                                    //payment status
    "date":"2018-05-04T12:55:51+0000",
    "method":"mobile",                                     //payment method code
    "sum":{
      "amount":849,
      "currency":"EUR"
    },
    "description":"Flights"
  },
  "account":{
    "number":"20072017",
    "type":"mTELE2"
  },
  "customer":{
    "id":"otokarczuk@gmail.com"
  },
  "operations":[
    {
      "id":2018416116,
      "type":"sale",                                      //operation type
      "status":"decline",                                 //operation status
      "date":"2020-05-04T12:55:51+0000",
      "created_date":"2020-05-04T12:55:10+0000",
      "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008",
      "sum_initial":{
        "amount":849,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":849,
        "currency":"EUR"
      },
      "code":"20502",           //code specifying the status of the sale operation
      "message":"Error during operation validation",  //phrase explaining the code
      "provider":{
        "id":5232,
        "payment_id":"1024514",
        "auth_code":""
      },
      "operation_fee":{        //object with information about the operation fee
        "amount":0,
        "currency":""
      }
    }
  ],
  "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow=="
}

```

The following example is the response to the payment status request when the payment in question has not been initiated in the payment platform \(for instance, when the customer has closed the Payment Page without confirming the purchase and, thus, the request to initiate the payment has not been actually sent\). In this case, the response contains:

-   response status code indicating that the payment status request has been successfully processed \(`200`\);
-   status of the payment in question \(`error`\);
-   detailed description of the error that occurred: error code \(`3061`\) and the explanatory phrase \(`Transaction not found`\).

```language-json
HTTP/1.1 200 OK                                 //response status line
...                                                      //header fields
{
  "payment":{
    "status":"error"                                     //payment status
  },
  "errors":[
    {
      "code":"3061",                             //code specifying the status   
      "message":"Transaction not found"          //phrase explaining the code
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}
```

## Checking payment information by request ID {#en_gate_payment_status_request_by_request_id}

### Request format {#section_ahp_s43_55b .section}

A request to check payment status by request ID is formatted according to the guidelines listed in [Interaction concepts](en_gate_interaction_organisation.md). It is sent to the endpoint [/v2/payment/status/request](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status-request), and its body must contain the following identification information:

-   `project_id`—a project ID assigned by Ecommpay at the stage of integration;
-   `request_id`—an ID of the request to be monitored, can be found in the synchronous response from the payment platform;
-   `signature`—a request signature generated after required parameters listed above have been specified. To learn more, see [Signature generation and verification](en_platform_signature.md).

```language-json
{
   "project_id":50,
   "request_id":"2336565",
   "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
}
```

### Response format {#section_qx5_s43_55b .section}

A response to the payment status request is formatted according to the guidelines listed in [Interaction concepts](en_gate_interaction_organisation.md). If the request has been successfully accepted and processed, the response header contains the status line indicating the protocol and its version \(HTTP/1.1\), the response status code and the explanatory phrase \(for instance, `200 OK`\). The body of such response contains information about the payment in question: it is either the information about the payment status and all operations initiated within this payment, or the information about errors in the payment request.

## Related links {#en_gate_payment_status_request_related_links}

-   [Interaction concepts](en_gate_interaction_organisation.md)—general information about integration with the payment platform using Gate.
-   [Payment processing](en_platform_payment_model.md)—detailed information about types, workflows, and possible statuses of supported payments.
-   [Signature generation and verification](en_platform_signature.md)—detailed information about generating and verifying signatures in requests and callbacks sent by the payment platform.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—a comprehensive list of error and response codes used in the payment platform to provide operation processing information.



---

# Cascade payment processing {#en_gate_cascading}

An article about the capability of making additional attempts to process a payment via Gate.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Cascading optionwith card payments {#en_gate_cascading_cards}

### Overview {#section_rlm_rfp_qjb .section}

Payments could sometimes fail due to different reasons. For example, while a payment is being processed by a provider or a bank, technical issues may occur, or processing of the payment may take too long, or a customer's card limit may have been reached.

The Ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful.In any of the above cases, the cascading option enabled allows the payment that cannot be processed properly by a provider to be rerouted to an alternative provider with no change of the payment method. In card payments, you can use the cascading option for both one-step and two-step purchases with authentication by using 3‑D Secure as well as without authentication.

In card payments, a customer may be charged only once for the same payment, that's why it is the payment platform which is required to initiate new additional attempts to process the payment.

Using the cascading option requires to update the merchant web service because the workflow of cascade payment processing includes additional steps that are not included in the workflow of regular payment processing. The following section discusses in more details the workflow of cascade payment processing and how to integrate the option in your web service.

### Setup and configuration {#section_fpy_5hcgh_qjb .section}

To integrate and enable the cascading option in your web service, you need to do the following:

1.  Address the organisational interaction issue with Ecommpay.

    Contact your Ecommpay key account manager and discuss the possibility of implementing the option and updates of your web service that the option requires.

2.  Update your web service to support the cascading option.
    -   Update your payment pages with additional user interface elements.

        If an additional attempt requires performing 3‑D Secure authentication, notifications are recommended to inform a customer that the initial attempt was unsuccessful and then to ask the customer to confirm one more 3‑D Secure authentication with the same card details. You may use notification as an informational component and a button as an input control. Also if the limit on the number of allowed attempts has been reached, you may ask the customer to use another payment method and then to initiate a new payment with a new payment identifier \(`payment_id`\).

    -   Support 3‑D Secure authentication more than once for the same payment without updating card details.

        To support multiple authentication, your web service is required to receive callbacks that contain customer redirection data and the new `cascading_with_redirect` parameter, and then, if the customer accepts, is required to redirect customer to ACS URL.

3.  Test and deploy cascade payment processing with the Ecommpay technical support.

### Workflow {#section_sb4_nvd_kkb .section}

Payments with the enabled cascading option are initiated in the same way as regular payments. Your web service is required to send a request for purchase to initiate an attempt to process the payment. The payment platform accepts the request, and then the 3‑D Secure authentication may be required. If a customer is charged for this attempt, the payment platform sends a callback with the payment results and the `success` payment status. If a customer isn't charged for the initial attempt, the payment platform keeps processing the payment that may require one or more additional attempts to process it.

Until the customer is charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached, the payment platform initiates a new additional attempt. If the new additional attempt doesn't require 3‑D Secure authentication, there is no need any customer and web service involvement. If the 3‑D Secure authentication is required, the payment platform sends another callback with customer redirection data and the `cascading_with_redirect` parameter. If the customer confirms one more additional attempt to process the payment, the payment platform keeps processing the new additional attempt with new 3‑D Secure authentication. The payment status is set to one of following ones: `awaiting_3ds_result`, `awaiting_redirect_result` or `processing`.

Payment processing with the enabled cascading option is completed in the same way as regular payment processing. The payment platform sends a callback with the `success` payment status, if the customer has been charged for one of processed additional attempts. The payment status is set to `decline`, if the customer hasn't been charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached.

The following diagram provides the detailed picture of a one-step purchase processing with the cascade option enabled and the 3‑D Secure authentication included.

![](images/universal/cascade/en_gate_sale_cascading.svg)

\* Ecommpay may function as a provider.

1.  The payment platform performs the internal request processing and sends it to the provider.
2.  The provider processes the request and determines whether the 3‑D Secure authentication is required. If it's required, the provider sends customer redirection data. If it's not required, the provider forwards the request for purchase to an issuer.
3.  The payment platform sends the message with the customer redirection data to the merchant web service.
4.  The web service interacts with the customer:
    -   if the authentication is required for the first time within the payment processing, the web service redirects a customer to the authentication page.
    -   If the authentication is required again, it's recommended to display card details, information about unsuccessful attempt to the customer and ask the customer to confirm one more 3‑D Secure authentication with the same card details. If the customer confirms, the web service redirects a customer to the authentication page.
5.  The authentication page is displayed to the customer.
6.  The issuer authenticates the customer.
7.  The issuer redirects the customer to the web service and sends a message with the authentication results to the web service.
8.  The preloaded page hosted on the web service is displayed to the customer.
9.  The web service sends the request for the payment completion that contains the authentication result to the URL of the Ecommpay payment platform.
10. The payment platform accepts the request.
11. The payment platform validates and then processes the request.
12. The payment platform sends the response with the validity check result and the request receipt acknowledgement.
13. The payment platform performs the internal request processing and sends it to the provider.
14. The provider processes the request. If the customer isn't charged, the provider sends information about declined payment, and then the payment platform initiates a new additional attempt to process the payment. If the customer is charged, the provider forwards the request to the issuer, and the payment platform keeps processing the payment in the same way as regular payment processing.

### Callback format {#section_bnh_qw4_rjb .section}

In card payments, payment processing with the enabled cascading option uses the standard format for callbacks with payment results \(for more information, see [Handling callbacks](en_platform_callbacks.md)\), as well as standard formats for intermediate callbacks with redirection data \(for more information, see [3‑D Secure authentication](en_gate_payment_3ds.md)\). Note that unlike regular payment processing, in payment processing with the enabled cascading option, callbacks with redirection data contain the `cascading_with_redirect` parameter. The parameter is set to one of the following values:

-   `true`—It means you should ask a customer to confirm one more additional attempt to process the payment because one of previous additional attempts has required 3‑D Secure authentication.
-   `false`—It means you shouldn't ask a customer to confirm one more additional attempt to process the payment because non of previous additional attempts has required 3‑D Secure authentication.

The reason the payment is declined is may be specified in the `message` parameter of the `operations` object.

In the following example of callback, the `cascading_with_redirect` parameter is set to `false`, so the merchant web service isn't required to ask the customer to confirm one more additional attempts to process the payment.

```
{
        "cascading_with_redirect": false,
        "payment": {
            "date": "2020-03-28T09:28:54+0000",
            "OperationFee": {
                "amount": 0,
                "currency": "USD"
            },
            "type": "purchase",
            "sum": {
                "amount": 2000,
                "currency": "USD"
            },
            "status": "awaiting 3ds result",
            "method": "card",
            "id": "1115888716",
            "description": ""
        },
        "customer": {
            "id": "11158745"
        },
        "account": {
            "number": "431422******0056",
            "type": "visa",
            "card_holder": "Jane Doe",
            "expiry_month": "11",
            "expiry_year": "2025"
        },
        "project_id": 18616,
        "operation": {
            "id": 50454000052091,
            "type": "sale",
            "status": "awaiting 3ds result",
            "date": "2020-03-28T09:28:54+0000",
            "created_date": "2020-03-28T09:28:53+0000",
            "request_id": "af5e3a32bf6f8742c9are9",
            "sum_initial": {
                "amount": 2000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "USD"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "eci": "07",
            "provider": {
                "id": 4164,
                "payment_id": "",
                "endpoint_id": 4184
            }
        },
        "card_type": "Visa Gold",
        "acs": {
            "pa_req": "eJxVUd85...W6ip/iPo2E=",
            "acs_url": "https://acs.bank.com/pareq",
            "md": "eyZjUtODg...IjoiIn0="
        },
        "signature": "T1e+AOko05D...KupPd7TA=="
    }

```



---

# Checking payment method availability {#en_gate_available_methods}

An article about the capability of obtaining via Gate payment method availability information for processing a specific payment.

When working with different payment methods, in some cases you may need to get updates on their availability, for example, to keep the list of methods available to your customers accurate and up to date. The Ecommpay payment platform supports the capability of checking payment method availability via an API both for individual and for all integrated methods. At the same time, however, keep in mind that even if the payment method is available, the problems when processing payments made with this method can still occur.

To check payment method availability, use requests to the [/v2/info/available-methods/\{payment\_direction\}/list](https://api-developers.ecommpay.com/api.html/v2-info-available-methods-payment-direction-list) endpoints where `payment_direction` indicates the payment category you need: `payin` for purchases of any type and `payout` for payouts. When working with these requests, keep in mind the following:

-   Each request must contain the `general` object with two parameters:
    -   `project_id`—project identifier obtained from Ecommpay during integration.
    -   `signature`—request signaturegenerated after all required parameters are specified \(for details, see [Signature generation and verification](en_platform_signature.md)\).
-   If you need to check payment method availability for one or several specific payment methods, pass the `payment_method_list` array that specifies the [payment method code](en_pm_codes.md) for each method individually as a value of the `payment_method` parameter.

```language-json
{
  "general":{
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    },
  "payment_method_list": [
        {
            "payment_method":"etoken"
        },
        {
            "payment_method":"google-pay"
        }
        ]
}
```

```language-json
{
  "general":{
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}
```

A payment method availability request is processed according to the synchronous model of interaction between the web server and the payment platform. This implies that the request is fully processed within one HTTP session and uses only the resources of the payment platform. The response to the correct request contains an HTTP response status code \(`200`\) and the required data without detailed request processing information. If the request is incorrect, or there have been issues with its acceptance and processing, then the response contains an HTTP response status code, request processing status `error` and the detailed description of the error that occurred. To learn more about HTTP response status codes, see [Interaction concepts](en_gate_interaction_organisation.md), and to learn more about the response codes that provide information on operation processing in the payment platform, see [Handling operation processing information](en_platform_payment_info_codes.md).

The body of the response to the correct request contains the project identifier, the signature, and the payment method availability array.

```language-json
{
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==",
    "available_methods":[
        {
            "payment_method":"etoken",
            "is_available": false
        },   
        {
            "payment_method":"google-pay",
            "is_available": true
        }]
}
```

```language-json
{
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==",
    "available_methods":[
        {
            "payment_method":"card",
            "is_available": true
        },    
        {
            "payment_method":"etoken",
            "is_available": false
        },    
        {
            "payment_method":"google-pay",
            "is_available": true
        }]
}
```

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Processing purchases with partial authorisation {#en_gate_partial_approval}

An article about the capability of processing purchases via Gate with the payment amount partially approved by the issuer.

## Overview {#section_slr_23r_c3c .section}

During payment processing, you can encounter situations when the customer's account has insufficient balance for paying the full amount, but you would rather accept a portion of the payment amount than decline the whole payment. For example, it can be relevant when the customer adds funds to their account in the web service: it might not cover the full amount of the subscription fee, but at least a part of it will be paid. To accept such payments and avoid declining them due to insufficient funds, you can use the functionality of partial authorisation \(also referred to as partial approval\) when a portion of the payment amount is approved by the issuer. This feature is supported by specific card networks.

The Ecommpay payment platform supports processing purchases with partial authorisation for standard card payments made with Mastercard and Visa. This capability is enabled upon agreement with your Ecommpay account manager for specific projects, following which you can request to apply partial authorisation to each payment initiated on the side of the web service. You can use a specialised parameter `allow_partial_approval` that was added to the request structure in the API specification.

The exact amount for which the purchase can be authorised is determined each time by the issuer of the card used for making this purchase\(the amount depends on the available balance on the customer's card\). The information about this amount is passed from the issuer to the Ecommpaypayment platform where the approved amount is counted as the actual payment amount, while the initially requested payment amount is ignored. Note that this change can affect subsequent operations within this purchase, for example, capturing the funds held as part of a two-step purchase, or refunding the purchase amount.For example, if the purchase for the *initially requested* amount of `100 EUR` was *partially approved* for the amount of `90 EUR` \(the sum actually paid by the customer\), partial refund can be requested only for the amount lower than `90 EUR`. In turn, the difference between the initial and approved amounts can be paid \(and if needed, refunded\) separately, with the use of a separate payment request.

The use of partial authorisation capability does not affect standard payment processing workflows as to the interaction between the web service and the payment platform. However, when using this capability, you should be aware of changes in the request and callback formats \(more on this below\) and be ready to supplement user scenarios as follows. You need to:

-   Inform your customers that partial authorisation capability is available or make sure they can consent to this payment option—before every purchase to which partial authorisation feature applies.
-   Inform you customers about the partially approved and paid amount—after every purchase with partial authorisation has been completed.
-   Provide your customers with the possibility to pay the outstanding amount by making a separate payment\(with the use of a different payment instrument\)—if necessary.
-   Ensure the possibility to refund the paid amount—if necessary.
-   Add other changes and modifications—if it is dictated by the specifics of the web service or the services you provide.

If you have questions about the integration of the partial authorisation capability, refer to your Ecommpay account manager. If you have technical questions about the use of this capability, refer to the Ecommpay support specialists

## Special aspects and limitations {#section_j1f_mbz_c3c .section}

When working with the capability of processing purchases with partial authorisation, consider the following special aspects and limitations:

-   This capability is supported for purchases made with Mastercard and Visa cards, in cases when the issuer of the specific card supports partial approvals.

    If the issuer does not support this capability and the customer's account has insufficient balance, the purchase is declined.

-   This capability must be enabled for the project.

    If this capability is not enabled and the customer's account has insufficient balance, the purchase is declined even if the request contains an indicator that partial approval is allowed.

-   Partial authorisation can be applied to one-step and two-step purchases as well as one-click purchases if their terms are stored on the side of the web service\(the value of `stored_card_type` parameter is `2`, [details](en_Gate__payments_on_saved_data.md)\). If a COF purchase is registered, the initial payment can be partially authorised. However, even if the initially requested payment amount has been changed, the actual amount of the series of debitings that is being registeredwill not be affected.

    If the request to initiate an on-demand or a regular COF purchase \(the value of `stored_card_type` parameter is `4` or `6` respectively\) contains an indicator that partial approval is allowed, it will be ignored and, if the customer's account has insufficient balance, the purchase will be declined.

-   After the feature of partial authorisation was applied, the actual payment amount is the amount approved by the issuer.

    This factors in when currency conversion is used and it affects the subsequent operations within the payment including refunds and various actions performed as part of the two-step purchase \(increasing or decreasing the previously authorised amount, capturing the held funds or cancelling the hold, even if these operations are initiated automatically\).


## Setup, testing, and use {#section_pxp_2fz_c3c .section}

To *enable* the partial authorisation capability:

1.  With your Ecommpay account manager, discuss and agree upon setting up this capabilityand whether testing is necessary.
2.  If you need testing, get notified by the Ecommpay specialists that the capability is ready for being used in test mode,test this capability, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the capability has been added and fullyset up.

To *test* accepting purchases with partial authorisation, process at least one purchase in your test projectusing the request format described [below](en_gate_partial_approval.md#section_eps_yfz_c3c) and specifying test data.

-   If you test processing a purchase for the amount greater than `120 EUR`\(`12000` in the smallest currency unit\) with the use of test card numbers `5126160000356675` or `4010571676223548`, the charged amount will be `120 EUR`. All other parameters, including the name of the cardholder or the verification code, can contain arbitrary values but should be specified in appropriate format\(for example, the card expiry date must occur after the payment date\).
-   In other cases, the full purchase amount will be charged or the purchase will be declined\(according to the processing scenarios set up for the project\).

``` {#codeblock_jn2_yqx_f3c .language-json}
{
  "general": {
      "project_id": 41,
      "payment_id": "test_165",
      "signature": "MpdRv7dsOtVftZ1ZZ5D/aZAebeR+CqGrNw...=="
  },
    "payment": {
      "amount": 15000,
      "currency": "EUR",
      "allow_partial_approval": true
  },
    "card": {
      "pan": "4010571676223548",
      "year": 2035,
      "month": 8,
      "card_holder": "JANE DOE",
      "cvv": "123"
  }
    "customer": {
      "ip_address": "192.0.2.1,
      "id": "test_customer",
      "screen_res": "360x640",
      "phone": "999123456789",
      "email": "test@example.com"
  }
}
```

``` {#codeblock_gns_yqx_f3c .language-json}
{
    "account": {
        "number": "401057******3548",
        "type": "visa",
        "card_holder": "JANE DOE",
        "id": 12,
        "expiry_month": "08",
        "expiry_year": "2035"
    },
    "customer": {
        "id": "test_customer",
        "phone": "999123456789"
    },
    "payment": {
        "date": "2026-01-10T13:02:42+0000",
        "id": "test_165",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 12000, // approved amount
            "currency": "EUR"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 325,
        "type": "sale",
        "status": "success",
        "date": "2026-01-10T13:02:42+0000",
        "created_date": "2026-01-10T13:01:45+0000",
        "request_id": "eedb14c629b4ef20b086d...d04132b0088cbc0be",
        "sum_initial": {
            "amount": 12000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 12000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "MpfogAxwRIL9tVftD/aZAeb0VMdeR+CqGUwSm...=="
}
```

To *indicate* that partial authorisation can be applied to a specific payment, make surethe capability has been enabled and include the `allow_partial_approval` parameter with `true` specified as its value in the payment requestsent from the web service to the payment platform.

## Request format {#section_eps_yfz_c3c .section}

When sending requests to initiate purchases with partial authorisation, consider the following:

1.  To initiate a purchase, send a POST request to one of the following endpoints:
    -   for one-time one-step purchases with actual card details specified and for one-click purchases—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
    -   for one-time one-step purchases with the saved card identifier specified—[/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)
    -   for one-time one-step purchases with the card token specified—[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)
    -   for one-time two-step purchases with actual card details specified—[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)
    -   for one-time two-step purchases with the saved card identifier specified—[/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)
2.  Each request must contain objects and parameters required for processing a purchase of a specific type\(more information can be found in the descriptions of request formats for initiating [one-step](en_gate_payment_sale.md) and [two-step](en_gate_payment_auth.md) purchases and [one-click purchases with their terms stored on the side of the web service](en_Gate__cof_merchant_side.md#section_jbj_flf_dlb).
3.  Each request must contain the `allow_partial_approval` parameter with `true` specified as its value in the `payment` object.If `false` is passed, or this parameter is not passed in the request at all, partial authorisation is not allowed.
4.  Additionally, any other parameters included in the API specification of the endpoint can be used.

``` {#codeblock_izf_fkt_yhc .language-json}
{
  "general": {
      "project_id": 42,
      "payment_id": "135113521359",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "payment": {
      "amount": 10000,
      "currency": "EUR",
      "allow_partial_approval": true
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2035,
      "month": 8,
      "card_holder": "Prostetnik Jeltz",
      "cvv": "521"
  }
    "customer": {
      "ip_address": "93.47.230.225",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "p.jeltz@mail.com"
  },
    "return_url": {
      "success": "https://cosmoshop.jupiter.example/pages/success",
      "decline": "https://cosmoshop.jupiter.example/pages/decline"
  }
}
```

``` {#codeblock_t1n_rsg_23c .language-json}
{
  "general": {
      "project_id": 42,
      "payment_id": "135113521359",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "payment": {
      "amount": 10000,
      "currency": "EUR",
      "allow_partial_approval": true
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2035,
      "month": 8,
      "card_holder": "Prostetnik Jeltz",
      "cvv": "521"
  }
    "customer": {
      "ip_address": "93.47.230.225",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "p.jeltz@mail.com"
  },
    "return_url": {
      "success": "https://cosmoshop.jupiter.example/pages/success",
      "decline": "https://cosmoshop.jupiter.example/pages/decline"
  }
}
```

## Callback format {#section_pzd_1gz_c3c .section}

Results of purchases with partial authorisation are communicated in callbacks with standard format.To learn more about the callback format, see [Handling callbacks](en_platform_callbacks.md). Note that parameters `sum`, `sum_initial`, and `sum_converted` passed in the `payment` and `operation` objects contain the amount approved by the issuer, and this amount should be used for reporting and reconciliation.

The following example contains the result of processing a one-time purchase for the amount of `90 EUR` approved by the card issuer. \(The example of the initial payment request specified the amount of `100 EUR`.\)

``` {#codeblock_avz_wkt_yhc .language-json}
{
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "PROSTETNIK JELTZ",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2035"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2026-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2026-01-11T13:02:42+0000",
        "created_date": "2026-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "sum_converted": {
            "amount": 7805, // approved amount in the actual operational currency
            "currency": "GBP" // code of the actual operational currency
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2026-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

``` {#codeblock_stx_5sg_23c .language-json}
{
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "PROSTETNIK JELTZ",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2035"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2026-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2026-01-11T13:02:42+0000",
        "created_date": "2026-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "sum_converted": {
            "amount": 7805, // approved amount in the actual operational currency
            "currency": "GBP" // code of the actual operational currency
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2026-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

## Useful links {#section_kxp_mlz_c3c .section}

The following materials can be useful when you work with the capability of partial authorisation:

-   [One-time purchases](en_Gate_purchase.md)—a section with articles about processing one-time one-step and two-step purchases via Gate, including description of processing workflows and data formats for working with standard card payments.
-   [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)—a section with articles about registering and processing COF purchases via Gate, including description of processing workflows and data formats for working with standard card payments.
-   [Purchase refunds](en_Gate_Refund.md)—an article about refunding purchases via Gate, including general information about refunds and description of data formats for working with standard card payments.
-   [Handling payment processing information](en_platform_payment_information.md)—a section with articles about different ways to receive data that merchants can use to monitor and analyse payment processing activity.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Saving payment data {#en_gate_saved_data .concept}

An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of arbitrarily assigned identifiers.

For convenience of quick and efficient payment customers can save the data of one or several bank cards, e-wallets, accounts, mobile numbers or any other payment instrument when performing a payment. If you obtain the [PCI DSS](https://www.pcisecuritystandards.org/pci_security/) certificate, you can store the card data on your side, if not—on Gate side. For each payment instrument, Gate saves the payment credentials and assigns the instrument its own ID.

Gate supports the maximum quantity limits of the payment instruments a customer can save.

**Note:** To enable and configure the service contact the technical support by email [support@ecommpay.com](mailto:support@ecommpay.com).

**Warning:** To save and perform payments on saved data, pass the id parameter of the customer object in the request for payment.

## Retrieving the list of saved payment data {#section_yz5_kyy_wbb .section}

Additionally, you can request a list of the customer's saved instruments and their details; in this case the number of the customer card is masked and CVV is not sent.

## Request to retrieve the list of saved payment data {#section_h5b_zdn_jbb .section}

**Note:** POST the [/v2/customer/saved\_account/list](https://api-developers.ecommpay.com/api-specification/requests-for-customer-details/post-v2-customer-saved-account-list) request.

In the request specify the customer id, the project id, and the payment system.

When Gate finishes processing the request, you receive a response with the list of customer's saved payment instruments. The response will not contain the list if no payment instruments were savedin the selected payment system. For each payment instrument, its ID in Gate is specified in the account\_id orcard\_id parameter.

## Deleting saved payment data {#section_qy2_zyy_wbb .section}

When a customer deletes previously saved payment instrument, send the request for removal. In this case, Gate removes the instrument from the list of saved payment instruments, but does not delete its data.

**Note:** If the saved card has a token, the token will be deleted when the saving of the card is canceled. Alternatively, a saved bank card is removed when you revoke the token of this card. For more information about tokens, see [Using tokens](en_Gate_Token.md).

## Request to delete a payment data from the saved list {#section_nh4_zdn_jbb .section}

**Note:** POST the [/v2/customer/saved\_account/delete](https://api-developers.ecommpay.com/api-specification/requests-for-customer-details/post-v2-customer-saved-account-delete) request.

In the request specify the ID of the saved payment instrument.

When Gate finishes processing of your request you receive a reply with the result of removal of the payment instrument from the saved list.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Using tokens {#en_Gate_Token .concept}

An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of standardized internal tokens.

**Token** is a unique, random sequence of 64 characters associated in Gate with a specific bank card and the customer in the project. Token does not contain a confidential information and can be stored in your system without threatening to violate the standards of secure bank card data storage.

By using Gate you can create tokens automatically or by request and make puchases and payouts by using existing tokens.

## Statuses of tokens {#section_txw_jp2_zbb .section}

The status of a token defines if the token can be used to perform payments and payouts.

|Status|Description|
|------|-----------|
|active|Token is active and can be used to perform payments and payouts|
|revoke|Token is revoked and cannot be used to perform payment and payouts|
|expiry|Token has expired and cannot be used to perform payment and payouts|

## Automatic token generation {#section_jrt_kzd_lbb .section}

*Automatic generation* procedure creates a token when the first successful purchase or payout is performed by using a bank card, as well as after holding the funds on a bank card.

The generated token and the date when it was created are returned in the payment callback. For more information about callbacks, see in [Handling callbacks](en_platform_callbacks.md).

**Note:** To enable automatic token generation, contact technical support by email [support@ecommpay.com](mailto:support@ecommpay.com).

## Token generation by request {#section_emy_sg2_lbb .section}

Another way to generate a token is to send a request to generate a token. In the request you send the data required to generate the token.

The generated token and the time it was created at are returned in the token generation response.

## Token generation request {#section_vft_rzd_lbb .section}

**Note:** POST the [/v2/customer/card/tokenize](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-tokenize) request.

Specify the project id, customer data and data of customer bank card in the request.

You receive in the callback a bank card token and the time when it was generated. For more information about callbacks, see in [Handling callbacks](en_platform_callbacks.md).

```language-javascript
{
    "customer": {
        "id": "1707",
        "ip_address": "1.87.128.111",
        "project_id": 11,
        "signature": "LLmhbDKdNhNLT+Qkr2SzbLbFYNxC9sZLnQKkrTFYNN06NMPmZS/BfWGucWQVZ2WM3v5N709w=="
    },
    "card": {
        "pan": "4314220000000056",
        "year": 2020,
        "month": 5,
        "card_holder": "PAUL SMITH"
    }
}
```

## Payment by token {#section_fcr_vxx_5bb .section}

Gate enables customers to process fast payments by using a previously generated bank card token.

**Note:** The token is unique to the bank card. When processing payments by bank card a valid token that already exists will be returned.

The token is unique to the bank card. When processing payments by bank card a valid token that already exists will be returned. In this case, if the card expiration date is different from the one specified when the token was generated, the token is not generated anew, but the expiration date of the token is updated.

Additional information about the token-based payments see in [One-time purchases](en_Gate_purchase.md).

## Payout by token {#section_zyv_mc2_lbb .section}

Gate enables you to process the payout of funds to a customer's bank card by using a previously generated token. Additional information about the token-based payouts see [Payouts](en_Gate_payout.md).

## Receiving card data by token {#section_vqp_phc_yfb .section}

If you need to receive bank card data and information about the payment instrument to which this card is linked, send a request to Gate.

**Note:** POST the [/v2/customer/card/bytoken](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-bytoken) request.

In the request, specify the project ID, customer ID and token.

You receive in the callback the masked bank card data and other information on the customer payment instrument.

```
{
	"customer": {
		"project_id": 12,
		"id":"test_customer",
		"signature":"2tlMuYxLW9Yu6RETr8pdCfmi0UPE8JguQjXWH6naCA9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q=="
	},
	"token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039"
}
```

```
{
    "account": {
        "id": 2932,
        "number": "431422******0056",
        "type": "card",
        "additional": {
            "country": "GB",
            "phone": "4314220000000056",
            "email": "john@gmail.com",
            "card": {
                "expiry": "01/20",
                "holder": "JOHN JOHNSON",
                "type": "visa"
            }
          },
          "recurring_enable": false
        },
        "token": "959c664ad64b8caa54bb7836ddc777fd1a3e6c704b59bd71d89caff6c242a039"
    },
    "signature": "62kPxuCGqN4KDrxqqsuWnv0LOjdvUydWCxDmN+AVW7/5UtLlmVL+SIyfbxot/Nf+47DEsAuW76DIgBg=="
}
```

## Card verification by token {#section_gch_npt_wmb .section}

Gate enables you to perform the customer's bank card verification by using a previously generated token. The information about the token-based verification is provided in the [Payment instrument verification](en_gate_account_verification.md) section.

## Revoke of a token {#section_kw4_31z_wbb .section}

A token can be revoked in one of the following happens: you revoke the token or the payment card expires.

In the former case, if required, you can revoke a token from Gate by sending a request to revoke the token. Gate revokes the token.

## Request to revoke a token {#section_t5g_4ym_jbb .section}

**Note:** POST the [/v2/customer/card/token/revoke](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-token-revoke) request.

Specify the customer data in your system and the token to be revoked.

You receive in the callback the result of revoking of the token.

## Callback after generating or revoking a token {#section_ozl_ws3_1cb .section}

Once you pass a token generation or token revoke request to the [/v2/customer/card/tokenize](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-tokenize) endpoint, the payment platform returns a callback with the request execution result. The following table shows the parameters included in the callback. For more information about callbacks, see [Handling callbacks](en_platform_callbacks.md).

|Parameter|Description|tree|
|---------|-----------|----|
|general  
 object, required

|The object with the general request data.|1|
|project\_id  
 string, required

|The unique identifier of your project.

 Example: `42`.

|1-11|
|customer\_id  
 string, optional

|The unique identifier of the customer in your project.|1-21|
|signature  
 string, required

|Callback signature|1-31|
|request  
 object, required

|The object with the request data|2|
|id  
 integer, required

|Unique identifier of the request

 Example: `3718000054`

|2-12|
|action  
 string, optional

|Type of the request. The following options are available:-   `tokenize`—token creation request
-   `token_revoke`—token revoke request
-   **parameter is missing from callback** — token is expired and deactivated. The platform initiates a callback with missing action automatically, immediately after the token expires. Such callback is not issued in response to a request.

|2-22|
|status  
 string, required

|The request status. The following options are available:-   `success`—request successfully completed
-   `error`—error\(s\) encountered when processing request. The error details are passed in the errors array.

|2-32|
|errors  
 array, optional

|Array of error messages.|2-42|
|ErrorItem  
 object, required

|The object with information about a single error.|2-4-12-4|
|code  
 string, optional

|Error code.

 Example: `10309`.

|2-4-1-12-4-1|
|message  
 string, optional

|A message that clarifies the error cause.

 Example: `Attempt to make COF purchase without registered recurrent payments.`

|2-4-1-22-4-1|
|field  
 string, optional

|The parameter in which the error occurred if it was defined|2-4-1-32-4-1|
|token  
 string, optional

|Token of the customer bank card. The token is generated automatically when a successful payment is performed if the appropriate option is enabled.|3|
|token\_created\_at  
 string, optional

|The date and time the token was generated.

 Example: `2017-07-21T03:31:24+0000`

|4|
|token\_status  
 string, optional

|Token status.

 Example: `active`

|5|

```language-xml
"general":{
   "project_id":12,
   "signature":"\/gmTHcy5wvrFD4ISuWEiV8+nOa3aqnLnyJ\/AupOYkl9S5eLJZ",
"request": {
			"id": "3c7f53fdbb5b8c96f9707457d75f",
			"action": "tokenize",
			"status": "success"
		},
"token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
"token_created_at":"2017-11-28 13:30:57",
"token_status":"active"
}
```

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Using Mastercard and Visa network tokens {#en_gate_tokens}

An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of Mastercard and Visa network tokens.

## Overview {#section_rsl_pxl_rhc .section}

To improve convenience and security of card payments, global card networks offer network tokenisation solutions. A network token is created for a card of the respective card network and via a specialised service of this card network. Once created and collected, this token can be used in payment processing via any acquirer or provider that supports working with network tokens of the said card network.

The Ecommpay payment platform allows you to process payments with the use of network tokens created by the Mastercard Secure Card on File \(SCOF\) service and Visa Token Service \(VTS\). A network token is a sequence of 16 characters that can be used in requests instead of the card number.When the card associated with a specific token is reissued or replaced or its details are changed in any other way, the token remains valid because the data associated with the token is updated automatically in the originating tokenisation service.

When processing payments via the Ecommpay payment platform, you can use network tokens if such tokens have already been created in the third-party services and are being used on the side of the merchant web service. In other cases, you can use the capabilities of processing payments with tokens via Payment Page \([details](en_pp_token.md)\) and Gate \([details](en_Gate_Token.md)\) and migrating information about payment card tokens from other acquirers \([details](en_gate_data_migration.md)\).

If you have questions regarding the terms and conditions of using network tokens and the steps of integrating this functionality, refer to your Ecommpay account manager.If you have questions regarding the technical aspects of using network tokens, refer to the information on the documentation portal and to the Ecommpay technical support.

## Special aspects and limitations {#section_vfs_pxl_rhc .section}

When processing payments with the use of network tokens, you need to consider the following:

-   The capability of using network tokens \(for all supported card networks\)must be enabled for the specific project.

    When this capability is not enabled for the project, payments with network tokens are declined with the 318 error code.

-   The use of network tokens is limited to several payment workflows that include processing one-time one-step and two-step purchases, registering and processing COF purchases with saved data stored on the side of the web service \([details](en_gate_payment_recurring_registration.md)\), and payment card verification.

    In other cases, for example, processing payment link purchases, COF payments with saved data stored on the side of the platform, or issuing payouts, you can only use tokens created in the payment platform \([details](en_Gate_Token.md)\).

-   Managing network tokens \(creating, updating, and receiving data required for their use\) is carried out via specialised services.

    To learn more about working with them, refer to documentation and specialists of these services.

-   The merchant is responsible for appropriate use of network tokens and the network token information.

    If you have questions concerning the incorrect use of network tokens, contact your Ecommpay account manager.


## Request format {#section_vtw_pxl_rhc .section}

When creating a request for processing a payment with the network token, consider the following:

1.  The request must be sent to one of the following endpoints with the use of the HTTP POST method:
    -   for one-time one-step and COF purchases—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
    -   for one-time two-step purchases—[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)
    -   for payment card verification—[/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)
2.  In the `card` object, specify the following network token information instead of card details:
    -   `pan`—the token created in the specialised service of the card network
    -   `year`—the year of the token's expiration date\(in the `YYYY` format according to the Gregorian calendar\)
    -   `month`—the month of the token's expiration date\(as a number without a leading zero\)
    -   `card_holder`—the name of the cardholder, passed if this parameter is required for the project\(the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks\)
    -   `cvv`—card verification code \(required in all cases except for processing on-demand and regular COF purchases\)
3.  In the `token_data` object, pass the following parameters:
    -   `token_type`—the type of the token with the value `network_token` \(required for each payment\)
    -   `cryptogram`—the verification code of the network tokensuch as the Token Authentication Verification Value \(TAVV\) received from the network tokenisation service \(required for registering COF purchases and optional for other payment types\)
    -   `eci`—[the Electronic Commerce Indicator](en_ECI_codes.md) that corresponds to the token, received from the network tokenisation service \(required for registering COF purchases and optional for other payment types
    -   `trid`—the identifier of the merchant assigned when the merchant registers in the network tokenisation service \(optional\)
4.  In the required `stored_card_type` parameter, pass one of the following values:

    -   `1` to save payment data or register a one-click purchase
    -   `2` to process a payment with saved payment data or a one-click purchase
    -   `3` to register an on-demand COF purchase
    -   `4` to process an on-demand COF purchase
    -   `5` to register a regular COF purchase
    -   `6` to process a regular COF purchase
    You can find more information about working with COF purchases in [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)

5.  When processing a COF purchase \(the `stored_card_type` contains values `2`, `4`, or `6`\) made with a card issued in the European Economic Area, pass the `scheme_id` parameter, which is an identifier of the initial operation within which the COF purchase was registered on the side of Mastercard or Visa.
6.  Additionally, you can use any other parameters from the API specification of the endpoint you need.

## Useful links {#section_mcb_qxl_rhc .section}

When working with network tokens, you can also use the following articles:

-   [One-time purchases](en_Gate_purchase.md)—about processing of one-time one-step purchases by using Gate.
-   [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)—about processing of COF purchases via Gate
-   [Using tokens](en_Gate_Token.md)—about processing payment with tokens generated in the payment platform.
-   [Migrating information about COF purchases and payment card tokens](en_gate_data_migration.md)—about the steps for migrating information about COF purchases and tokens created by other acquirers.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Migrating information about COF purchases and payment card tokens {#en_gate_data_migration}

An article about the capability of migrating information about recurring purchases and payment card tokens from other acquirers to the Ecommpay platform.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## General information {#en_gate_data_migration_overview}

In some instances, it may be relevant for the merchant to process payments via Ecommpay with the payment details previously saved in the services of other acquirers. The Ecommpay payment platform provides this functionality by supporting the following options:

-   Merchants can migrate and use the data of COF purchases \(both scheduled and on-demand\) and payment card tokens. This capability is described in this article.
-   Merchants can process COF purchases registered in the services of other providers, without migrating the data about them to the platform. To set up and use this capability, refer to your Ecommpay account manager.

Migration of information about COF purchases and card tokens can be relevant when you need to use card tokens, combine the use of the Ecommpay platform and services of other acquirers, and in cases when you need to implement processing COF purchases with automatic debiting. While Ecommpay charges no fees for such migration, certain fees may be charged by the acquirer providing the to-be-migrated information. Besides, migration is only possible if the acquirer supports such a capability and if other conditions are met \(described further\).If you have any questions about the organisation of data migration to Ecommpay from other acquirers or in reverse, contact the Ecommpay account manager.

Due to the data sensitivity, the data should be encrypted before migration. When it comes to migrating data to the Ecommpay platform, this data is usually encrypted via the PGP \(Pretty Good Privacy\) algorithm; however, in certain cases, other methods can be used upon the coordination with the Ecommpay specialists \(for example, when the acquirer that provides the data does not support the PGP encryption\).

For migrating data, the file with this data must be encrypted by your current acquirer providing the data with the use of the public key from Ecommpay \(in case of the PGP encryption\) and sent to the Ecommpay specialists. Contact your Ecommpay account manager to set up a communication channel with the dedicated Ecommpay specialists responsible for the data migration.

After all the necessary data has been migrated to the Ecommpay payment platform and its correctness has been confirmed by the merchant, the target COF purchases and tokens can be used for making various actions supported in the platform: performing series of debits within COF purchases \([details](en_Gate__cof_merchant_side.md)\), managing these debits \([details](en_gate_payment_recurring_manage.md)\), processing purchases and payouts with the help of tokens \([details](en_Gate_Token.md)\), performing payment cards verification \([details](en_gate_account_verification.md)\), and so on. Along with that, all information about payments processed by using the migrated details can be obtained via the Dashboard interface\(in the **Payments** section, with the information about all payments, and the **Subscriptions** section, with the information about regular purchases\), [the Data API](en_dbl_api_protocol.md), and the Gate API.

**Note:** Note that for performing any actions with the use of the migrated data, it is required to use new identifiers registered in the Ecommpay payment platform:

-   card tokens specified in the `token` parameter
-   identifiers of payments specified in the `payment_id` parameter
-   identifiers of series of debits specified in the `id` parameter of the `recurring` object

These identifiers are included in the verification file sent to the merchant's specialists to confirm the correctness of the migrated data and can only be used with the identifier of the project \(`project_id`\), to which they are initially assigned.

## Conditions and limitations {#en_gate_data_migration_restrictions}

When using the capability of data migration, the merchant should consider the conditions and limitations from both the acquirer providing the information and Ecommpay receiving the data. Ecommpay applies the following restrictions:

-   The information migration is only available for the following card networks: American Express,Mastercard, and Visa.

    For working with cards of other card networks, the generation of tokens and registration of COF purchases should be carried out directly in the platform, with the use of the corresponding options supported.

-   The information can only be migrated directly from other acquirers.

    When working via third parties, the merchant should discuss with them whether it is possible to interact directly with the acquirers.

-   The information migration is only possible within the production projects in the Ecommpay payment platform.

    If not yet an Ecommpay client, the merchant should submit [an application](https://ecommpay.com/sign-up/) to connect and proceed with the onboarding process.

-   The merchant is responsible for keeping the migrated information up-to-date and correct.

    After the migration, a verification file is sent to the merchant's specialists. If they confirm the correctness of the data in this file, the information is considered valid and the responsibility for any consequences \(for example, the occurrence of a chargeback due to an erroneous withdrawal of funds from a customer\) is placed on the merchant.

-   The merchant is responsible for double debits.

    Prior to the data migration, the Ecommpay specialists and the merchant's specialists agree on the date for payment processing with the use of the migrated information to start. In order to avoid double debits \(via the two acquirers\), the merchant should ensure that the processing of payments via the previous acquirer will be terminated by the agreed date.


## Migration workflow {#en_gate_data_migration_workflow}

The information about COF purchases and tokens is migrated through an encrypted communication channel established between Ecommpay and your current acquirer that provides the information. Migration timelines usually make up a maximum of one week for tokens and a maximum of two weeks for COF purchases. These timelines depend on various factors and can vary if it is required to set up additional parameters, they also can be discussed by the involved parties. If migration of the token information is completed and necessary for payment processing prior to the migration of the COF purchases information, its early usage can be arranged with the Ecommpay specialists.

To have the data migrated, the merchant should:

1.  Agree with the other acquirer on the migration availability and conditions.
2.  Inform the Ecommpay account manager that data migration is needed and agree on the migration timelines and the date to start payment processing.

    If you are not an Ecommpay client, submit [an application](https://ecommpay.com/sign-up/) to connect and proceed with the onboarding process.

3.  Agree with the Ecommpay specialists on the following:
    -   The projects that require information migration.

        If it is necessary to migrate information for several projects in the platform, the migration is carried out for each project individually.

    -   The set of parameters that should be migrated to the Ecommpay platform.

        The set can include either only basic parameters described [further](en_gate_data_migration.md) and required for use or, if relevant, the basic parameters alongside additional ones supported in the platform.

    -   If you need to migrate information about COF purchases—the identifiers that should be assigned to these purchases\(as the values for the parameter `scheduled_payment_id`\) and the series of debits within these purchases\(as the values for the parameter `register_payment_id`\).

        These values can be in the format used by default \(`Ecommpay–yyyymmddnnn`\) or in the formats specified by the merchant \(with regards to the 255-character limit\).

    -   The set of parameters that should be used by the merchant's specialists to verify that the target information has been migrated to the platformcorrectly and can be used for payment processing.

        This set must include the new identifiers \(`token` and `recurring_id`\), particular parameters from the basic set that are marked as ‘required for verification’ and, if relevant, can include additional parameters from the migrated ones.

    -   The contact information of the specialists in charge of migration on the side of the merchant, the acquirer, from which the information should be obtained, and Ecommpay—for organising the interaction and addressing arising questions, including questions related to the information correctness.
4.  If the direct interaction between the specialists of your current acquirer and Ecommpay is not organised, receive the encrypted file with data from the acquirer and submit it to the specialists responsible for migration on the Ecommpay side. Contact your Ecommpay account manager to set up a communication channel with the dedicated Ecommpay specialists responsible for the data migration.

    When it comes to migrating data to the Ecommpay platform, this data is usually encrypted via the PGP \(Pretty Good Privacy\) algorithm; however, in certain cases, other methods can be used upon the coordination with the Ecommpay specialists.

    ```
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    
    mQINBF6dl0kBEADFrBtqZ7gXwTxPZXKFFJNPtickNW2lj7TigR+ymGR8ym+AOb9k
    /IJp7Ua7Rgw6vFD/puLdGv7RFIbMYtqGnQgBzN4b+TFVqUtLST4cL8vR3S5tvYof
    /YYY9PuqGaLWYdtg9PYtTQREe19gKhZPVi9PVjpnYLwnqGZnKYD9f76b8seQGUNS
    RMJ9RA2VjwLq0GcOP2k4s3pnNN+GJFdS/z/RAfBwyT++681irmXgVWOq//3yIkya
    WGRkVb+weY0Z3aoK++piMR55xr76l8aukOxb3ULJd1N5zhYMWACzZglla47rtCkC
    rWw2Y8aC/DVbU7+NLtyr58LlXs7CbOpbfMIt59VfM2vrt4JtPF/F+u+ahBqJ5g0j
    8aM0fhZASeS6m/1FRXAR6ArUIEuILlW91xk6C2nRNcnnrbm7uSTiWAaCrV719lSm
    h/DlNVubFjgsTZ+KbkCjsPza2q6QQc8PCzhWhu7cmxmQKVL1l17+tujQvxa5x74N
    9T4aizoOGXhZEKm33cReCGEga30WdZFstB1sfjDcNhxbBsHYPu15iVMDpo8BQSeb
    5Gt/rQD7Q0uk6IgwMfuuICCCsF695hUFRK7dvQUNEHB5biWrCec7Yl40XaY0EDMy
    0s3J/Niha049jT7Z+/RSqrv53BftdyI+UVJKn9rAGdKeiMPC31tAjCRW9QARAQAB
    tBppdHNlYyA8aXRzZWNAZWNvbW1wYXkuY29tPokCTgQTAQgAOBYhBFe/BlX1+HSg
    v2i/PfBgfCmIRnw0BQJenZdJAhsDBQsJCAcCBhUKCQgLAgQWAgMBAh4BAheAAAoJ
    EPBgfCmIRnw0v2wP/RGy9jAseKPNOk1NyEbuMTP7F3O/sYfgLKzMpl6TPp6q11Xn
    TPnepkukszZtn4ZwBV16fl5dcXXfM8gvfXgKgtBKr6XzNU9lTfGqTLcQJ5OzSSGY
    e7zxhE2NtQQmMVyARC4y+BzIYjyzn6ekVNh0lI61ZhluimSm+BWnm1TcE/ASS7a9
    ddI+FA93iupb/0l9EIZHn0tyf/+uj3SnMspCV8fFVDxSuTggbdOsZsfMa9MCXrHD
    2HYY2EfMhgVkDh+LvInrhAzgWLJmGiyS5VT6+v6hs3xpyILQUsi1SbVkPdF7jBiy
    LknMHj5AGmL5uIWANVLT/BMgyhUksuadqpo91O0KZf8K4c3PvToHw7UOQ7me15G0
    4mpInCNqPzaAz655Jc3eeUmJHGybTEUFX7MBlx/Fqvj7aTNIFStH7FPQq+a5HDGl
    5Y9jIfTFBwVCb4ngETERE6j/b8K+TCHGXo87t+OmMdxNc2vSSOWmM9c/PSlsKKCH
    Y2y78m3T2WpWwrhw7QYNpAhdPw4dVqGLcjXqFAhxcv4BAeaRYZwiqNdNNIq17Gch
    N6e7e8emPwFip0+ok5PLMDvfAfE3/LeoAfU+QCbaMticklgojxmWZAGU2nzoe9tq
    95jiDf1Rif4qJaixoTEoGaezBVcA73BW5zDRLbkppeCCT4pVUgpfTvJBAJknuQIN
    BF6dl0kBEADLNI2mOwmFWlvgKRUAtpbdaqmaTTmsVyoVl0VpLnOKnAxQDTReSfcV
    7G4NS0bSwnNIlxQsbtq5hUKsz/HYOS5fMvgFRIORUosOR80+Zz1QjGRC/UvWHoKs
    qsAs5vKRqhMOtQ+1KxYEhsyy8PZKBUgqo31q9FWkmgjR7urzlidRocutTI5vHNTR
    MODrjrhlPJ8nTp30935oFCML4eJXDV3eQWmCM9LahVj9bbSqGungdPafHPP1DLVR
    AUg+EONUW2/jM0jZwoJxafUBT3Is6XcLNNtB6DlX2N4ITOxE23CLl6B1M54gwTiv
    iF1bGV13h4K0XxrsQqw6OEX8K4B3MPd468NJn5GCoinGtMBQFT3uv6mzxTxtyVaG
    EI9H6i5ElAAIL7BqlbQI/ad40PVwe7mWWP0k8GawAf6y1298hPbkIhOvEjnMyKiv
    HpOWrnDEQPxKUvvjrh8n83r4yQWRI77vT3OYKbmQbEESsJgZnmMwJpjBswKjuwwm
    Td+7V45e0dL9YC6XQfIwV8VZugdYueuAVX5m4IdebzJQst8uvPXM2SH4jW44cDhs
    pw0Zs+++frCjoYw4PnNtVeZ2BBRGIyylCQxirNtyeEzd5lO2p04KmYJcCO79wmAM
    ZdkEeohh52SMe3xz/HrfrOZXdFeu83Cx/TMEzAbeGgf9SNTOfdViIQARAQABiQI2
    BBgBCAAgFiEEV78GVfX4dKC/aL898GB8KYhGfDQFAl6dl0kCGwwACgkQ8GB8KYhG
    fDSANg/8CFHIoWGGro7Wh//k8pNsfzdpUZPj4kNuKB2Hl/17Lj5Tz0ziQWis7uSI
    11pf+u0GttJ8MxzBn4XAnvvMA+LozoAu9i9OKMLrGAplr2EsMRBFA8+tMeZFdUmt
    pDA3bVCIp12/ERsxhzhd7eN6M0g/JxXkDKhvHTsDlsAJF+T+xeDPgQu+ejrKB8bb
    2fCIv1Ru6UNSCJ32ZbtEF9MlkODSumD+gVPQddM5E2OUmbuE02wFOcN7vGx2mAa6
    6HWUv2gK/FX8id82RSWkEvlV12xLu/BDWaSKddemBX357iwC3ho6EsWovbZfhFsw
    Yrw8WTz4eYOVw9rm4jbX82vCiztN8snrdx5vZ2H/F/0jAHB1YHLReFdsLAdRGfj6
    6MolppVGjCal/Q/JkqPQQpWGy3oSo3TbpbqKrWqaGTDWnb8+enocfBM5pjIo+Y3w
    diofU0meiCGgQs32LhuJV6kraUakYa0CEyhNeyVVqPPqUg8mqC/CEs12bExABEDI
    +3q6nA8OivWShBLVvmuKMYbQnO874VHJ0IF60sX6a5FIGi31QS2efcxYCcVD6sCU
    WD2s88/xYedyDNHWaUfl+fi9+7FRPhKixB2TlzARWN5m5D1Jc3rsZ/NlXfEk0m6j
    Xfgysvyy0abRlDIfFHv87ICIc8kNWtn4mIw9a6jbSDpAT/+16eQ=
    =jMHf
    -----END PGP PUBLIC KEY BLOCK-----
    
    ```

5.  After a verification file is received from the Ecommpay specialists is received at the provided email address, check whether the information in the file is complete and correct.

    **Note:** The verification file contains all parameters that were previously agreed on and is sent in the CSV format, with the password to access the file provided separately. Besides, if decided on step 2, separate verification files for tokens and COF purchases can be created and provided.

6.  Send an email to the Ecommpay specialists either confirming information correctness or reporting inconsistencies.

    If the information in the file is correct, the merchant can start using the migrated information after the confirmation. If inconsistencies or mistakes have been detected, the Ecommpay specialists compare the details in the file with those received from the previous acquirer and, depending on the outcome, proceed with the following:

    -   If the information does not match, they correct the details upon the coordination with the merchant.
    -   If the information matches, they recommend that the merchant contact the previous acquirer for updating the information and then provide the Ecommpay specialists with the updated details.
    **Note:** Processing of payments with the use of the migrated information via the Ecommpay platform is only possible after the confirmation of the information correctness is received from the merchant.

7.  Set up the usage of relevant information in the web service.

    Thus, for working with tokens, update their values \(replacing them by the ones generated in the payment platform\), and for working with COF purchases, set up the usage of new identifiers of payments and debits. After that, you are all set to work with the migrated information


Basic parameters for migration are covered below.Contact your Ecommpay account manager for additional parameters setup.

## Set of parameters for COF purchases {#en_gate_data_migration_cof_parameters}

The following table presents the basic set of parameters used to migrate COF purchases information.

### Project and customer identifiers {#section_xbx_3tt_2xb .section}

|Parameter|Description|
|---------|-----------|
|`project_id`|Identifier of the projectin the Ecommpay payment platform, to which the migrated information is related.

 Example: `42`

|
|`customer_id`  
 [required for verification](en_default_for_verification.md)

|Identifier of the customer in the web service.Must be a string of 255 or fewer characters.

 Example: `customer_17008`

|

### Payment card details {#section_hhl_rtt_2xb .section}

|Parameter|Description|
|---------|-----------|
|`pan`  
 [required for verification](en_default_for_verification.md)

|Number of the payment card.During migration, the number is used in its full form, while in the verification file, the number is masked and specified in the `card_number` parameter.

 Example: `4314220000000056`

|
|`card_holder`|Cardholder's first and last names, provided as they are specified on the card and with regards to the applied [restrictions](en_faq_payment_processing.md).

 Example: `ARTHUR EDDINGTON`

|
|`card_expiration_month`|Sequence number of the payment card expiration monthas an integer from 1 to 12.

 Example: `5`

|
|`card_expiration_year`|Sequence number of the payment card expiration year in the format of `YYYY`.

 Example: `2025`

|
|`card_type`|Indicator of the card brand that can be one of the following:

 -   `amex`—American Express
-   `maestro`—Maestro
-   `mastercard`—Mastercard
-   `visa`—Visa

|

### Basic details about a COF purchase {#section_a5j_wtt_2xb .section}

|Parameter|Description|
|---------|-----------|
|`description`|COF purchase description, specified as a string of 255 or fewer characters.

 Example: `Subscription for Cosmoshop mini games pack`

|
|`scheme_id`|Identifier of the initial operation of the COF purchase registration. This identifier is assigned by the global card network \(Mastercard or Visa\) and can be used when a COF purchase is registered in the European Economic Area.

 Examples: `MDS60JXCH0209` \(for Mastercard\) and `482269429345022` \(for Visa\)

|
|`register_payment_id`|Identifier of the record of a series of recurring debits in the merchant's web servicespecified as a string of 255 or fewer characters. If this parameter is not provided, the identifier is set in the payment platform automatically in the format of `Ecommpay–yyyymmddnnn` and sent to the merchant in the verification file.

 Example: `Ecommpay-20230515001`

|
|`status`|Status of the record of a series of recurring debits\([details](en_gate_payment_recurring_registration.md)\):-   `active`—further debits are awaited.
-   `canceled`—further debits are canceled.

If this parameter is not provided, the `active` status is assigned to the series of debits.

|
|`recurring_type`|Indicator of the COF purchase type\([details](en_Gate__saved_cards_payments_type.md)\):

 -   `U`—autopurchase
-   `R`—regular purchase

|

### Parameters of recurring debits {#section_x25_35t_2xb .section}

|Parameter|Description|
|---------|-----------|
|`amount`  
 [required for verification](en_default_for_verification.md)

|Amount of a single debit. Specified in minor currency units \(if applicable\).In the verification file, the amount is specified in the `recurring_amount` parameter.

 Example: `999`

|
|`currency`  
 [required for verification](en_default_for_verification.md)

|Code of the debits currency in the ISO 4217 alpha-3 format.In the verification file, the amount is specified in the `recurring_currency` parameter.

 Example: `USD`

|
|`start_date`  
 [required for verification](en_default_for_verification.md)

|Date on which debits should begin after the migration, specified in the `dd-mm-yyyy` format.

 Example: `01-06-2023`

|
|`start_time`  
 [required for verification](en_default_for_verification.md)

|Time at which debits should be performed, specified in the `hh–mm–ss` format.

 Example: `15-00-00`

|
|`period`  
 [required for verification](en_default_for_verification.md)

|Period used for calculating the interval of debits \(to set up recurring debits to be performed each *nth* number of days, weeks, or other periods\),with the following values allowed:

 -   `D`—day
-   `W`—week
-   `M`—month
-   `Q`—quarter
-   `Y`—year

 In case if alongside the `period` parameter, the `period_interval` parameter is not specified, the debits are respectively performed daily, weekly, monthly, quarterly, and yearly.

|
|`period_interval`|Multiplier used in relation to the `period` parameter for defining the interval of regular debits \(to set up recurring debits to be performed each *nth* number of days, weeks, or other periods, where the *nth* number is the interval\),with the allowed integer values from 1 to 100.

 For example, if the value `3` of the `period_interval` parameter and the value `W` of the `period` parameter are used, the debits should occur every 3 weeks.

|
|`scheduled_payment_id`|Identifier assigned to the payment within which scheduled debits are performed, specified as a string of 255 or fewer characters. If this parameter is not provided, the identifier is specified in the payment platform automatically in the format of `Ecommpay–yyyymmddnnn` and sent to the merchant in the verification file.

 Example: `Ecommpay-20230515001`

|

## Set of parameters for tokens {#en_gate_data_migration_token_parameters}

The following table presents the basic set of parameters used to migrate tokens information.

|Parameter|Description|
|---------|-----------|
|`project_id`|Identifier of the projectin the Ecommpay payment platform, to which the migrated information is related.

 Example: `42`

|
|`customer_id`  
 [required for verification](en_default_for_verification.md)

|Identifier of the customer in the web service.Must be a string of 255 or fewer characters.

 Example: `customer_17008`

|
|`pan`|Number of the payment card.During migration, the number is used in its full form, while in the verification file, the number is masked and specified in the `card_number` parameter.

 Example: `4314220000000056`

|
|`card_holder`|Cardholder's first and last names, provided as they are specified on the card and with regards to the applied [restrictions](en_faq_payment_processing.md).

 Example: `ARTHUR EDDINGTON`

|
|`card_expiration_month`|Sequence number of the payment card expiration monthas an integer from 1 to 12.

 Example: `5`

|
|`card_expiration_year`|Sequence number of the payment card expiration year in the format of `YYYY`.

 Example: `2025`

|
|`card_type`|Indicator of the card brand that can be one of the following:

 -   `amex`—American Express
-   `maestro`—Maestro
-   `mastercard`—Mastercard
-   `visa`—Visa

|

## Useful links {#en_gate_data_migration_links}

When using the capability of migrating information about COF purchases and payment card tokens, you can refer to the following sources that can come in handy:

-   [Interaction concepts](en_gate_interaction_organisation.md)—the article with general information about the interaction with the payment platform via Gate.
-   [Credential-on-file \(COF\) purchases](en_Gate__payments_on_saved_data.md)—the group of articles with information about working with COF purchases.
-   [Using tokens](en_Gate_Token.md)—the article with information about working with card tokens.
-   [Monitoring and performing payments](en_dbl_payments.md)—the article with information about processing and monitoring payments and operations via Dashboard.
-   [API Reference](https://api-developers.ecommpay.com/)—the Gate API interface specification.



---

# MO/TO payment processing {#en_Gate_moto .concept}

An article about the capability of processing via Gate purchases with the use of the customer's payment data received through email, phone, or other communication channels.

Mail Order/Telephone Order \(MO/TO\) payment is a CNP \(card-not-present\) payment when a cardholder provides payment card credentials via mail or telephone to perform a payment.

## The types of payments that support MO/TO payment processing {#section_c22_lkx_y2b .section}

The types of operations that support MO/TO functionality:

-   purchase with direct withdrawal of funds—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
-   purchase with direct withdrawal of funds by using saved data—[/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)
-   purchase with direct withdrawal of funds by using token—[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)
-   placing an authorisation hold—[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)
-   placing an authorisation hold by using saved card data—[/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)
-   placing an authorisation hold by using the token associated with the card details—[/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)
-   payment card verification by card number—[/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)
-   payment card verification by the token associated with the card details—[/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)

## MO/TO payment processing by using Gate {#section_ncq_xfx_y2b .section}

MO/TO payments are different from the usual ones. MO/TO payment is a type of CNP payments when both a payment card and a cardholder are not physically present at the moment the payment is made. The payment card credentials are provided by its holder by mail, telephone, fax or other means of communication to create an invoice.

To perform a MO/TO payment by using Gate, pass one of the necessary values of the moto\_type parameter in the payment object:

-   `1` for the Mail Order \(MO\) payment
-   `2` for the Telephone Order \(TO\) payment

## Passing the `cvv` parameter {#section_ct3_jkx_y2b .section}

If moto\_type=`1`, for Mastercard, Visa, and American Express the cvv parameter in the object card becomes optional. For other card types the parameter is mandatory.

If moto\_type=`2`, for Mastercardand American Express the cvv parameter in the object card becomes optional. For other card types the parameter is mandatory.

## Restrictions on MO/TO payment processing {#section_ffr_y4h_jfb .section}

To perform a MO/TO payment by using Maestro cards, you have to make sure that the country where the operation is performed matches the country where the card was issued and also be in the list of available countries. If these conditions are not met, the operation processing is declined. The countries available for MO/TO payments by using Maestro are listed in the following table.

|IRL|Ireland|
|FRA|France|
|GBR|United Kingdom|
|TUR|Turkey|

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Cardholder name verification {#en_gate_cardholder_name_verification}

An article about the capability of matching the spelling of the cardholder's name against the one held by the card issuer during payment processing via Gate.

## General information {#section_zq3_2q2_zhb .section}

When you perform verification of a payment card, you can also check if the spelling of the cardholder's name matches the one held by this card issuer. The Ecommpay payment platform supports this capability for Mastercard and Visa cards and carries out verification via Mastercard Name Validation Service\(NVS\) and Visa Account Name Inquiry\(ANI\)—the specialised services of these card networks.

The cardholder name verificationcapability can be applicable in various situations. For example, you can use it before issuing payouts or when working with unusual orders, and it also allows you to assess fraud and chargeback risks. It is supported for standard card payments, Apple Pay and Google Pay payments, and payments via the Mastercard MoneySend and Visa Direct services.

Using this capability fits within the payment instrument verification workflow \([details](en_gate_account_verification.md)\) and requires no additional action from the web service other than working with an extended set of parameters in the requests and callbacks \(more details [below](en_gate_cardholder_name_verification.md#section_rpp_v14_3fc)\). To enable this option, refer to your Ecommpay account manager.

## Special aspects and limitations {#section_td5_kdj_5yb .section}

When working with the cardholder name verification, consider the following special aspects and limitations:

-   Verification can be performed only when the card issuer supports integration with the service provided by the card network.
-   Issuers may have different verification rules that allow only full name match or full and partial name match.
-   The degree of match for cardholder name verification should be treated as reference information only.The final decision whether to accept or reject a payment based on this information lies in each case with the merchant.
-   The card network charges a fee for each completed name verification attempt.No fee is charged in the case when the verification attempt has been initiated but has not been completed. For information on current name verification fees, refer to your Ecommpay account manager.
-   The workflow of name verification includes matching the data held by the issuer against the data specified in the request for card verificationin the `first_name`, `middle_name`, and `last_name` parameters of the `customer` object. For each of these parameters, only the first 35 characters, excluding special characters and spaces, are verified.
-   The match result is sent to the web service in the final callback for the payment card verificationin the `name_validation_result` parameter of the `operation` object.

## Request format {#section_rpp_v14_3fc .section}

There are several things you need to consider when sending a request for the payment card verification with additional cardholder name check:

1.  To initiate each verification, send a separate POST request to one of the following endpoints:
    -   when performing verification by card number—`/v2/payment/card/account_verification` \([details](en_gate_account_verification.md)\)
    -   when performing verification by the token that is associated with payment card details—`/v2/payment/card/account_verification/token` \([details](en_gate_account_verification.md)\)
    -   when performing verification by using the Apple Pay method—`/v2/payment/applepay/account_verification` \([details](pm_applepay.md)\)
    -   when performing verification by using the Google Pay method—`/v2/payment/googlepay/account_verification` \([details](pm_googlepay.md)\)
2.  Each request must contain the following parameters in the `customer` object:
    -   `first_name`—customer first name \(mandatory\)
    -   `middle_name`—customer middle name or patronymic \(only if it was provided by the customer\)
    -   `last_name`—customer last name \(mandatory\)
    -   `name_validation`—flag indicating the need to verify the cardholder name \(required with the `true` value\)
3.  Additionally, any other parameters included in the specification of the endpoints mentioned above can be used.

``` {#codeblock_dxp_wqx_jfc .language-json}
{
  "general":{
    "project_id":874,
    "payment_id":"15538406111",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"192.0.2.0",
    "id":"customer_10",
    "first_name":"John",    
    "middle_name": "Jr",
    "last_name": "Doe",
    "name_validation": true //requesting name verification 

  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },
  //specifying the payment instrument details (as in specification)
}
```

## Callback format {#section_gq3_n12_pfb .section}

The payment card verification with additional verification of the cardholder's name uses the standard format for callbacks.For more information, see [Handling callbacks](en_platform_callbacks.md). In addition, the `operation` object in these callbacks includes the `name_validation_result` parameter. This parameter can have the following values:

-   `A`—the information provided in the request fully matches the information held by the issuer.
-   `B`—the information provided in the request partially matches the information held by the issuer.
-   `C`—the information provided in the request does not match the information held by the issuer.
-   `U`—the name matching is impossible \(because it is either not supported by the issuer or an error occurred\).

The following is an example of a callback where the `name_validation_result` parameter contains the full match indicator \(`A`\).

``` {#codeblock_dd2_1tx_jfc .language-json}
{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"success",
    "date":"2024-09-10T13:45:59+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"USD"
    },
    "description":"Add card"
  },
  "account":{
    "number":"431422******0056",
    "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type":"visa",
    "card_holder":"JOHN DOE",
    "id":8861226,
    "expiry_month":"09",
    "expiry_year":"2028"
  },
  "customer":{
    "id":"customer_10",
    "first_name":"John",
    "middle_name":"Jr",
    "last_name":"Doe"
  },
  "recurring":{
    "id":10505,
    "currency":"USD",
    "valid_thru":"2025-09-30T00:00:00+0000"
  },
  "operation":{
    "id":4314220000000056,
    "type":"account verification",
    "status":"success",
    "date":"2024-09-10T13:45:59+0000",
    "name_validation_result": "A",          //match result indicator
    "created_date":"2024-09-10T13:45:57+0000",
    "request_id":"5cb898347e62b2c1-52dac6c8c",
    "provider":{
      "id":120,
      "payment_id":"306449667",
      "date":"2024-09-10T13:45:59+0000",
      "auth_code":"188591",
      "endpoint_id":120
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"P9g0U+eF2QWs2A=="
}
```

## Useful links {#section_d55_sxv_chd .section}

The following articles can be useful for working with the cardholder name verification:

-   [Payment instrument verification](en_gate_account_verification.md)—about debiting a dummy \(zero\) amount or authorising a specific \(non-zero\) amount to verify a payment instrument via Gate, including information about request and callback formats in case of card payments.
-   [Standard card payments](en_pm_card_payments.md)—about card payments in the context of using payment methods.
-   [Apple Pay](pm_applepay.md)—about working with the Apple Pay method, including information about request and callback formats in case of payment instrument verification with this method via Gate.
-   [Google Pay](pm_googlepay.md)—about working with the Google Pay method, including information about request and callback formats in case of payment instrument verification with this method via Gate.
-   [Using Mastercard MoneySend and Visa Direct services](en_gate_money_transfer_services.md)—about performing money transfers via specialised services by Mastercard and Visa.
-   [Handling callbacks](en_platform_callbacks.md)—about working with callbacks to receive up-to-date information significant for processing of each payment.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Using Mastercard MoneySend and Visa Direct services {#en_gate_money_transfer_services}

An article about the capability of transferring funds between customers and merchants via the Mastercard MoneySend and Visa Direct services.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Overview {#en_gate_money_transfer_services_overview}

The Ecommpay payment platform supports the capabilities of Mastercard MoneySend and Visa Direct networks that significantly simplify transferring money between customers and merchants. These services offer the functionality that utilises specific operations to withdraw \(i.e. *debit*\) funds from the accounts of customers \(senders\) and to deliver \(i.e. *credit*\) funds to the accounts of customers \(recipients\).These debiting and crediting operations can be executed separately or combined, and since global card schemes require that the funds reach the target accounts in 30 minutes or less, using Mastercard MoneySend and Visa Direct services makes transferring funds fast and efficient as well as convenient for customers.

Main characteristics of these operations can be summed up as follows:

| |Debiting|Crediting|
|:-|:-------|:--------|
|Mastercard MoneySend operation|Funding transaction \(FT\)|Payment transaction \(PT\)|
|Visa Direct operation|Account Funding Transaction \(AFT\)|Original Credit Transaction \(OCT\)|
|Ecommpay platform equivalent operation|`sale`|`payout`|
|Available payment methods|-   Card payments
-   Apple Pay
-   Google Pay

|Card payments

|
|Available payment instruments|Mastercard or Visa cards|Mastercard or Visa cards|
|Operation can be cancelled after it has been processed

|+with certain time restrictions

|–|
|Use cases|-   Adding funds to the customer’s account in the merchant’s service.
-   The first step of the card-to-card money transfer \(with funds debited from the account of the sender\).

|-   A payout to a customer.
-   The second step of the card to card money transfer \(with funds credited to the account of the recipient\)

|

Since these operations are executed as `sale` and `payout` in the Ecommpay payment platform \(utilising the corresponding sets of required parameters\), you can initiate them in any interface that fits your needs: debiting operations can be initiated not only via Gate but also via Payment Pageand mobile SDKs while crediting operations can be initiated via Gate and Dashboard.

If you have any questions regarding the possible restrictions imposed by the global card schemes when these services are used and how to connect to them, refer to your Ecommpay account manager.

## Workflow {#en_gate_money_transfer_services_workflow}

### General information {#section_v5s_3tq_5wb .section}

Workflows of processing debiting and crediting operations via Gate are by and large identical to the workflows of processing [one-step purchases](en_gate_payment_sale.md) and [payouts](en_Gate_payout.md): the web service must send a request to initiate each of these operations, perform intermediate actions if they are demanded by the prescriptive callbacks received from the platform, and accept the final informational callback. When a card-to-card money transfer is processed, these two operations have to be initiated consecutively: first, the debiting operation and, once it has been completed, the crediting operation.

### Options to specify payment information {#section_kf3_vyq_5wb .section}

As in the case with other kinds of purchases and payouts in the Ecommpay payment platform, whenworking with debiting and crediting operations executed as part of the Mastercard MoneySend and Visa Direct services, you can choose from several options to specify payment card details:

-   *Actual card details*—in the request, pass the card number, expiry date, the first and last name of the cardholder, and CVV.
-   *Arbitrary saved card identifier*—in the request, pass the identifier associated with the corresponding card details in the payment platform \(for more information, see [Saving payment data](en_gate_saved_data.md)\).
-   *Standardised card token*—in the request, pass the token associated with the corresponding card details in the payment platform \(for more information, see [Using tokens](en_Gate_Token.md)\).

### Debiting {#section_qyl_51r_5wb .section}

To initiate the debiting of funds via Gate, the web service is required to do the following:

1.  Send a request to the `/v2/payment/\{payment method\}/sale[/selected option to specify payment information]` endpoint.
2.  If necessary, complete a procedure of the 3‑D Secure customer authentication \(for more information, see [3‑D Secure authentication](en_gate_payment_3ds.md)\).
3.  Receive a callback from the payment platform with the result of the debiting operation.

The format of the request for debiting is presented in [the following section](en_gate_money_transfer_services.md#section_zhh_dfr_5wb) of this article.

### Returning debited funds {#section_kxr_tcr_5wb .section}

In certain cases, you may need to return debited funds to the customer. From a technical standpoint, the cancellation of debiting is executed as [a refund](en_Gate_Refund.md) and is initiated with the request to the `/v2/payment/\{payment\_method\}/refund` endpoint. Keep in mind that according to the rules of the global card schemes only full payments can be refunded within limited time periods.

According to Visa rules, you can send the request to return debited funds only during the first 24 hours from the moment when the debiting has been completed while according to Mastercard rules this should be done within three business days. Upon expiration of these time limits, you have to contact the Ecommpay technical support to return debited funds to the customer.

### Crediting {#section_zmk_12r_5wb .section}

To initiate the crediting of funds via Gate, the web service is required to do the following:

1.  Send a request to the `/v2/payment/card/payout[/token]` endpoint.
2.  Receive a callback from the payment platform with the result of the crediting operation.

The format of the request for crediting is presented in [the following section](en_gate_money_transfer_services.md#section_rjj_4pr_5wb) of this article.

## Request format {#en_gate_money_transfer_services_format_request}

### Debiting {#section_zhh_dfr_5wb .section}

When creating a request for debiting, consider the following:

1.  The request must be sent to one of the following endpoints with the use of the HTTP POST method:
    -   when sending the actual card details—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
    -   when sending the saved card identifiers—[/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)
    -   when sending the card tokens—[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token);
    -   when Apple Pay or Google Pay is used to make a payment—[/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale) or [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale) respectively
2.  The request must contain the following objects and parameters:
    -   `general`—the object containing the general identification information of the request:
        -   `project_id`—the project identifier assigned by Ecommpay
        -   `payment_id`—the payment identifier unique within the project
        -   `signature`—the request signature generated after all required parameters have been specified \(for more information, see [Signature generation and verification](en_platform_signature.md)\)
    -   `payment`—the object containing the debiting information:
        -   `amount`—the amount to be debited from the customer’s \(sender's\) card in the smallest currency units
        -   `currency`—the currency code for the debited amount in ISO-4217 alpha-3
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation
    -   `customer`—the object containing the information about the customer \(sender\):
        -   `id`—the identifier of the customer within the project
        -   `ip_address`—the IP address of the customer
        -   `country`—the customer’s country code in ISO 3166-1 alpha- 2
        -   `address`—the customer's address, required when Visa cards are used
        -   `city`—the customer’s city \(or any other place of residence\), required when Visa cards are used
        -   `state`—the customer’s state or province code, required when the debited funds are credited to Visa cards issued in the USA or Canada
        -   `phone`—the customer’s phone number, required when the debited funds are credited to Visa cards issued in Brazil or Qatar
        -   `account_id`—the customer’s wallet number, required when Mastercard cards are used
        -   `first_name`—the customer's first name, required when Apple Pay or Google Pay is used
        -   `last_name`—the customer's last name, required when Apple Pay or Google Pay is used
3.  The request must contain the following information about the sender’s \(customer’s\) card:
    -   When sending the actual card details, include the following parameters in the `card` object:
        -   `pan`—the card number
        -   `year`—the card expiration year
        -   `month`—the card expiration month
        -   `card_holder`—the first and last name of the cardholder \(as specified on the card\)
        -   `cvv`—the card verification code
    -   When sending the saved card identifier, include the following parameters in the `card` object:
        -   `saved_account_id`—the identifier associated with the corresponding card details in the payment platform
        -   `cvv`—the card verification code
    -   When sending the token, include the following parameters:
        -   `token`—the token associated with the corresponding card details in the payment platform
        -   `cvv`—the card verification code
4.  The request must contain the following information about the recipient and their payment instrument:
    -   When sending the recipient’s wallet information, include the following parameters in the `recipient` object:
        -   `wallet_id`—the wallet number
        -   `wallet_owner`—the first and last name of the wallet owner
        -   `country`—the wallet owner’s country code in ISO 3166-1 alpha- 2, required when a Mastercard is linked to this wallet
    -   When sending the card details, include the following parameters in the `recipient` object:
        -   `pan`—the recipient's card number
        -   `card_holder`—the first and last name of the cardholder \(as specified on the card\)
        -   `day_of_birth`—the recipient's date of birth in `DD-MM-YYYY` format, required if a Visa card is used to receive the payment
5.  In some cases, the request must contain the following additional information about the recipient in the `recipient` object:
    -   When sending the details of a Visa card issued in Canada:
        -   `country`—the recipient’s country code in ISO 3166-1 alpha-2
        -   `city`—the recipient’s city \(or any other place of residence\)
        -   `state_code`—the recipient’s state or province code
    -   When sending the details of a Visa card issued in Australia, Canada, or New Zealand—the recipient’s address in the `address` parameter.
6.  If necessary, you can also add any other additional parameters and objects specified in the API specification.

Thus, a correct request for debiting funds contains project and payment identifiers, the signature, the amount to be debited and the corresponding currency code, information about the sender, and the payment information of the sender and the recipient specified as one of the options described above.

The following example contains the body of the request for debiting from a Visa with the funds intended for subsequent crediting to a Mastercard.

```language-json
{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225,
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18"
  },
//when sending the details of the sender's card:
  "card":{
    "pan":"4314220000000056",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//when sending the saved card identifier:
  "card":{
    "saved_account_id": 21121375,
    "cvv": "334"
  },
//when sending the card token:
    "token":"f365bb1729f9b72fd9c09703a751c979f3becc67",
    "cvv":"334",
//when sending the details of the recipient's card:
"recipient":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  }
//when sending the information about the recipient's wallet:
"recipient":\{
    "wallet\_id":"WID20071304",
    "wallet\_owner":"Fran Petrarca",
    "country":"IT"
  \}
}
```

### Crediting {#section_rjj_4pr_5wb .section}

When creating a request for crediting, consider the following:

1.  The request must be sent to one of the following endpoints with the use of the HTTP POST method:
    -   when sending the actual card details—[/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout)
    -   when sending the card tokens—[/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token)
2.  The request must contain the following objects and parameters:
    -   `general`—the object containing the general identification information of the request:
        -   `project_id`—the project identifier assigned by Ecommpay
        -   `payment_id`—the payment identifier unique within the project
        -   `signature`—the request signature generated after all required parameters have been specified \(for more information, see [Signature generation and verification](en_platform_signature.md)\)
    -   `payment`—the object containing the crediting information::
        -   `amount`—the amount to be credited the recipient's card in the smallest currency units
        -   `currency`—the currency code for the credited amount in ISO-4217 alpha-3
        -   `cryptocurrency_type`—the indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
            -   `cbdc`—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority
            -   `stablecoins_fiat_backed`—a fiat-backed digital asset with reserves held by a licensed financial institution
            -   `native_tokens`—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments
            -   `other`—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation
    -   `customer`—the object containing the information about the sender:
        -   `id`—the identifier of the customer \(sender\) within the project
        -   `ip_address`—the IP address of the customer
3.  The request must contain the following information about the recipient’s card:
    -   When sending the card details, include the following parameters in the `card` object:
        -   `pan`—the recipient's card number
        -   `card_holder`—the first and last name of the cardholder \(as specified on the card\)
    -   When sending the token, include the following parameters:
        -   `token`—the token associated with the corresponding card details in the payment platform
4.  The request must contain the following information about the sender in the `sender` object:
    -   Specify payment instrument information in one of the following parameters:
        -   `pan`—the sender's card number
        -   `wallet_id`—the sender's wallet number
    -   Specify information about the sender, preferably including the following parameters:
        -   `country`—the sender’s country code in ISO 3166-1 alpha- 2
        -   `address`—the sender's address, required when Visa cards are used
        -   `city`—the sender’s city \(or any other place of residence\), required when Visa cards are used
        -   `first_name`—the sender's first name
        -   `last_name`—the sender's last name
        -   `state`—the sender’s state or province code, required when funds are credited to Visa cards issued in the USA or Canada
        -   `zip`—the sender’s postal code, required when Mastercard cards are used
        -   `day_of_birth`—the sender's date of birth in the DD-MM-YYYY format, recommended when Visa cards are used
        -   `phone`—the sender’s phone number, required when funds are credited to Visa cards issued in Brazil or Qatar
5.  The request must contain the following information about the recipient in the `recipient` object:
    -   `first_name`—the first name of the recipient
    -   `last_name`—the last name of the recipient
6.  If necessary, you can also add any other additional parameters and objects specified in the API specification.

Thus, a correct request for crediting funds contains project and payment identifiers, the signature, the amount to be credited and the corresponding currency code, information about the sender and the recipient, and the payment information of the sender and the recipient specified as one of the options described above.

The following example contains the body of the request for crediting funds to a Mastercard with the funds previously debited from a Visa.

```language-json
{
  "general":{
    "project_id":91348,
    "payment_id":"135113521355",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225"
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "recipient":{
    "first_name":"Fran",
    "last_name":"Petrarca"
  },
  "sender":{
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18",
    "first_name":"Gio",
    "last_name":"Boccaccio",
    "day_of_birth":"16-06-1313"
  },
//when sending the details of the recipient's card:
  "card":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  },
//when sending the card token:
    "token": 1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713,
//when sending the details of the sender's card:
"sender":{
    "pan":"4314220000000056"
  }
//when sending the number of the sender's wallet:
"sender":\{
    "wallet\_id":"WID16061313" 
  \}
}
```

## Callback format {#en_gate_money_transfer_services_format_callback}

Results of processing Mastercard MoneySend and Visa Direct operations are communicated in callbacks of standard format. To learn more about the callback format, see [Handling callbacks](en_platform_callbacks.md).

```language-json
    {
        "project_id": 91348,
        "payment": {
            "id": "135113521354",
            "type": "purchase",
            "status": "success",
            "date": "2022-02-22T19:52:14+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056",
            "type": "visa",
            "token": "f365bb1729f9b72fd9c09703a751c979f3becc67",
            "country": "IT",
            "bank": "Intesa Sanpaolo SpA",
            "product": "debit"
        },
        "customer": {
            "id": "16061313"
        },
        "operations": [
            {
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521354",
                    "auth_code": "661786",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T19:52:14+0000"
                },
                "rrn": "305440290856",
                "region": "domestic",
                "code": "0",
                "message": "Success",
                "eci": "05",
                "id": 52901540107953,
                "type": "sale",
                "status": "success",
                "date": "2022-02-22T19:52:14+0000",
                "created_date": "2022-02-22T19:51:18+0000",
                "request_id": "a51091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-d7bc0c44525",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                }
            }
        ],
        "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
    }
```

```language-json
    {
        "project_id": 91348,
        "payment": {
            "id": "135113521355",
            "type": "payout",
            "status": "success",
            "date": "2022-02-22T20:01:36+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "541333******0019",
            "type": "mastercard",
            "token": "1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713"
        },
        "customer": {
            "id": "16061313"
        },
        "issuer_name": "UniCredit SpA",
        "product_name": "World Mastercard",
        "country": "IT",
        "card_product_type": "debit",
        "card_holder": "Fran Petrarca",
        "operations": [
            {
                "type": "payout",
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521355",
                    "auth_code": "309410",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T20:01:35+0000"
                },
                "status": "success",
                "date": "2022-02-22T20:01:36+0000",
                "rrn": "301360291143",
                "created_date": "2022-02-22T20:01:34+0000",
                "region": "domestic",
                "request_id": "fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001711",
                "code": "0",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "message": "Success",
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "id": 5013600010130727
            }
        ],
        "signature": "hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
    }
```



---

# Debt repayment {#en_Gate_debt_repayments}

An article about the capability of processing loan repayments via Gate.

## General information {#section_knc_3mq_4mb .section}

*Debt repayment* is a type of purchase from the customer's card intended for payment of a loan or debt. This type of payment is available for merchants providing microfinance services with the category code `6012` or `6051`.

Debt repayment can be made as a one-time purchase, registration of a COF payment, or card verification operation. If an MFI is registered in the United Kingdom \(for Mastercard payments\) or in the European region according to Visa regulations \(for Visa payments\) in addition to the required objects and parameters, the MFI account number and additional customer data must be specified in the request:

-   payment—object containing payment data:
    -   debt\_account—the merchant account number for debiting funds from the customer's card in order to repay the debt. Latin letters and numbers are allowed, the maximum length is 10 characters
-   customer—object containing customer data:
    -   first\_name—first name
    -   last\_name—last name
    -   day\_of\_birth—date of birth, in the DD-MM-YYYY format
    -   zip—postal address code \(mandatory for the UK\).

This functionality is not available for payments with American Express cards.

If the parameter is not specified in the request, a callback containing this parameter is sent for additional payment information submission \(for more details, see [Submission of additional payment information](en_Gate_Clarification.md)\).

```language-json
{
    "general": {
      "project_id": 200,
      "payment_id": "payment_id",
      "signature": "PJkV8ej\/UG0Di8NN5...=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR",
      "debt_account": "897896541"
    },
    "customer": {
      "id": "123",
      "ip_address": "1.1.1.1"
      "first_name": "John",
      "last_name": "Johnson",
      "day_of_birth": "12-05-1990",
      "zip": "SW1W 0NY"    
    } 
}
```

If the debt re payment is made by the registration of a COF payment—you do not need to pass additional parameters in requests for payment processing—they will be taken from the initial request for registration.

For more information about this functionality and how to enable it, refer to the Ecommpay key account manager.

## Mastercard restrictions {#section_jzh_kmq_4mb .section}

According to Mastercard requirements, this functionality is available to merchants from the United Kingdom only with the category code `6012`. For all other countries both `6012` or `6051` codes are available. It is prohibited to repay debts from credit and prepaid cards if the country of issue of the card and registration of the merchant is the United Kingdom.

## Visa restrictions {#section_gb2_lmq_4mb .section}

According to Visa requirements, merchants from the United Kingdom who accept payment of overdue debts must have the category code `6051`. In other cases and for all other countries both `6012` or `6051` codes are available. It is prohibited to repay debts from credit cards.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Using addendum with airline tickets data {#en_gate_addendum}

An article about the capability of using the extended set of parameters \(financial detail addendum\) when processing air travel payments via Gate.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Overview {#en_gate_addendum_overview}

To support and further develop various economic industries, global card networks implement specialised incentive programs that offer an additional layer of protection and preferential treatment to merchants in these industries. For example, merchants in the tourist industry with an eligible MCC \([Merchant Category Code, MCC](en_glossary.md) can receive certain benefits if they ensure passing information about their specific services in the *financial details addendum* included in payment requests.

The Ecommpay payment platform supports working with *addendum* parameters that allow passing information about travel industry services purchased with the use of Mastercard and Visa cards. It includes purchases of airline tickets and additional services within these booked trips. Such travel itinerary information is passed in the corresponding payment request in the `addendum` object and includes data organised according to the specification.

In some cases, merchants may need to specify extended information about travel itineraries and booked trips differently\(for example, when the MCC of the merchant does not fall within the eligible range determined by the card networks, but their business processes require receiving itinerary information together with the information about payments\). For such instances, the platform offers the capability of working with the `booking_info` object \([details](en_gate_additional_data.md)\).

Using addendum with airline tickets data is available by default to merchants with the eligible MCCs.The extended set of parameters that can be used for such purpose is described further in this article. If a merchant with an ineligible MCC attempts to use these parameters, the payment will be declined. If you have questions regarding the relevant programs offered by card networks and about the preferences that are available in each specific case due to regional specifics or other reasons as well as questions about using specialised processing scenarios and specific types of `addendum` objects, contact your Ecommpay account manager.

## Specifying information about airline tickets {#en_gate_addendum_airline}

### Restrictions {#section_f12_bzv_n3c .section}

You can pass information about booked airline tickets to participate in incentive programs offered by the card networks if your MCC falls within the range of `3000`–`3350` or equals `4511`. If `addendum` objects are passed in the payment requests by merchants with other MCCs, payments will be declined with the `310` response code.

To pass similar data for your own needs \(with other MCCs\), you can use the `booking_info` object \([details](en_gate_additional_data.md)\).

### Data format {#section_id2_czv_n3c .section}

Airline tickets data should be specified in the initial requests for processing payments, in the `airlines` JSON object nested in the `addendum` object. For each ticket, you should send a separate payment request.

To provide general information about the passenger and the ticket, use the parameters of the `airlines` object. To provide information specific to an individual leg of the trip, use the `trip_legs` object that allows you to pass information about up to four legs of the trip using the `trip_leg<legNr>` object, with `<legNr>` being the sequence number of the leg within the trip itinerary.

```language-json
{
  "addendum": {
    "airlines": {
      "ticket_number": "1055526005625",
      "passenger_name": "William Herschel",
      "customer_ref": "K7XT2A",
      "ticket_issuer_code": "KL"
      "ticket_issue_date": "2025-12-24",
      "travel_agency_code": "12345678",
      "travel_agency_name": "Deep Sky Tours",
      "restricted_ticket_indicator": true,
      "computerized_reservation_system": "SABR",
      "total_fare_amount": 15000,
      "total_tax_amount": 2000,
      "total_fees_amount": 1000,
      "trip_legs": {     \\ Object with information about the legs of the journey
        "trip_leg1": {   \\ Object with informaiton about the first leg of the journey
          "flight_number": "3142",
          "carrier_code": "KL",
          "departure_airport": "AMS",
          "departure_at": "2026-12-25T15:30:25+01:00",
          "destination_airport": "JFK",
          "arrival_at": "2026-12-25T17:45:25-05:00",
          "stop_over_code": true,
          "service_class": "Y",
          "fare_bassis": "Y0SVR7",      
          "exchange_ticket": "3141592653589",
          "conjunct_ticket": "6626070151034",
          "coupon_number": "1",
          "endorsements_restr": "No changes allowed"
        },
        "trip_leg2": {   \\ Object with informaiton about the second leg of the journey
          "flight_number": "1054",
          "carrier_code": "DL",
          "departure_airport": "JFK",
          "departure_at": "2026-12-25T22:45:25-05:00",
          "destination_airport": "LHR",
          "arrival_at": "2026-12-26T10:55:25+00:00",
          "stop_over_code": false,
          "service_class": "K",
          "fare_bassis": "KHCLS7",
          "coupon_number": "2",
          "endorsements_restr": "Changes allowed"
        }
      }
    }
  }
}
```

The `airlines` object can be passed in the requests sent to various endpoints, with its schema specified in the API and its location in the request payload structure as defined by the endpoint specification.

-   for one-time one-step purchases:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)—with payment details provided as is or via the network tokens
    -   [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)—with payment details provided via the saved card identifiers
    -   [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)—with payment details provided via the internal tokens generated in the platform
-   for one-time two-step purchases:
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)—with payment details provided as is or via the network tokens
    -   [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)—with payment details provided via the saved card identifiers
    -   [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)—with payment details provided via the internal tokens generated in the platform

### Parameters {#section_i1r_czv_n3c .section}

The `airlines` object can include the following objects and parameters.

|Parameter|Description|tree|
|---------|-----------|----|
|`ticket_number`  
 string, required

|Number of the issued ticket.

 Can include basic Latin letters and numbers, cannot exceed 15 characters.

 Example: `1055526005625`

|1|
|`passenger_name`  
 string, required

|First name and last name of the passenger to whom the ticket is issued.

 A string of up to 20 characters long.

 Example: `William Herschel`

|2|
|`customer_ref`  
 string, required

|Identifier of the passenger record in the reservation system.

 As a rule, it is the PNR \(Passenger Name Record\) locator. Can include basic Latin letters and numbers, cannot exceed 25 characters.

 Example: `K7XT2A`

|3|
|`ticket_issuer_code`  
 string, required

|Two-character code of the airline that issued the ticket \(according to the IATA classification\).

 Example: `KL`

|4|
|`ticket_issue_date`  
 string, required

|Date when the ticket was issued in the `YYYY-MM-DD` format \(according to [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)\).

 Example: `2025-12-24`

|5|
|`travel_agency_code`  
 string, optional

|Code of the travel agency that issued the ticket.

 This code is received as a result of accreditation from one of the professional associations \(IATA, ARC, or other\).

 Can include basic Latin letters and numbers, cannot exceed 8 characters.

 Example: `12345678`

|6|
|`travel_agency_name`  
 string, optional

|Name of the travel agency that issued the ticket.

 Can include basic Latin letters and numbers, cannot exceed 25 characters.

 Example: `Deep Sky Tours`

|7|
|`restricted_ticket_indicator`  
 boolean, optional

|Indicator that specifies refund restrictions applied to the ticket.

 Possible values:

 -   `true`—non-refundable
-   `false`— refundable

 Example: `true`

|8|
|`computerized_reservation_system`  
 string, optional

|Code of the computerised reservation system, may be needed for payments in Germany.

 Possible values:

 -   `BLAN`—Dr. Blank
-   `DALA`—Covia-Apollo
-   `DATS`—Delta
-   `DERD`—DER
-   `PARS`—TWA
-   `SABR`—Sabre
-   `STRT`—Start
-   `TUID`—TUI

 Example: `SABR`

|9|
|`total_fare_amount`  
 integer, optional

|Amount charged by the airline for transporting the passenger and their luggage \(i.e. free luggage allowance\), in the smallest currency unit.

 Example: `15000`

|10|
|`total_tax_amount`  
 integer, optional

|Amount of the tax included in the payment amount, in the smallest currency unit.

 Can be the sales tax, the VAT, or any other similar tax.

 Example: `2000`

|11|
|`total_fees_amount`  
 integer, optional

|Total amount of fees charged, in the smallest currency unit.

 Example: `1000`

|12|
|`trip_legs`  
 object, required

|Object with information about the legs of the journey.

 Must contain information about at least one flight in the nested `trip_leg<legNr>` object and can include up to four `trip_leg<legNr>` objects

|13|
|`trip_leg<legNr>`  
 object, required

|Object that contains information about the leg of the journey \(the segment of the flight itinerary between the two consecutively planned stops\)|13-1 13|
|`flight_number`  
 string, required

|The flight number assigned by the carrier that operates the flight, without the airline code.

 Can include basic Latin letters and numbers, cannot exceed 5 characters

 Example: `3142`

|13-1-1 13-1|
|`carrier_code`  
 string, required

|Two-character code of the carrier that operates the flight \(according to the IATA classification\).

 Example: `KL`

|13-1-2 13-1|
|`departure_airport`  
 string, required

|Three-letter code of the departure airport \(according to the IATA classification\).

 Example: `AMS`

|13-1-3 13-1|
|`departure_at`  
 string, required

|Date and time of the planned departure in the `YYYY-MM-DDThh:mm:ss±hh:mm` format \(according to [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)\).

 Example: `2026-12-25T15:30:25+01:00`

|13-1-4 13-1|
|`destination_airport`  
 string, required

|Three-letter code of the destination airport \(according to the IATA classification\).

 Example: `JFK`

|13-1-5 13-1|
|`arrival_at`  
 string, required

|Date and time of the planned arrival in the `YYYY-MM-DDThh:mm:ss±hh:mm` format \(according to [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)\).

 Example: `2026-12-25T17:45:25-05:00`

|13-1-6 13-1|
|`stop_over_code`  
 boolean, required

|The indicator specifying whether it is a connecting flight.

 Possible values:

 -   `true`—connecting flight
-   `false`—direct flight

 Example: `true`

|13-1-7 13-1|
|`service_class`  
 string, required

|One-letter code indicating the service class \(according to the IATA classification\).

 -   R—Supersonic
-   P—First Class Premium
-   F—First Class
-   A—First Class Discounted

 -   J—Business Class Premium
-   C—Business Class
-   D—Business Class Discounted
-   I—Business Class Discounted
-   Z—Business Class Discounted

 -   W—Economy/Coach Premium
-   S—Economy/Coach
-   Y—Economy/Coach
-   B—Economy/Coach Discounted
-   H—Economy/Coach Discounted
-   K—Economy/Coach Discounted
-   L—Economy/Coach Discounted
-   M—Economy/Coach Discounted
-   N—Economy/Coach Discounted
-   Q—Economy/Coach Discounted
-   T—Economy/Coach Discounted
-   V—Economy/Coach Discounted
-   X—Economy/Coach Discounted

 Example: `D`

|13-1-8 13-1|
|`fare_bassis`  
 string, required

|Code indicating the fare assigned by the carrier.

 Can include basic Latin letters and numbers, cannot exceed 6 characters.

 Example: `Y0SVR7`

|13-1-9 13-1|
|`exchange_ticket`  
 string, optional

|Number of the ticket that was replaced by the current ticket

 Can include basic Latin letters and numbers, cannot exceed 15 characters

 Example: `3141592653589`

|13-1-10 13-1|
|`conjunct_ticket`  
 string, optional

|Number of the conjunction ticket.

 Issued when the flight includes more than four trip legs and the tickets for this flight are linked together. Can include basic Latin letters and numbers, cannot exceed 15 characters.

 Example: `6626070151034`

|13-1-11 13-1|
|`coupon_number`  
 string, optional

|Number of the flight coupon, corresponds to the number of the trip leg.

 Example: `1`

|13-1-12 13-1|
|`endorsements_restr`  
 string, optional

|Added notation to specify any relevant information about various restrictions, additional data, and endorsement information \(indicating whether the flight coupon can be accepted by another carrier\).

 A string of up to 20 characters.

 Example: `No changes allowed`

|13-1-13 13-1S|



---

# Specifying extended purchase data for subsequent merchant use {#en_gate_additional_data}

An article about the capability of capturing relevant purchase information via Gate for internal merchant use.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Introduction {#en_gate_additional_data_overview}

In addition to specifying required and provider-recommended parameters inpayment requests, merchants sometimes need to pass data that is related to specific payments and their statuses andthat can be subsequently used by merchantsat their discretion. For this purpose, the Gate API includes the parameters that allow passing various data in requests and receiving these data together with other information in final callbacks.

**Note:** When processing payments via Payment Page, you can use [similar capabilities](en_pp_additional_data.md).

## Specifying booking data {#en_gate_booking_data}

### Overview {#section_eqc_4gh_h1c .section}

The `booking_info` object allows you to keep track of booking information relevant to a certain payment and receive this information in callbacks from the payment platform. In comparison to specifying the addendum with itinerary data \([details](en_gate_addendum.md)\) utilised in certain branches of travel industry, this capability can be applied in a wider range of use cases \(for example, to specify information about booking concert tickets\) and with more flexibility as there are no restrictions by MCC \([Merchant Category Code, MCC](en_glossary.md)\). At the same time, using the `booking_info` object may not offer the advantages that are available for addendum data capabilities, so if you have more questions concerning the use of these capabilities, refer to your Ecommpay account manager for more details.

The `booking_info` object can be used for almost all types of paymentsmade with cards, Apple Pay,Click to Pay, and Google Pay, including one-time purchases, unscheduled COF purchases, and payment instrument verification.

**Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` object containing information about the start and end dates of the booked service \(in the`start_date` and `end_date` parameters\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

### Use case {#section_qkq_ryl_h1c .section}

Here is an example of a use case when a merchant in the music festival industry needs to:

-   collect and process data about music festival tickets booked by the customers.
-   Provide the company's employees with the timely access to such information about each customer.

For this purpose, the following workflow is set up:

1.  Each request to Gate sent from the web service contains the following information in the `booking_info` object.
    -   The `bookers` array with the information about the customers for whom the service is booked. Each element of this array contains:
        -   `first_name`—the name of the customer provided at the time of booking
        -   `last_name`—the last name of the customer provided at the time of booking
        -   `email`—the email provided at the time of booking
    -   The `items` array with the information about separate services included in the booking. Each element of this array contains:
        -   `description`—description of the service included in the booking
        -   `start_date`—starting date of the service included in the booking
        -   `end_date`—ending date of the service included in the booking
    -   Parameters with other details of the booking:

        -   `start_date`—starting date of the booked service
        -   `end_date`—ending date of the booked service
        -   `description`—a free-form description of the booked service
        -   `total`—the total cost of the booking
        -   `pax`—the number of people per booking
        -   `reference`—the booking reference, which can be the URL, the name of the booked service, or its code in the merchant web service
        -   `id`—the identifier of the booking, unique in the merchant web service
        **Note:** Keep in mind that the standalone parameters `start_date` and `end_date` of the `booking_info` object are intended for specifying the starting and ending dates of the booking as a whole, while parameters `start_date` and `end_date` of the `items` array are intended for specifying the starting and ending dates of the separate services included in the booking.

        **Warning:** The value of parameters `total` and `pax` must be greater than `0`.

2.  When a relevant operation has been processed, the information specified in the `booking_info` object is passed to the merchant web service in the final callbackand can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the operation data.

### Setup {#section_jcp_hkm_h1c .section}

The capability of using the `booking_info` object in requests and receiving booking information in callbacks \(with standard format\) is available by default and does not require any specific setup.

### Data format {#section_nvb_nlm_h1c .section}

The `booking_info` object can be specified in requests to different endpoints and callbacks with operation results. Its structure is provided in the [BookingInfo](https://api-developers.ecommpay.com/api.html#/7f6ce1c65f45f-booking-info) schema and its location in the request structure can be found in a particular endpoint specification.

-   One-time one-step purchases:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)—when specifying the actual card details
    -   [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)—when specifying the saved card identifier
    -   [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)—when specifying the token associated with the card
-   One-time two-step purchases:
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)—when specifying the actual card details
    -   [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)—when specifying the saved card identifier
    -   [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)—when specifying the token associated with the card
    -   [/v2/payment/card/incremental](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-incremental)—when sending a request to increase the amount previously authorised as part of performing a two-step purchase
-   Payment link purchases
    -   [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)—without specifying the card details in the request
    -   [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create)—when specifying the token associated with the card
-   COF purchases:
    -   [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring)
-   Payment instrument verification:
    -   [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)—when specifying the actual card details
    -   [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)—when specifying the token associated with the card
-   Purchase refund:
    -   [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund)

-   [/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale)—for one-time one-step purchases
-   [/v2/payment/applepay/auth](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-auth)—for one-time two-step purchases
-   [/v2/payment/applepay/recurring](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-recurring)—for COF purchases
-   [/v2/payment/applepay/account\_verification](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-account-verification)—for payment instrument verification
-   [/v2/payment/applepay/refund](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-refund)—for purchase refunds

-   [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale)—for one-time one-step purchases
-   [/v2/payment/googlepay/auth](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-auth)—for one-time two-step purchases
-   [/v2/payment/googlepay/recurring](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-recurring)—for COF purchases
-   [/v2/payment/googlepay/account\_verification](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-account-verification)—for payment instrument verification
-   [/v2/payment/googlepay/refund](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-refund)—for purchase refunds

In final callbacks with the operation result information, the data that was specified in the `booking_info` object of the request is passed in the `booking info` object.

```language-json
"booking_info": {
  "start_date": "12-08-2026",
  "end_date": "14-08-2026",
  "description": "Sideris music festival full pass",
  "total": 200000,
  "pax": 2,
  "bookers": [
     {
        "first_name": "William",
        "last_name": "Herschel",
        "email": "rsfellow@mail.com"
     },
     {
        "first_name": "Caroline",
        "last_name": "Herschel",
        "email": "salariedastronomer@mail.com"
     }
  ],        
  "items":[
     {
        "description": "VIP Arrival",
        "start_date": "12-08-2026",
        "end_date": "12-08-2026"
     },
     {
        "description": "Hotel",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "Concerts",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "VIP Departure",
        "start_date": "14-08-2026",
        "end_date": "14-08-2026"
     }
  ],
  "reference": "musicfestlink",
  "id": "83"
}
```

```language-json
{
    "payment": {
        "date": "2024-01-24T06:24:45+0000",
        "method": "card",
        "id": "FESTIVAL_PASS_1781",
        "sum": {
            "amount": 0,
            "currency": "EUR"
        },
        "type": "purchase",
        "status": "refunded",
        "description": "FESTIVAL_PASS_1781"
    },
    "project_id": 111738,
    "customer": {
        "id": "musicaficionado_83"
    },
    "account": {
        "number": "551115******1822",
        "token": "7123ba1f24f16a115f3390a9",
        "type": "mastercard",
        "card_holder": "WILLIAM HERSCHEL",
        "expiry_month": "08",
        "expiry_year": "2030"
    },
    "booking info": \{    // Object with the booking information
        "start\_date": "12-08-2026",
        "end\_date": "14-08-2026",
        "description": "Sideris music festival full pass",
        "total": 200000,
        "pax": 2,
        "bookers": \[
          \{
            "first\_name": "William",
            "last\_name": "Herschel",
            "email": "rsfellow@mail.com"
          \},
          \{
            "first\_name": "Caroline",
            "last\_name": "Herschel",
            "email": "salariedastronomer@mail.com"
          \}
        \],        
        "items": \[
          \{
            "description": "VIP Arrival",
            "start\_date": "12-08-2026",
            "end\_date": "12-08-2026"
          \},
          \{
            "description": "Hotel",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "Concerts",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "VIP Departure",
            "start\_date": "14-08-2026",
            "end\_date": "14-08-2026"
          \}
        \],
        "reference": "musicfestlink",
        "id": "83"
    \},
    "operation": {
        "provider": {
            "payment_id": "0010000124258736",
            "auth_code": "",
            "endpoint_id": 414,
            "id": 414
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "id": 55386010114429,
        "type": "refund",
        "status": "success",
        "date": "2024-01-24T06:24:45+0000",
        "sum_initial": {
            "amount": 200000,
            "currency": "EUR"
        },
        "created_date": "2024-01-24T06:24:43+0000",
        "request_id": "abcaf52323381a-d988c158cc4b43046-00055387"
    }
}
```

## Specifying other extended purchase data {#en_gate_merchant_data}

### Overview {#section_lhs_1xx_pzb .section}

The `merchant.data` parameter can be used for keeping track of extended information about the order, applying promotions and bonus points, and other relevant data.In addition, the value of this parameter can be combined with the information passed in the `payment.description` parameter and the receipt information passed in the `receipt_data` object. As a result, all necessary data can be provided in callbacks without passing certain pieces of information multiple times in different parameters.

### Use case {#section_dbs_bxx_pzb .section}

Here is an example of a use case when a merchant in the video game industry needs to:

-   collect and process data about add-on services that the gamers purchase as they play.
-   Provide the company's employees with the timely access to such information about each customer.

Merchant specialists in charge of the integration inform the Ecommpay account manager about these requirements.As a result, the following workflow is devised and set up:

1.  Each request sent from the merchant web service to Gate contains information about the purchased services—passed as a JSON object in the `data` parameter of the `merchant` object.

    The `data` string includes the following:

    -   The `items` array in which each element contains the SKU \(`sku`\), the description \(`description`\), and the number of the purchased services \(`count`\).
    -   The `total_count` parameter with the total number of the purchased services or goods items.
    -   The `user_id` parameter with the internal identifier of the customer.
2.  When a payment has been processed, the information specified in the `data` string is passed to the merchant web service in the final callback and can be viewed in the payment information tab in Dashboard.
3.  The web service processes this information as needed together with the rest of the payment data.

![](images/ecommpay/en_merchant_data_db.svg "Viewing information in Dashboard")

### Setup {#section_qtw_bxx_pzb .section}

To use the capability of passing information in the `merchant.data` parameter, contact your account manager. The capability is then set up in the payment platform by the Ecommpay specialists who will subsequently inform you that it is ready to be usedand that the extended information is now available in callbacks and in the Dashboard interface.

### Data format {#section_bqb_cxx_pzb .section}

In requests to process payments via Gate, the data specified in the `merchant.data` parameter must be passed as a JSON object. However, because this parameter is a string \(string\), to pass the JSON object in it when using the HTTP POST method, you need to escape the `"` character \(quotation mark,U+0022\) by adding `\` \(backlash or reverse solidus,U+005C\) in front of it.It is necessary in order to distinguish on the level of programmatic interaction which quotation marks close the string and which quotations marks are part of the JSON contents within the string.

In final callbacks with payment results, the data that was specified in the `merchant.data` parameter is passed in the `data` parameter of the `merchant` object.

In the following examples, the contents of the parameter are split into several lines for the reader's convenience.

```language-json
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"
```

```language-json
"merchant": {
        "data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" 
}
```



---

# Using optional parameters for payments processing {#en_Gate_extra_params .concept}

An article about the capability of using additional parameters that are relevant to merchants and cannot be found in the the Gate API.

If necessary, Gate allows you to specify extra settings for processing payments performed by customers. That data should be sent in the payment.extra\_param parameter.

For more information regarding this option, you may apply to your Key Account Manager.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Using dynamic merchant descriptor {#en_gate_descriptor}

An article about the capability of providing customers with information about merchants via issuer services.

## Overview {#section_u2p_3rk_mhc .section}

When Ecommpay acts as an acquirer, in compliance with the rules of card networksEcommpay shares merchant details with other parties involved in payment processing. These detailscan be used by each party at its discretion and can be specified in receipts and bank statements by issuers.

By default, merchant information isstatic and limited to theagreed upon name of the merchant. However, the merchant can dynamically append additional detailsrelating to a particular payment or other aspects of their business. These dynamic descriptions can be included in payment requestsand are only limited to the maximum string length and the permitted character set \([details](en_gate_descriptor.md#section_b3f_hvp_13c)\). For example, the merchant descriptor can include the merchant's name combined with a booking period \(`Cosmotour* 17-19 feb`\) or with the name of the reserved hotel \(`Cosmotour* MarsSuite`\).

![](images/ecommpay/en_gate_descriptor_2.svg "Adding booking period")

![](images/ecommpay/en_gate_descriptor_1.svg "Adding hotel name")

Flexible use of accurate and informative details makes it easier for customers to identify merchants and payments and allows merchants to improve user experience and reduce the risk of disputes.In the Ecommpay payment platform, dynamic descriptors are relevant for *card payments* \(including standard card payments and payments made with Apple Pay, Click to Pay, Google Pay, and Visa Instalments\) and such payment types as one-time and COF purchases, payouts, and payment instrument verification.

## Special aspects {#section_fhg_s3m_djc .section}

When working with merchant data, consider the following special aspects:

-   The primary purpose of the merchant descriptor is to help customers recognise payments they made and prevent unnecessary chargebacks.

    Hence, avoid ambiguous or potentially misleading information in the merchant descriptor. Focus on the information that enables the customer to identify both the merchant and each operation clearly. In particular, it is recommended that you use a familiar brand name together with a concise description of the goods or services related to the operation.

-   Requirements to the merchant descriptor can vary depending on the card network.

    Pay attention to such differences, at least regarding the supported formats \([details](en_gate_descriptor.md#section_b3f_hvp_13c)\).

-   The way merchant details are provided to customers is determined by issuers.

    How merchant details will appear in receipts, bank statements, and other communication with the customer is determined by the rules of a specific issuer. As a result, merchant details may vary across issuers, different interfaces of the same issuer, and different operation types within a single interface. In particular, there may be differences due to processing different types of purchases ans payouts as well as Mastercard MoneySend and Visa Direct operations.


## Setup {#section_p14_v5p_13c .section}

The name of the merchant to be used as a default merchant descriptor is specified when the merchant is onboarded with the payment platform and, subsequently, can only be modified via the Ecommpay account manager.

To enable the use of the dynamic merchant descriptor, continue as follows:

1.  Coordinate with the Ecommpay account manager the roadmap of enabling the functionalityfor specific projects and the necessity for testing..
2.  If you need testing, get notified by the Ecommpay specialists that the capability is ready for being used in test mode,test this capability, and inform Ecommpay that everything is ready to launch.
3.  Get notified by the Ecommpay specialists that the capability has been added and fullyset up.

## Use {#section_dh5_v5p_13c .section}

If you need to use the dynamic merchant descriptor, include the `descriptor` parameter in the payment requests. Pass this parameter inthe `merchant` and `sender` objects. If both objects are supported for a given endpoint, the `descriptor` parameter can be specified in either. However, when both objects are passed, priority is given to a more relevant object:

-   `merchant` for purchases and payment instrument verification
-   `sender` for payouts

Keep in mind that in cases when the value of the `descriptor` parameter does not conform to the required format \([details](en_gate_descriptor.md#section_b3f_hvp_13c)\), the platform can automatically correct it\(for example, by transliterating alphabetic characters and removing invalid non-alphabetic characters\). Such correction of values does not lead to declined payments. Also, note that the Ecommpay platform does not validatethe value of the `descriptor` parameterfor factual correctness, but this information can be analysed and subsequently used by the issuers. Merchants should therefore ensure that values provided in the `descriptor` parameter are both technically compliant and contextually accurate in every instance of use.

-   for one-time one-step purchases with payment details provided as is or via the network tokens—[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)
-   for one-time one-step purchases with payment details provided via the internal tokens generated in the platform—[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)
-   for one-time two-step purchases with payment details provided as is or via the network tokens—[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)
-   for one-time two-step purchases with payment details provided via the internal tokens generated in the platform—[/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)
-   for COF purchases of all types—[/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring)
-   for payouts with payment details provided as is—[/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout)
-   for payouts with payment details provided via the internal tokens generated in the platform—[/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token)
-   for payment instrument verification with payment details provided as is or via the network tokens—[/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)
-   for payment instrument verification with payment details provided via the internal tokens generated in the platform—[/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)

-   for one-time one-step purchases—[/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale)
-   for one-time two-step purchases—[/v2/payment/applepay/auth](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-auth)

-   for one-time one-step purchases—[/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale)
-   for one-time two-step purchases—[/v2/payment/googlepay/auth](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-auth)

## Data format {#section_b3f_hvp_13c .section}

The maximum length of the merchant descriptor is determined by the card network. Mastercard sets a maximum length of 22 characters, while Visa sets a maximum length of 25 characters.Any characters exceeding these limits are truncated. Keep these limits and the allowed character requirements in mind when generating descriptions. The `descriptor` parameter can contain characters from the basic Latin alphabet, digits, a space character \(U+0020\), and the following symbols:

|`*`|U+002A|asterisk|
|`,`|U+002C|comma|
|`-`|U+002D|hyphen|
|`.`|U+002E|full stop|
|`=`|U+003D|equals sign|
|`_`|U+005F|underscore|

When generating the `descriptor` parameter, use the agreed uponmerchant's name followed by additional details separated by an asterisk \(`*`\) and a space, ensuring compliance with the applicable string length restrictions. For example, if a 9-character name `Cosmotour` is used with a 2-character separator, the remaining string length available for additional details is 11 characters for Mastercard and 14 characters for Visa. This is enough for a value such as `Cosmotour* to the Moon`.

``` {#codeblock_m2w_r5h_23c .language-json}

{
"payment": {
"amount": 1000,
"currency": "EUR",
"description": "Payout"
},
"general": {
"project_id": 91348,
"payment_id": "135113521354",
"signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
},
"customer": {
"id": "16061313",
"ip_address": "93.47.230.225",
"first_name": "John",
"last_name": "Doe"
},
"sender": {
"descriptor": "Cosmotour* to the Moon" // merchant details
},
"card": {
"save": false,
"pan": "4314220000000056"
}
}

```

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)



---

# Sending notifications to customers {#en_gate_receipts}

An article about the capability of informing customers about payment processing and related events via email notifications.

**Parent topic:**[Additional capabilities](en_Gate_Additional_capabilities.md)

## Overview {#en_gate_receipts_overview}

Ecommpay payment platform supports a capability of sending notifications to inform customers about various events related to processing of their payments. As a rule, these notifications contain information about operation processing results; however, depending on the needs of the merchant, notifications can inform customers about other events, for example, an e-wallet registration as part of processing a payment request oran update of the COF purchase's terms.

Notifications are sent if the following conditions are met:

-   Sending notifications has been set up for the project in question.
-   The email of the customer has been passed to the payment platform \(either in the initial request to perform a payment or in the clarification request\).
-   The event that triggers sending of notifications has occurred.

Events which can generate notifications include both the results of operation processing as part of executing a payment\(for example, operations `sale`, `auth`, `cancel`, `payout`, and `refund`\) and the results of separate actions that are part of operation processing\(for example, an update of the COF purchase's terms\).

You can also send your customers purchase receipts—notifications that contain information about the purchases they made. In this case, notifications include a list of purchased items with the corresponding attributes for each item \(price, quantity, description, and the amount of added VAT\).

If you need a certain notification to be sent once again, contact technical support specialists [support@ecommpay.com](mailto:support@ecommpay.com).

Sections below describe how this capability is set up, what versions of notification design can be used, and what relevant data to provide in payment requests. For more information about sent receipts to customers from Payment Page, see the section [Sending receipts and notifications to customer](en_PP_receipt_data.md).

## Setting up {#en_gate_receipts_setting_up}

Ecommpay technical support specialists enable and set up the capability of sending notifications to customers. The following settings are configured upon agreement with the merchant:

-   List of operations and other events to generate notifications.
-   Operations statuses that generate notifications \(can be enabled both for the final status `success` and for the final status `decline`\).
-   Subject line of the email with the notification \(for instance, Receipt or Notification about completed purchase\).
-   Sender's email address \(can be Ecommpay domain or custom domain\)
-   Option to send blind carbon copy \(bcc\) of the notification to the address provided by the merchant.

## Notification design {#en_gate_receipt_templates}

### Standard template {#section_vm3_223_cmb .section}

Our standard template can only be used for notifications about the results of operation processing as part of performing a `purchase`and a `payout` as well as the result of issuing a `refund`.

This template includes:

-   Date and time of the event that occurred with the time zone of the merchant's web service specified.
-   Logo of Ecommpay or the logo of the merchant.
-   Name, current address, and the registered domain name ofEcommpay or the merchant.
-   Type of the payment or operation the result of which is communicated in the notification.
-   Status of this payment or operation.
-   Payment identifier which corresponds to `payment_id`.
-   Description of the payment or operation if it was specified in the initial request.
-   Payment method which specifies the payment instrument used.
-   Payment amount with the currency code.
-   Link to the email ofEcommpay or the merchant.
-   Link to terms and conditions.

![](images/ecommpay/template_receipt_purchase.svg "Example of the notification about a completed purchase")

### Custom coded template {#section_glr_kj3_cmb .section}

A custom coded template can be used for sending notifications about the results of operation processing as well as other events that occur during payment processing. Custom coded templates are developed by Ecommpay specialists on the basis of the layouts provided by the merchant. These templates can include the same elements as the standard templates, with the option to modify the order in which the elements appear on the page, or they can include other elements, for example, the list of purchased items,or the details of the e-wallet registration, a warning about surpassing the daily amount limit for processed operations,or the update of the COF purchase's terms. Keep in mind that if you need a customised notification message, or the notification is sent in a language other than English \(which is the default notification language\), you should provide the text of the notification message to the technical support specialists.

The following are the examples of custom coded notification templates:

-   Notification about the end of the free trial period which does not contain any elements of the standard template \(except for the logo of the merchant\).
-   Notification with the list of purchased items which contains all elements of the standard template.

![](images/en-receipt-trial-update.png "Example of the notification about the end of the free trial period")

![](images/en-receipt-orderlist.png "Example of the notification with the list of purchased items")

## Data format {#en_gate_receipt_request_format}

For the notification to be sent, in addition to the required parameters, the payment request should contain the following:

-   The email of the customer which is passed in the `email` parameter of the `customer` object.
-   The language code of the customer which is passed in the `language` parameter of the `customer` object when notifications are sent in a language other than English.

To add the list of purchased items to the notification, send relevant data in the `receipt_data` object. The `receipt_data` object contains the `positions` array which allows listing up to 300 purchased items in the notification. For each listed item, the following information can be specified:

-   `amount`—a required parameter to specify the price of the item
-   `quantity`—an additional parameter to specify the number of purchased items of the same kind
-   `tax`—an additional parameter to specify VAT rate
-   `tax_amount`—an additional parameter to specify the amount of the VAT paid
-   `description`—an additional parameter to describe the purchased item

As a rule, the `receipt_data` object also contains the `total_tax_amount` parameter specifying the total VAT amount for the entire purchase. If the VAT rate is the same for all items, then it is specified in the `common_tax` parameter after the total amount has been specified. If the VAT rate differs for listed items, then it is specified in the `tax` parameter separately for each item.

The JSON object structure is provided in the `[receiptdata](https://api-developers.ecommpay.com/api.html#/c2NoOjQwNTY3ODY2-receipt-data)` model in the Gate API specification.

In the example below, the purchase request contains the list of three items in the `positions` array of the `receipt_data` object. The VAT rates for the listed items differ; therefore, they are specified separately in the `tax` parameter for each item. There is no need to pass the `common_tax` parameter with the VAT rate for all items in this case.

```language-json
{
  "general":{
    "project_id":92724,
    "payment_id":"7654321-777",
    "signature":"5fgsjhgfgFxO9UaFLYGsBaisdffddgYuezUf+6VWlrsdfsH+LysUfdQM+w=="
  },
  "customer":{
    "ip_address":"128.112.0.16",
    "email":"relativeal@princeton.com"
  },
  "payment":{
    "amount":131971,
    "currency":"USD",
    "description":"Cosmoshop order"
  },
  "receipt_data":{
    "positions":[             //an array with the list of purchased items
      {
        "quantity":1,
        "amount":5990,
        "tax":20,                   //standard VAT rate
        "tax_amount":1198,
        "description":"How to communicate with aliens, a book"
      },
      {
        "quantity":3,
        "amount":2990,
        "tax":10,     //reduced VAT rate
        "tax_amount":299,
        "description":"Astronaut space food, 1-week supply"
      },
      {
        "quantity":1,
        "amount":122990,
        "tax":20,                   //standard VAT rate 
        "tax_amount":24598,
        "description":"Radio-controlled flying saucer, full size"
      }
    ],
    "total_tax_amount":26095    //total VAT amount for the entire purchase
  },
  "card":\{
    "pan":"4314220000000056",
    "year":2025,
    "month":11,
    "card\_holder":"Albert Astone"
  \}
}
```



---

# Gate API {#gate_api}
**Up one level:** [Gate](en_Gate_Integration_About.md)

{
    "openapi": "3.0.2",
    "info": {
        "title": "Gate API",
        "description": "Ecommpay Gate public API is an interface for merchants to perform operations and retrieve operation information",
        "version": "3.34.5"
    },
    "servers": [
        {
            "url": "https://api.ecommpay.com"
        }
    ],
    "paths": {
        "/v2/payment/card/sale": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/sale",
                "description": "Request for purchase from the customer's card",
                "operationId": "POST_v2-payment-card-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "card",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoForSaleAuth"
                                    },
                                    "token_data": {
                                        "$ref": "#/components/schemas/TokenData"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfoSale"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/sale/saved": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/sale/saved",
                "description": "Request for purchase from the customer's saved card",
                "operationId": "POST_v2-payment-card-sale-saved",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "saved_account_id"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    },
                                    "saved_account_id": {
                                        "type": "integer",
                                        "description": "The identifier associated with the corresponding payment instrument in the payment platform"
                                    },
                                    "cvv": {
                                        "type": "string",
                                        "pattern": "^[0-9]{3,4}$",
                                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/sale/token": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/sale/token",
                "operationId": "POST_v2-payment-card-sale-token",
                "description": "Request for purchase from the customer's card by using its token",
                "requestBody": {
                    "description": "Payment by token",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "token": {
                                        "description": "Card token received from the payment platform",
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255
                                    },
                                    "cvv": {
                                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession",
                                        "type": "string",
                                        "pattern": "^[0-9]{3,4}$"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfoSale"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/card/auth": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/auth",
                "description": "Request for holding funds on the customer's card. The holding of funds can be captured or cancelled by merchant request or automatically if it is specified in merchant project",
                "operationId": "POST_v2-payment-card-auth",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "card",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoForSaleAuth"
                                    },
                                    "token_data": {
                                        "$ref": "#/components/schemas/TokenData"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/auth/saved": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/auth/saved",
                "description": "Request for holding funds on the customer's saved card",
                "operationId": "POST_v2-payment-card-auth-saved",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "saved_account_id"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "saved_account_id": {
                                        "type": "integer",
                                        "description": "The identifier associated with the corresponding payment instrument in the payment platform"
                                    },
                                    "cvv": {
                                        "type": "string",
                                        "pattern": "^[0-9]{3,4}$",
                                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/auth/token": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/auth/token",
                "operationId": "POST_v2-payment-card-auth-token",
                "description": "Request for holding funds on the customer's saved card by using its token",
                "requestBody": {
                    "description": "DMS first step by token",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoCard"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "email",
                                                    "phone",
                                                    "screen_res"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoForCard"
                                    },
                                    "token": {
                                        "description": "Card token received from the payment platform",
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255
                                    },
                                    "cvv": {
                                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession",
                                        "type": "string",
                                        "pattern": "^[0-9]{3,4}$"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumInitialCard"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "installment": {
                                        "$ref": "#/components/schemas/Installment"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/card/capture": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/capture",
                "description": "Request for debit of the previously held funds on the customer's card",
                "operationId": "POST_v2-payment-card-capture",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "type": "object",
                                        "properties": {
                                            "amount": {
                                                "type": "integer",
                                                "description": "Payment amount, can be equal to, less or more than in the initial auth request. If the amount is less or more than in the auth request a decremental or incremental operation is created automatically"
                                            },
                                            "currency": {
                                                "type": "string",
                                                "pattern": "^[A-Z]{3}$",
                                                "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in the initial auth request"
                                            },
                                            "description": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Payment description or comment"
                                            },
                                            "extra_param": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Parameter for passing additional settings for customise the payment processing flow"
                                            }
                                        }
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/Addendum"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/incremental": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/incremental",
                "description": "Request for changing the amount of payment after holding, before confirm",
                "operationId": "POST_v2-payment-card-incremental",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoCard"
                                    },
                                    "payment": {
                                        "type": "object",
                                        "properties": {
                                            "amount": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 10000000000000,
                                                "description": "Amount to increment"
                                            },
                                            "currency": {
                                                "type": "string",
                                                "pattern": "^[A-Z]{3}$",
                                                "description": "Payment currency in ISO 4217 alpha-3 format, must be same with currency in auth request"
                                            },
                                            "description": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Payment description"
                                            },
                                            "extra_param": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Parameter for passing additional settings for customise the payment processing flow"
                                            }
                                        },
                                        "required": [
                                            "currency",
                                            "amount"
                                        ]
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/Addendum"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/cancel": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/cancel",
                "description": "Request to cancel the holding of funds on the customer's card",
                "operationId": "POST_v2-payment-card-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "type": "object",
                                        "properties": {
                                            "amount": {
                                                "type": "integer",
                                                "description": "Payment amount, can be equal to or less than in the initial auth request. If the amount is less than in the auth request a decremental operation is created automatically"
                                            },
                                            "currency": {
                                                "type": "string",
                                                "pattern": "^[A-Z]{3}$",
                                                "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in auth request"
                                            },
                                            "description": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Payment description or comment"
                                            },
                                            "extra_param": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Parameter for passing additional settings for customise the payment processing flow"
                                            }
                                        }
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/Addendum"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/account_verification": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/account_verification",
                "description": "Request for card verification without performing actual withdrawal",
                "operationId": "POST_v2-payment-card-account-verification",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "card",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfo"
                                    },
                                    "token_data": {
                                        "$ref": "#/components/schemas/TokenData"
                                    },
                                    "customer": {
                                        "type": "object",
                                        "description": "Object that contains customer details",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoNameValidation"
                                            },
                                            {
                                                "type": "object",
                                                "required": [
                                                    "id"
                                                ]
                                            }
                                        ]
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/AccountVerificationPaymentInfoForCard"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    },
                                    "merchant": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/MerchantInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/Descriptor"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/account_verification/token": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/account_verification/token",
                "description": "Request for card verification by token without performing actual withdrawal",
                "operationId": "POST_v2-payment-card-account-verification-by-token",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "type": "object",
                                        "description": "Object that contains customer details",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoNameValidation"
                                            },
                                            {
                                                "type": "object",
                                                "required": [
                                                    "id"
                                                ]
                                            }
                                        ]
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/AccountVerificationPaymentInfoForCard"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "acs_return_url": {
                                        "$ref": "#/components/schemas/ACSReturnUrl"
                                    },
                                    "authentication_data": {
                                        "$ref": "#/components/schemas/AuthenticationData"
                                    },
                                    "token": {
                                        "description": "Card token received from the payment platform",
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255
                                    },
                                    "cvv": {
                                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession",
                                        "type": "string",
                                        "pattern": "^[0-9]{3,4}$"
                                    },
                                    "card": {
                                        "type": "object",
                                        "properties": {
                                            "stored_card_type": {
                                                "$ref": "#/components/schemas/StoredCardType"
                                            }
                                        }
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    },
                                    "merchant": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/MerchantInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/Descriptor"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/recurring": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/recurring",
                "description": "Request to perform regular COF payment from the customer's card",
                "operationId": "POST_v2-payment-card-recurring",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "type": "object",
                                        "description": "Object that contains customer details",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfo"
                                            },
                                            {
                                                "type": "object",
                                                "required": [
                                                    "id"
                                                ]
                                            }
                                        ]
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfoRecurring"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "recurring_id": {
                                        "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier received from the payment platform",
                                        "type": "integer"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/recurring/update": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/recurring/update",
                "description": "Request to update or change recurring payment conditions",
                "operationId": "POST_v2-payment-card-recurring-update",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringUpdateInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/recurring/cancel": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/recurring/cancel",
                "description": "Request to cancel recurring payment",
                "operationId": "POST_v2-payment-card-recurring-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/merchant_auth": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/merchant_auth",
                "description": "Request for performing a customer authentication by the payment system on merchant's request",
                "operationId": "POST_v2-payment-card-merchant_auth",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/MerchantAuthGeneralInfo"
                                    },
                                    "confirmation_code": {
                                        "type": "string",
                                        "minLength": 1,
                                        "description": "Authentication confirmation code entered by a customer"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/3ds_check_iframe": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/3ds_check_iframe",
                "operationId": "POST_v2-payment-card-3ds_check_iframe",
                "description": "Request to check enrolled card after show iframe",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo3DS"
                                    },
                                    "threeds_completion_indicator": {
                                        "description": "Indicator that specifies whether the message acknowledging the receipt of the customer's device information was received within 10 seconds after the iframe element was closed. If the acknowledgement was received within 10 seconds, pass `true`; if not, pass `false`",
                                        "type": "boolean"
                                    },
                                    "md": {
                                        "type": "string",
                                        "minLength": 1,
                                        "description": "Merchant state data. The content of this field must be passed unchanged and without assumptions about its content"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/3ds_result": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/3ds_result",
                "description": "Request to continue payment processing after 3-D Secure authentication",
                "operationId": "POST_v2-payment-card-3ds_result",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "required": [
                                            "general",
                                            "cres"
                                        ],
                                        "properties": {
                                            "general": {
                                                "$ref": "#/components/schemas/GeneralInfo3DS"
                                            },
                                            "cres": {
                                                "type": "string",
                                                "minLength": 1,
                                                "description": "Challenge response - the parameter containing the information about customer's 3‑D Secure 2 authentication result sent in the message from the Access Control Server"
                                            },
                                            "md": {
                                                "type": "string",
                                                "minLength": 1,
                                                "description": "Merchant state data received from the payment platform in the callback. The content of this field must be passed unchanged and without assumptions about its content"
                                            },
                                            "interface_type": {
                                                "$ref": "#/components/schemas/SourceInfo"
                                            }
                                        }
                                    },
                                    {
                                        "required": [
                                            "general",
                                            "pares"
                                        ],
                                        "properties": {
                                            "general": {
                                                "$ref": "#/components/schemas/GeneralInfo3DS"
                                            },
                                            "pares": {
                                                "type": "string",
                                                "minLength": 1,
                                                "description": "Payer Authentication Response - the parameter containing the information about customer's 3‑D Secure 1 authentication result sent in the message from the Access Control Server"
                                            },
                                            "md": {
                                                "type": "string",
                                                "description": "Merchant state data received from the payment platform in the callback. The content of this field must be passed unchanged and without assumptions about its content"
                                            },
                                            "interface_type": {
                                                "$ref": "#/components/schemas/SourceInfo"
                                            }
                                        }
                                    },
                                    {
                                        "x-stoplight": {
                                            "id": "5ifn7agerbe31"
                                        }
                                    }
                                ],
                                "type": "object"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/refund": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/refund",
                "description": "* Request for full or partial refund to the customer's card.\n* Refund is requested in the same currency that the payment was performed.\n* The refund amount can be less than or equal to the amount of the initial payment. The partial refund amount is specified in the parameter `amount`.\n* If the refund amount is not specified in the request, the full amount of the initial payment is refunded",
                "operationId": "POST_v2-payment-card-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/Addendum"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/payout": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/payout",
                "description": "Request to credit funds to the customer's card",
                "operationId": "POST_v2-payment-card-payout",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "card",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoLight"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfoPayout"
                                    },
                                    "recipient": {
                                        "type": "object",
                                        "properties": {
                                            "country": {
                                                "maxLength": 2,
                                                "pattern": "^[A-Z]{2}$",
                                                "type": "string",
                                                "description": "Country code of recipient"
                                            },
                                            "address": {
                                                "maxLength": 99,
                                                "type": "string",
                                                "description": "Recipient address"
                                            },
                                            "city": {
                                                "maxLength": 25,
                                                "type": "string",
                                                "description": "Name of recipient's address city"
                                            },
                                            "state": {
                                                "maxLength": 3,
                                                "pattern": "^[A-Z]+$",
                                                "type": "string",
                                                "description": "State code of recipient"
                                            },
                                            "first_name": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Customer first name"
                                            },
                                            "last_name": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Customer last name"
                                            }
                                        }
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            },
                                            {
                                                "type": "object",
                                                "description": "Object that contains payment details",
                                                "properties": {
                                                    "purpose": {
                                                        "type": "string",
                                                        "maxLength": 12,
                                                        "description": "Payment purpose code—the parameter is populated if specification of payment purpose is mandatory in issuer country"
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/card/payout/token": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/card/payout/token",
                "description": "Request to credit funds to the customer's card by using its token",
                "operationId": "POST_v2-payment-card-payout-token",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfoPayout"
                                    },
                                    "recipient": {
                                        "type": "object",
                                        "properties": {
                                            "country": {
                                                "maxLength": 2,
                                                "pattern": "^[A-Z]{2}$",
                                                "type": "string",
                                                "description": "Country code of recipient"
                                            },
                                            "address": {
                                                "maxLength": 99,
                                                "type": "string",
                                                "description": "Recipient address"
                                            },
                                            "city": {
                                                "maxLength": 25,
                                                "type": "string",
                                                "description": "Name of recipient's address city"
                                            },
                                            "state": {
                                                "maxLength": 3,
                                                "pattern": "^[A-Z]+$",
                                                "type": "string",
                                                "description": "State code of recipient"
                                            },
                                            "first_name": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Customer first name"
                                            },
                                            "last_name": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "description": "Customer last name"
                                            }
                                        }
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "type": "object",
                                                "description": "Object that contains payment details",
                                                "properties": {
                                                    "purpose": {
                                                        "type": "string",
                                                        "maxLength": 12,
                                                        "description": "Payment purpose code—the parameter is populated if specification of payment purpose is mandatory in issuer country"
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "token": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255,
                                        "description": "Card token received from the payment platform"
                                    },
                                    "card": {
                                        "type": "object",
                                        "properties": {
                                            "card_holder": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                                                "description": "Name of the cardholder as specified on the payment card"
                                            }
                                        }
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/individual/payout": {
            "post": {
                "tags": [
                    "Card payments"
                ],
                "summary": "/v2/payment/individual/payout",
                "description": "Request to credit funds to a customer's card by using P2P scheme",
                "operationId": "POST_v2-payment-individual-payout",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "card",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoLight"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/card/bytoken": {
            "post": {
                "tags": [
                    "Token operations"
                ],
                "summary": "/v2/customer/card/bytoken",
                "description": "Request for retrieving the saved customer's payment account details by customer's card token in specific project",
                "operationId": "POST_v2-customer-card-bytoken",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "customer",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerGeneralInfo"
                                    },
                                    "token": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255,
                                        "description": "Card token received from the payment platform"
                                    }
                                },
                                "description": "Object that contains parameters for receiving of the customer's payment account in the project"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "account",
                                        "signature"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "signature": {
                                            "type": "string",
                                            "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)."
                                        },
                                        "account": {
                                            "$ref": "#/components/schemas/SavedAccount"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/card/tokenize": {
            "post": {
                "tags": [
                    "Token operations"
                ],
                "summary": "/v2/customer/card/tokenize",
                "description": "Request for the token generation of a customer's card",
                "operationId": "POST_v2-customer-card-tokenize",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "customer",
                                    "card"
                                ],
                                "type": "object",
                                "properties": {
                                    "customer": {
                                        "$ref": "#/components/schemas/TokenizeCustomerInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoForTokenize"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/card/token/revoke": {
            "post": {
                "tags": [
                    "Token operations"
                ],
                "summary": "/v2/customer/card/token/revoke",
                "description": "Request for revoking token.",
                "operationId": "POST_v2-customer-card-token-revoke",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "token",
                                    "customer"
                                ],
                                "type": "object",
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerGeneralInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/clarification": {
            "post": {
                "tags": [
                    "Additional information submission"
                ],
                "summary": "/v2/payment/clarification",
                "description": "Request to pass the parameters required to make a payment and missed in the previously sent payment request",
                "operationId": "POST_v2-clarification",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "additional_data"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfoClarification"
                                    },
                                    "additional_data": {
                                        "$ref": "#/components/schemas/AdditionalData"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/payout/registration": {
            "post": {
                "tags": [
                    "Payment Page payouts"
                ],
                "summary": "/v2/payment/payout/registration",
                "description": "Register payout payment",
                "operationId": "POST_v2-payment-payout-registration",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "required": [
                                            "payment_id",
                                            "project_id",
                                            "signature"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "payment_id": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Identifier of the payment, must be unique within project. Any letters, digits, and symbols in UTF-8 encoding can be used"
                                            },
                                            "merchant_callback_url": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`"
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        }
                                    },
                                    "customer": {
                                        "required": [
                                            "id",
                                            "ip_address",
                                            "email"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Customer identifier unique within the project"
                                            },
                                            "email": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "format": "email",
                                                "description": "Customer email address"
                                            },
                                            "phone": {
                                                "pattern": "^[0-9]{4,24}$",
                                                "type": "string",
                                                "description": "Customer's phone number, can be 4 to 24 digits long"
                                            },
                                            "ip_address": {
                                                "type": "string",
                                                "maxLength": 255,
                                                "format": "ip-address",
                                                "description": "Customer IP address"
                                            }
                                        }
                                    },
                                    "payment": {
                                        "required": [
                                            "amount",
                                            "currency"
                                        ],
                                        "type": "object",
                                        "description": "Object that contains payment details",
                                        "properties": {
                                            "amount": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "maximum": 10000000000000,
                                                "description": "Payment amount in minor units of currency"
                                            },
                                            "currency": {
                                                "type": "string",
                                                "pattern": "^[:_A-Z0-9]{3,27}$",
                                                "description": "Payment currency in the ISO 4217 alpha-3 format"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/verification-of-payee/create": {
            "post": {
                "tags": [
                    "Verification of Payee Service"
                ],
                "summary": "/v2/verification-of-payee/create",
                "description": "Request for verification of payee",
                "operationId": "POST_v2-verification-of-payee-create",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "account"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "description": "Object that contains customer details",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/CustomerInfoBase"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "id"
                                                ]
                                            }
                                        ]
                                    },
                                    "account": {
                                        "description": "Object that contains account details",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/AccountBankPayoutInfo"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {},
                                                "required": [
                                                    "customer_name",
                                                    "number"
                                                ]
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/verification-of-payee/result": {
            "post": {
                "tags": [
                    "Verification of Payee Service"
                ],
                "summary": "/v2/verification-of-payee/result",
                "description": "Request for verification of payee result",
                "operationId": "POST_v2-verification-of-payee-result",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "vop"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "vop": {
                                        "required": [
                                            "id"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "type": "integer",
                                                "description": "Id of vop"
                                            }
                                        },
                                        "description": "Object that contains vop fields."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/session/applepay": {
            "post": {
                "tags": [
                    "Apple Pay",
                    "sync"
                ],
                "summary": "/v2/session/applepay",
                "description": "Request for receiving the Apple Pay payment session",
                "operationId": "POST_v2-session-applepay",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/SessionGeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/ApplePaySessionPaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SessionResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/sale": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/sale",
                "description": "Request to debit funds from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/ETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/auth": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/auth",
                "description": "Request for performing authentication from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-auth",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/ETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/capture": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/capture",
                "description": "Request for performing a customer capture from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-capture",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/recurring": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/recurring",
                "description": "Request to perform recurring payment from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-recurring",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/recurring/cancel": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/recurring/cancel",
                "description": "Request to cancel recurring payment from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-recurring-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/refund": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/refund",
                "description": "Request to perform refund payment from the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/applepay/account_verification": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/account_verification",
                "description": "Request for card verification without performing actual withdrawal via Apple Pay",
                "operationId": "POST_v2-payment-applepay-account-verification",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoNameValidation"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/AccountVerificationPaymentInfo"
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/ETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/applepay/cancel": {
            "post": {
                "tags": [
                    "Apple Pay"
                ],
                "summary": "/v2/payment/applepay/cancel",
                "description": "Request to cancel the holding of funds on the customer's card via Apple Pay",
                "operationId": "POST_v2-payment-applepay-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/CancelPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/atm/{payment_method}/sale": {
            "post": {
                "tags": [
                    "ATM"
                ],
                "summary": "/v2/payment/atm/{payment_method}/sale",
                "operationId": "POST_v2-payment-atm-payment-method-sale",
                "description": "Request to debit funds from the customer's card by means of ATMs of the supported banks",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Payment initiation request",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "return_url"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankPurchaseInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoLight"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/atm/{payment_method}/payout": {
            "post": {
                "tags": [
                    "ATM"
                ],
                "summary": "/v2/payment/atm/{payment_method}/payout",
                "operationId": "POST_v2-payment-atm-payment-method-payout",
                "description": "Request for payout to the customer's card by means of ATMs of the supported banks",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Payout initiation request",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "account"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountAtmPayoutInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoLight"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/bancontact/sale": {
            "post": {
                "tags": [
                    "Bancontact"
                ],
                "summary": "/v2/payment/bancontact/sale",
                "description": "Request for payment by using Bancontact",
                "operationId": "POST_v2-payment-bancontact-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/bancontact/refund": {
            "post": {
                "tags": [
                    "Bancontact"
                ],
                "summary": "/v2/payment/bancontact/refund",
                "description": "Request for refund by using Bancontact",
                "operationId": "POST_v2-payment-bancontact-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/banks/{payment_method}/sale": {
            "post": {
                "tags": [
                    "Banks"
                ],
                "summary": "/v2/payment/banks/{payment_method}/sale",
                "operationId": "POST_v2-payment-banks-payment-method-sale",
                "description": "Request to debit funds from the customer's card in one of the supported banks",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Payment initiation request",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankPurchaseInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentBanksInfo"
                                    },
                                    "return_url": {
                                        "oneOf": [
                                            {
                                                "$ref": "#/components/schemas/ReturnUrl"
                                            },
                                            {
                                                "type": "string",
                                                "description": "URL to which customer is redirected after payment performing",
                                                "minLength": 1
                                            }
                                        ]
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/banks/{payment_method}/payout": {
            "post": {
                "tags": [
                    "Banks"
                ],
                "summary": "/v2/payment/banks/{payment_method}/payout",
                "operationId": "POST_v2-payment-banks-payment-method-payout",
                "description": "Request to credit funds to the customer's card in one of the supported banks",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Payout initiation request",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "account"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankPayoutInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "card": {
                                        "$ref": "#/components/schemas/CardInfoLight"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/banks/{payment_method}/refund": {
            "post": {
                "tags": [
                    "Banks"
                ],
                "summary": "/v2/payment/banks/{payment_method}/refund",
                "operationId": "POST_v2-payment-banks-payment-method-refund",
                "description": "Request for refund to the customer's card in one of the supported banks",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Refund initiation request",
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/bank-transfer/{payment_method}/sale": {
            "post": {
                "tags": [
                    "Bank Transfer"
                ],
                "summary": "/v2/payment/bank-transfer/{payment_method}/sale",
                "description": "Request for transferring of funds from the customer's bank account in one of the supported banks",
                "operationId": "POST_v2-payment-bank-transfer-method-sale",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/BankTransferCustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AnotherAccountBankInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/bank-transfer/{payment_method}/payout": {
            "post": {
                "tags": [
                    "Bank Transfer"
                ],
                "summary": "/v2/payment/bank-transfer/{payment_method}/payout",
                "description": "Request for transferring of funds to the customer's bank account in one of the supported banks",
                "operationId": "POST_v2-payment-bank-transfer-method-payout",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "additional_data": {
                                        "$ref": "#/components/schemas/AdditionalData"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/bank-transfer/{payment_method}/refund": {
            "post": {
                "tags": [
                    "Bank Transfer"
                ],
                "summary": "/v2/payment/bank-transfer/{payment_method}/refund",
                "description": "Request for refund transferring to the customer's bank account in one of the supported banks",
                "operationId": "POST_v2-payment-bank-transfer-varying-method-refund",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankRefundInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/blik/sale": {
            "post": {
                "tags": [
                    "Blik"
                ],
                "summary": "/v2/payment/blik/sale",
                "description": "Request for payment through blik payment method",
                "operationId": "POST_v2-payment-blik-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/blik/refund": {
            "post": {
                "tags": [
                    "Blik"
                ],
                "summary": "/v2/payment/blik/refund",
                "description": "Request for refund through blik payment method",
                "operationId": "POST_v2-payment-blik-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/bnpl/humm/sale": {
            "post": {
                "tags": [
                    "BNPL"
                ],
                "summary": "/v2/payment/bnpl/humm/sale",
                "description": "BNPL sale",
                "operationId": "POST_v2-payment-bnpl-humm-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment",
                                    "customer"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoBnplSale"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/cup/union/sale": {
            "post": {
                "tags": [
                    "China UnionPay"
                ],
                "summary": "/v2/payment/cup/union/sale",
                "description": "Request to debit funds from the customer's account in China UnionPay system by using CUP payment method union",
                "operationId": "POST_v2-payment-cup-union-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "return_url"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/CupReturnUrl"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/unionpay/refund": {
            "post": {
                "tags": [
                    "China UnionPay"
                ],
                "summary": "/v2/payment/unionpay/refund",
                "operationId": "POST_v2-payment-unionpay-refund",
                "description": "Request for refund through the UnionPay payment method",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/directdebit/{payment_method}/sale": {
            "post": {
                "tags": [
                    "Direct debit"
                ],
                "summary": "/v2/payment/directdebit/{payment_method}/sale",
                "description": "Request for purchase with mandate registrations",
                "operationId": "POST_v2-payment-directdebit-payment_method-sale",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringRequiredInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/directdebit/{payment_method}/contract/registration": {
            "post": {
                "tags": [
                    "Direct debit"
                ],
                "summary": "/v2/payment/directdebit/{payment_method}/contract/registration",
                "description": "Request to mandate registrations without making payment",
                "operationId": "POST_v2-payment-directdebit-payment_method-contract-registration",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfoDirectDebit"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringRequiredInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/directdebit/{payment_method}/recurring": {
            "post": {
                "tags": [
                    "Direct debit"
                ],
                "summary": "/v2/payment/directdebit/{payment_method}/recurring",
                "description": "Request to perform recurring payment from the customer's directdebit account",
                "operationId": "POST_v2-payment-directdebit-recurring",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "recurring_id": {
                                        "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases",
                                        "type": "integer"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/directdebit/{payment_method}/recurring/update": {
            "post": {
                "tags": [
                    "Direct debit"
                ],
                "summary": "/v2/payment/directdebit/{payment_method}/recurring/update",
                "description": "Request to perform recurring payment update info",
                "operationId": "POST_v2-payment-directdebit-recurring-update",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringUpdateInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/directdebit/{payment_method}/recurring/cancel": {
            "post": {
                "tags": [
                    "Direct debit"
                ],
                "summary": "/v2/payment/directdebit/{payment_method}/recurring/cancel",
                "description": "Request to perform recurring payment cancel",
                "operationId": "POST_v2-payment-directdebit-recurring-cancel",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/recurring/info": {
            "post": {
                "tags": [
                    "Requests for recurring"
                ],
                "summary": "/v2/payment/recurring/info",
                "description": "Request to get info about recurring payment conditions",
                "operationId": "POST_v2-payment-recurring-info",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "type": "object",
                                        "description": "Object that contains general request details",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        },
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ]
                                    },
                                    "recurring": {
                                        "type": "object",
                                        "description": "Object that contains the identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases",
                                        "properties": {
                                            "id": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "description": "Unique identifier of the recurring payment in the payment platform"
                                            }
                                        },
                                        "required": [
                                            "id"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RecurringInfoSuccess"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/refund": {
            "post": {
                "tags": [
                    "Requests for refunding specific payments"
                ],
                "summary": "/v2/payment/refund",
                "description": "* Request for full or partial refund to the customer's payment method.\n* Refund is requested in the same currency that the payment was performed.\n* The refund amount can be less than or equal to the amount of the initial payment. The partial refund amount is specified in the parameter `amount`.\n* If the refund amount is not specified in the request, the full amount of the initial payment is refunded",
                "operationId": "POST_v2-payment-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/Addendum"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/sale": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/sale",
                "description": "Request to debit funds from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/GooglePayETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/auth": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/auth",
                "description": "Request for performing authentication from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-auth",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/GooglePayETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "sender": {
                                        "$ref": "#/components/schemas/Descriptor"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/capture": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/capture",
                "description": "Request for performing a customer capture from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-capture",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/recurring": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/recurring",
                "description": "Request to perform recurring payment from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-recurring",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfo"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/recurring/cancel": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/recurring/cancel",
                "description": "Request to cancel recurring payment from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-recurring-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/refund": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/refund",
                "description": "Request to perform refund payment from the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/payment/googlepay/account_verification": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/account_verification",
                "description": "Request for card verification without performing actual withdrawal via Google Pay",
                "operationId": "POST_v2-payment-googlepay-account-verification",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "etoken"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoNameValidation"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/AccountVerificationPaymentInfo"
                                    },
                                    "etoken": {
                                        "$ref": "#/components/schemas/GooglePayETokenInfoLight"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "avs_data": {
                                        "$ref": "#/components/schemas/AvsInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/googlepay/cancel": {
            "post": {
                "tags": [
                    "Google Pay"
                ],
                "summary": "/v2/payment/googlepay/cancel/etoken",
                "description": "Request to cancel the holding of funds on the customer's card via Google Pay",
                "operationId": "POST_v2-payment-googlepay-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/CancelPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/online-banking/{payment_method}/sale": {
            "post": {
                "tags": [
                    "Online banking"
                ],
                "summary": "/v2/payment/online-banking/{payment_method}/sale",
                "description": "Request for payment from customer's online bank account in one of the supported banks",
                "operationId": "POST_v2-payment-online-banking-payment_method-sale",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "receipt_data": {
                                        "$ref": "#/components/schemas/ReceiptData"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "recurring_register": {
                                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment",
                                        "type": "boolean"
                                    },
                                    "additional_data": {
                                        "$ref": "#/components/schemas/AdditionalData"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/online-banking/{payment_method}/refund": {
            "post": {
                "tags": [
                    "Online banking"
                ],
                "summary": "/v2/payment/online-banking/{payment_method}/refund",
                "description": "Request for refund to the customer's online bank account in one of the supported banks",
                "operationId": "POST_v2-payment-online-banking-payment_method-refund",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/pix/sale": {
            "post": {
                "tags": [
                    "Pix"
                ],
                "summary": "/v2/payment/pix/sale",
                "description": "Request for payment through the Pix payment method",
                "operationId": "POST_v2-payment-pix-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/pix/payout": {
            "post": {
                "tags": [
                    "Pix"
                ],
                "summary": "/v2/payment/pix/payout",
                "description": "Request for payout through the Pix payment method",
                "operationId": "POST_v2-payment-pix-payout",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountBankInfo"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/invoice/create": {
            "post": {
                "tags": [
                    "Payment links"
                ],
                "summary": "/v2/payment/invoice/create",
                "description": "Request to create an invoice payment",
                "operationId": "POST_v2-payment-invoice-create",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfoInvoice"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoInvoice"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfoInvoice"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "operation_type": {
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "auth",
                                            "contract registration"
                                        ],
                                        "description": "Operation type for customer to pay. Default is sale."
                                    },
                                    "send_email": {
                                        "type": "boolean",
                                        "description": "Send automatic email to customer or not"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Payload parsing or data structure error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/invoice/card/token/create": {
            "post": {
                "tags": [
                    "Payment links"
                ],
                "summary": "/v2/payment/invoice/card/token/create",
                "operationId": "POST_v2-payment-invoice-card-token-create",
                "description": "Create invoice payment by token",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "token"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfoInvoice"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoInvoice"
                                    },
                                    "payment": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/PaymentInfoInvoiceByToken"
                                            },
                                            {
                                                "$ref": "#/components/schemas/CryptoPayment"
                                            }
                                        ]
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/RecipientForCard"
                                    },
                                    "token": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255,
                                        "description": "Token of the customer's card in Gate"
                                    },
                                    "operation_type": {
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "auth"
                                        ],
                                        "description": "Operation type for customer to pay. Default is sale."
                                    },
                                    "send_email": {
                                        "type": "boolean",
                                        "description": "Send automatic email to customer or not"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "booking_info": {
                                        "$ref": "#/components/schemas/BookingInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Payload parsing or data structure error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/invoice/cancel": {
            "post": {
                "tags": [
                    "Payment links"
                ],
                "summary": "/v2/payment/invoice/cancel",
                "operationId": "POST_v2-payment-invoice-cancel",
                "description": "Request to cancel invoice payment",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfoInvoice"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Payload parsing or data structure error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/sale": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/sale",
                "description": "Request for payment through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-sale",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "return_url"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/1-tap": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/1-tap",
                "description": "Request for OneClick payment through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-1-tap",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/recurring/update": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/recurring/update",
                "description": "Request to update or change recurring conditions of the payment through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-recurring-update",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringUpdateInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/recurring/cancel": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/recurring/cancel",
                "description": "Request to cancel recurring payment through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-recurring-cancel",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/payout": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/payout",
                "description": "Request for payout through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-payout",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "account",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/SkrillCustomerInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/skrill/refund": {
            "post": {
                "tags": [
                    "Skrill"
                ],
                "summary": "/v2/payment/skrill/refund",
                "description": "Request for refund through the Skrill payment method",
                "operationId": "POST_v2-payment-skrill-refund",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "account",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/SkrillCustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/sale": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/sale",
                "description": "Request for payment via methods that support e-wallets",
                "operationId": "POST_v2-payment-wallet-paymentmethod-sale",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "account": {
                                        "type": "object",
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/AccountInfo"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {
                                                    "customer_name": {
                                                        "type": "string",
                                                        "description": "Account owner full name"
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "addendum": {
                                        "$ref": "#/components/schemas/AddendumData"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/auth": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/auth",
                "description": "First step DMS for APS",
                "operationId": "POST_v2-payment-wallet-paymentmethod-auth",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "return_url"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/capture": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/capture",
                "description": "First step DMS for APS",
                "operationId": "POST_v2-payment-wallet-paymentmethod-capture",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "properties": {
                                            "amount": {
                                                "type": "integer",
                                                "description": "Payment amount, can be equal to, less or more than in the initial auth request. If the amount is less or more than in the auth request a decremental or incremental operation is created automatically"
                                            },
                                            "currency": {
                                                "type": "string",
                                                "pattern": "^[A-Z]{3}$",
                                                "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in the initial auth request"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/cancel": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/cancel",
                "description": "Cancel step DMS for APS",
                "operationId": "POST_v2-payment-wallet-paymentmethod-cancel",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/CancelPaymentInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    },
                                    "callback": {
                                        "$ref": "#/components/schemas/CallbackInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/sale/1click": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/sale/1click",
                "description": "Request for OneClick payment through the payment method that supports such payments by using e-wallets",
                "operationId": "POST_v2-payment-wallet-payment-method-sale-1click",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "saved_account_id"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoWithId"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringInfo"
                                    },
                                    "saved_account_id": {
                                        "type": "integer"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/recurring": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/recurring",
                "description": "Request to perform regular payment from the customer's e-wallet",
                "operationId": "POST_v2-payment-wallet-payment-method-recurring",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment",
                                    "customer",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoWalletRecurring"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/1-tap": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/1-tap",
                "description": "Request for OneClick payment through the payment method that supports such payments by using e-wallets",
                "operationId": "POST_v2-payment-wallet-payment-method-1-tap",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/recurring/update": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/recurring/update",
                "description": "Request to update or change recurring conditions of the payment through the payment method that supports such payments by using e-wallets",
                "operationId": "POST_v2-payment-recurring-update",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringUpdateInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/recurring/cancel": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/recurring/cancel",
                "description": "Request to cancel recurring payments through the payment method that supports such payments by using e-wallets",
                "operationId": "POST_v2-payment-recurring-cancel",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "recurring": {
                                        "$ref": "#/components/schemas/RecurringIdInfo"
                                    },
                                    "interface_type": {
                                        "$ref": "#/components/schemas/SourceInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/refund": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/refund",
                "description": "Request for refund to the customer's e-wallet",
                "operationId": "POST_v2-payment-wallet-refund",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "merchant": {
                                        "$ref": "#/components/schemas/MerchantInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/RefundPaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/wallet/{payment_method}/payout": {
            "post": {
                "tags": [
                    "Wallet"
                ],
                "summary": "/v2/payment/wallet/{payment_method}/payout",
                "description": "Request for payout via methods that use e-wallets",
                "operationId": "POST_v2-payment-wallet-payment-method-payout",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "customer",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfoPayout"
                                    },
                                    "account": {
                                        "$ref": "#/components/schemas/AccountInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    },
                                    "return_url": {
                                        "$ref": "#/components/schemas/ReturnUrl"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GateSuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/info": {
            "post": {
                "tags": [
                    "Requests for customer details"
                ],
                "summary": "/v2/customer/info",
                "description": "Request for retrieving customer data by customer identifier within the project",
                "operationId": "POST_v2-customer-info",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "customer"
                                ],
                                "type": "object",
                                "properties": {
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerGeneralInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "customer",
                                        "signature"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "customer": {
                                            "required": [
                                                "ip_address",
                                                "project_id"
                                            ],
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "Customer identifier unique within the project"
                                                },
                                                "project_id": {
                                                    "type": "integer",
                                                    "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`"
                                                },
                                                "country": {
                                                    "pattern": "^[A-Z]{2}$",
                                                    "type": "string",
                                                    "description": "Customer country code in the ISO 3166-1 alpha-2 format"
                                                },
                                                "phone": {
                                                    "pattern": "^[0-9]{4,24}$",
                                                    "type": "string",
                                                    "description": "Customer's phone number, can be 4 to 24 digits long"
                                                },
                                                "email": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer email address",
                                                    "format": "email"
                                                },
                                                "day_of_birth": {
                                                    "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                                    "type": "string",
                                                    "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                                                },
                                                "first_name": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer first name"
                                                },
                                                "last_name": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer last name"
                                                },
                                                "address": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer address"
                                                },
                                                "zip": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer address postal code"
                                                },
                                                "city": {
                                                    "maxLength": 256,
                                                    "type": "string",
                                                    "description": "Name of customer's address city"
                                                },
                                                "street": {
                                                    "maxLength": 256,
                                                    "type": "string",
                                                    "description": "Street of customer address"
                                                },
                                                "browser": {
                                                    "maxLength": 512,
                                                    "type": "string",
                                                    "description": "A string that identifies the customer browser information"
                                                },
                                                "ip_address": {
                                                    "maxLength": 255,
                                                    "type": "string",
                                                    "description": "Customer IP address, both IPv4 and IPv6 are supported",
                                                    "format": "ip-address"
                                                },
                                                "billing": {
                                                    "type": "object",
                                                    "properties": {
                                                        "country": {
                                                            "pattern": "^[A-Z]{2}$",
                                                            "type": "string",
                                                            "description": "Country code of the customer's billing address in ISO 3166-1 alpha-2 format"
                                                        },
                                                        "region": {
                                                            "type": "string",
                                                            "description": "The region or state of the customer's billing address"
                                                        },
                                                        "city": {
                                                            "type": "string"
                                                        },
                                                        "address": {
                                                            "type": "string"
                                                        },
                                                        "postal": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "description": "Billing info"
                                                },
                                                "created_at": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "signature": {
                                            "type": "string",
                                            "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/saved_account/list": {
            "post": {
                "tags": [
                    "Requests for customer details"
                ],
                "summary": "/v2/customer/saved_account/list",
                "description": "Request for retrieving saved customer's payment instruments in the project",
                "operationId": "POST_v2-customer-saved_account-list",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "customer",
                                    "payment_method"
                                ],
                                "type": "object",
                                "properties": {
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerGeneralInfo"
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 255,
                                        "description": "Identifier of the payment method in the payment platform"
                                    }
                                },
                                "description": "Object that contains customer details"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "accounts",
                                        "signature"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "signature": {
                                            "type": "string",
                                            "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)."
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "description": "Array that contains information about the customer's saved payment accounts",
                                            "items": {
                                                "$ref": "#/components/schemas/SavedAccount"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorItems"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/customer/saved_account/delete": {
            "post": {
                "tags": [
                    "Requests for customer details"
                ],
                "summary": "/v2/customer/saved_account/delete",
                "description": "Request for removal of saved card or other saved account of the customer",
                "operationId": "POST_v2-customer-saved_account-delete",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "customer",
                                    "saved_account_id"
                                ],
                                "type": "object",
                                "properties": {
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerGeneralInfo"
                                    },
                                    "saved_account_id": {
                                        "type": "integer",
                                        "description": "The ID of the customer's saved account received from the payment platform"
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "default": "card",
                                        "enum": [
                                            "card"
                                        ],
                                        "description": "Payment method type for saved accounts set"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "message",
                                        "status"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "description": "Status of removing of the saved used account"
                                        },
                                        "message": {
                                            "type": "string",
                                            "description": "Notification of the removal of the saved customer's account"
                                        }
                                    },
                                    "description": ""
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorItems"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/payment/status/request": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/payment/status/request",
                "description": "Request for clarifying the status and other data of the payment by ProjectId and RequestId",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "project_id",
                                    "request_id",
                                    "signature"
                                ],
                                "type": "object",
                                "properties": {
                                    "project_id": {
                                        "type": "integer"
                                    },
                                    "request_id": {
                                        "maxLength": 100,
                                        "type": "string"
                                    },
                                    "signature": {
                                        "maxLength": 255,
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TransactionStatusResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Payment not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-internal": false
            }
        },
        "/v2/payment/status": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/payment/status",
                "description": "Request for retrieving the status and other data of the payment. Keep in mind that depending on the individual settings of the project the format of the response may vary. Presented below is the default format of the response",
                "operationId": "POST_v2-payment-status",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "destination": {
                                        "type": "string",
                                        "enum": [
                                            "merchant",
                                            "terminal"
                                        ],
                                        "default": "merchant",
                                        "description": "Destination of notification (terminal, merchant, etc.)"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaymentStatusResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorItems"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/info/available-methods/{payment_direction}/list": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/available-methods/{payment_direction}/list",
                "description": "Returns availability of requested payment methods",
                "operationId": "POST_v2-info-available-methods-list",
                "parameters": [
                    {
                        "name": "payment_direction",
                        "in": "path",
                        "description": "Payment direction",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "payin",
                                "payout"
                            ]
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "description": "Object that contains general request details",
                                        "type": "object",
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ],
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        }
                                    },
                                    "payment_method_list": {
                                        "type": "array",
                                        "description": "Array of elements containing information about requested payment methods",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "payment_method"
                                            ],
                                            "properties": {
                                                "payment_method": {
                                                    "type": "string",
                                                    "description": "Payment method code"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "description": "Array that contains information about payment methods",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorItems"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/info/banks/bycountry": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/bycountry",
                "operationId": "POST_v2-info-banks-bycountry",
                "description": "Returns bank list broken down by country",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "project_id",
                                    "signature",
                                    "country"
                                ],
                                "type": "object",
                                "properties": {
                                    "project_id": {
                                        "type": "integer"
                                    },
                                    "signature": {
                                        "type": "string"
                                    },
                                    "country": {
                                        "type": "string",
                                        "format": "[A-Z][A-Z][A-Z]"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/info/banks/byaggregator": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/byaggregator",
                "operationId": "POST_v2-info-banks-byaggregator",
                "description": "Returns bank list broken down by aggregator",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "project_id",
                                    "aggregator_id",
                                    "signature"
                                ],
                                "type": "object",
                                "properties": {
                                    "project_id": {
                                        "type": "integer"
                                    },
                                    "aggregator_id": {
                                        "type": "integer"
                                    },
                                    "signature": {
                                        "type": "string",
                                        "minLength": 1
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/info/banks/bypaymentmethod": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/bypaymentmethod",
                "operationId": "POST_v2-info-banks-bypaymentmethod",
                "description": "Returns bank list broken down by payment method",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "project_id",
                                    "payment_method_id",
                                    "signature"
                                ],
                                "type": "object",
                                "properties": {
                                    "project_id": {
                                        "type": "integer"
                                    },
                                    "payment_method_id": {
                                        "type": "integer"
                                    },
                                    "currency": {
                                        "type": "string",
                                        "pattern": "^[A-Z]{3}$",
                                        "description": "Currency in ISO 4217 alpha-3 format"
                                    },
                                    "type": {
                                        "type": "string"
                                    },
                                    "signature": {
                                        "type": "string",
                                        "minLength": 1
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/info/banks/byprovider": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/byprovider",
                "operationId": "POST_v2-info-banks-byprovider",
                "description": "Returns bank list broken down by provider",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "project_id",
                                    "provider_id",
                                    "signature"
                                ],
                                "type": "object",
                                "properties": {
                                    "project_id": {
                                        "type": "integer"
                                    },
                                    "provider_id": {
                                        "type": "integer"
                                    },
                                    "currency": {
                                        "type": "string",
                                        "pattern": "^[A-Z]{3}$",
                                        "description": "Currency in ISO 4217 alpha-3 format"
                                    },
                                    "type": {
                                        "type": "string"
                                    },
                                    "signature": {
                                        "type": "string",
                                        "minLength": 1
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/info/banks/{payment_method}/{operationType}/list": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/{payment_method}/{operationType}/list",
                "operationId": "POST_v2-info-banks-payment-method-operationType-list",
                "description": "Request to retrieve the list of banks available for the specified payment method and operation type",
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "description": "Payment method",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "operationType",
                        "in": "path",
                        "description": "Operation type",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentBanksInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/info/banks/{parentMethod}/{childMethod}/{operationType}/list": {
            "post": {
                "tags": [
                    "Requests for information",
                    "sync"
                ],
                "summary": "/v2/info/banks/{parentMethod}/{childMethod}/{operationType}/list",
                "operationId": "POST_v2-info-banks-parentMethod-childMethod-operationType-list",
                "description": "Request to retrieve the list of banks available for the specified payment method and operation type (for groupped methods)",
                "parameters": [
                    {
                        "name": "parentMethod",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "childMethod",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "operationType",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "payment"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "$ref": "#/components/schemas/GeneralInfo"
                                    },
                                    "customer": {
                                        "$ref": "#/components/schemas/CustomerInfo"
                                    },
                                    "payment": {
                                        "$ref": "#/components/schemas/PaymentInfo"
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid JSON data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "x-codegen-request-body-name": "request"
            }
        },
        "/v2/recurring/retry-custom-schedule/save": {
            "post": {
                "tags": [
                    "Requests for recurring"
                ],
                "summary": "/v2/recurring/retry-custom-schedule/save",
                "description": "Request to save custom recurring retry schedule",
                "operationId": "POST_v2-recurring-retry-custom-schedule-save",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "interval_days"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        },
                                        "description": "Object that contains general request details"
                                    },
                                    "interval_days": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 10,
                                        "uniqueItems": true,
                                        "description": "The schedule by days when retry attempts for charging funds should be made",
                                        "items": {
                                            "type": "integer",
                                            "minimum": 1,
                                            "maximum": 10
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "status"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "maxLength": 255,
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/recurring/retry-custom-schedule/info": {
            "post": {
                "tags": [
                    "Requests for recurring"
                ],
                "summary": "/v2/recurring/retry-custom-schedule/info",
                "description": "Request to get custom recurring retry schedule",
                "operationId": "POST_v2-recurring-retry-custom-schedule-info",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        },
                                        "description": "Object that contains general request details"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "project_id",
                                        "schedule"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "project_id": {
                                            "type": "integer",
                                            "description": "Identifier of merchant project received from Ecommpay"
                                        },
                                        "schedule": {
                                            "type": "object",
                                            "properties": {
                                                "interval_days": {
                                                    "type": "array",
                                                    "description": "The schedule by days when retry attempts for charging funds should be made",
                                                    "items": {
                                                        "type": "integer"
                                                    }
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "active",
                                                        "disabled"
                                                    ]
                                                }
                                            }
                                        }
                                    }
                                },
                                "examples": {
                                    "Example 1": {
                                        "value": {
                                            "project_id": 0,
                                            "schedule": {
                                                "interval_days": [
                                                    1
                                                ],
                                                "status": "active"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/recurring/retry-custom-schedule/disable": {
            "post": {
                "tags": [
                    "Requests for recurring"
                ],
                "summary": "/v2/recurring/retry-custom-schedule/disable",
                "description": "Request to disable custom recurring retry schedule",
                "operationId": "POST_v2-recurring-retry-custom-schedule-disable",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        },
                                        "description": "Object that contains general request details"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "status"
                                    ],
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "maxLength": 255,
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/recurring/retry_stop": {
            "post": {
                "tags": [
                    "Requests for recurring"
                ],
                "summary": "/v2/recurring/retry_stop",
                "description": "Request for restrict retry operation",
                "operationId": "POST_v2-recurring-retry_stop",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "general",
                                    "recurring",
                                    "trigger_operation_id"
                                ],
                                "type": "object",
                                "properties": {
                                    "general": {
                                        "type": "object",
                                        "description": "Object that contains general request details",
                                        "properties": {
                                            "project_id": {
                                                "type": "integer",
                                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                                "minimum": 1,
                                                "maximum": 4294967295
                                            },
                                            "signature": {
                                                "type": "string",
                                                "minLength": 1,
                                                "maxLength": 255,
                                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                                            }
                                        },
                                        "required": [
                                            "project_id",
                                            "signature"
                                        ]
                                    },
                                    "recurring": {
                                        "type": "object",
                                        "description": "Object that contains Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier",
                                        "properties": {
                                            "id": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "description": "Unique identifier of the recurring payment in the payment platform"
                                            }
                                        },
                                        "required": [
                                            "id"
                                        ]
                                    },
                                    "trigger_operation_id": {
                                        "description": "Identifier of operation which initiated retry",
                                        "type": "integer"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "400": {
                        "description": "Data validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Access denied",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid data structure or JSON parsing error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "AccountInfo": {
                "required": [
                    "number"
                ],
                "type": "object",
                "properties": {
                    "number": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1,
                        "description": "Customer's account number. Example: `21312`"
                    },
                    "save": {
                        "type": "boolean",
                        "default": false,
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    }
                },
                "description": "Object that contains the minimum required details of the customer's payment instrument - account/wallet/voucher etc."
            },
            "AccountAtmPayoutInfo": {
                "description": "Object that contains account information for payout performing by using ATMs",
                "type": "object",
                "properties": {
                    "bank_id": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Bank identifier received from the payment platform"
                    },
                    "customer_name": {
                        "type": "string",
                        "description": "Account owner full name",
                        "minLength": 1
                    },
                    "branch": {
                        "type": "string",
                        "description": "Bank branch",
                        "maxLength": 255
                    },
                    "number": {
                        "type": "string",
                        "description": "Customer's account number. Example: `21312`",
                        "minLength": 1
                    },
                    "region_id": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Region or state identifier of the bank branch location received from the payment platform. Example: `3`"
                    },
                    "city": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Bank branch city code"
                    }
                },
                "required": [
                    "bank_id",
                    "region_id"
                ]
            },
            "AccountBankInfo": {
                "description": "Object that contains the account details of bank which is used for payment processing",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/AccountInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Account type."
                            },
                            "bank_id": {
                                "type": "integer",
                                "minimum": 1,
                                "description": "Bank identifier received from the payment platform. Example: `137"
                            },
                            "customer_name": {
                                "type": "string",
                                "description": "First name and last name of the account holder. Example: `John Johnson`"
                            },
                            "security_code": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Payment confirmation code. Some payment methods may require this parameter (depending on the methods themselves). Example: `852923"
                            },
                            "swift_code": {
                                "type": "string",
                                "minLength": 8,
                                "maxLength": 11,
                                "description": "SWIFT bank identification code"
                            },
                            "routing_number": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Identifier of the bank in the transfer system"
                            },
                            "routing_type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Type of bank transfer. Possible values: `ACH CODE`—for the USA, `BANK CODE`—for Honkong, `BSB CODE`—for Australia, `IFSC`—for India, `SORT CODE`—for Great Britain, `TRANSIT NUMBER`—for Canada, `BRANCH CODE`—for Brazil, `SWIFT`—for other countries that support this method."
                            },
                            "iban": {
                                "type": "string",
                                "minLength": 5,
                                "maxLength": 34,
                                "description": "International bank account number"
                            },
                            "bank_name": {
                                "type": "string",
                                "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`"
                            },
                            "bank_branch_name": {
                                "type": "string",
                                "description": "Name of the bank branch"
                            },
                            "bank_branch_code": {
                                "type": "string",
                                "description": "Code of the bank branch"
                            },
                            "bank_branch_city": {
                                "type": "string",
                                "description": "City of the bank branch's location"
                            },
                            "bank_branch_address": {
                                "type": "string",
                                "description": "Address of bank branch"
                            },
                            "bank_code": {
                                "type": "string",
                                "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`"
                            },
                            "fin": {
                                "type": "string",
                                "description": "Financial institution number"
                            },
                            "country": {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Country code in the ISO 3166-1 alpha-2 format"
                            }
                        }
                    }
                ]
            },
            "AccountBankPayoutInfo": {
                "description": "Object that contains the details of the customer's bank account for payout performing",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/AccountInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "bank_id": {
                                "type": "integer",
                                "minimum": 1,
                                "description": "Bank identifier received from the payment platform"
                            },
                            "customer_name": {
                                "type": "string",
                                "description": "Account owner full name",
                                "minLength": 1
                            },
                            "branch": {
                                "type": "string",
                                "description": "Bank branch",
                                "maxLength": 255
                            },
                            "number": {
                                "type": "string",
                                "description": "Customer's account number. Example: `21312`",
                                "minLength": 1
                            },
                            "region_id": {
                                "type": "integer",
                                "minimum": 1,
                                "description": "Region or state identifier of the bank branch location received from the payment platform. Example: `3`"
                            },
                            "city": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Bank branch city code"
                            },
                            "bank_code": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`"
                            },
                            "bank_address": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Address of bank location"
                            },
                            "bik": {
                                "type": "string",
                                "minLength": 9,
                                "maxLength": 9,
                                "description": "Bank code on the Russian Federation"
                            },
                            "bank_name": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`"
                            },
                            "branch_code": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Bank branch code"
                            },
                            "native_customer_name": {
                                "type": "string",
                                "description": "Native account owner full name",
                                "minLength": 1
                            }
                        }
                    }
                ]
            },
            "AccountBankPurchaseInfo": {
                "type": "object",
                "properties": {
                    "bank_id": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Bank identifier received from the payment platform"
                    },
                    "number": {
                        "type": "string",
                        "description": "Customer's account number. Example: `21312`",
                        "minLength": 1
                    },
                    "bank_code": {
                        "type": "string",
                        "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`"
                    },
                    "customer_name": {
                        "type": "string",
                        "description": "Account owner full name",
                        "minLength": 1
                    }
                },
                "description": "Object that contains the details of the customer's bank account for payment performing"
            },
            "AccountBankRefundInfo": {
                "type": "object",
                "properties": {
                    "bank_id": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Bank identifier received from the payment platform"
                    },
                    "number": {
                        "type": "string",
                        "description": "Customer's account number. Example: `21312`",
                        "minLength": 1
                    },
                    "customer_name": {
                        "type": "string",
                        "description": "Account owner full name",
                        "minLength": 1
                    }
                },
                "description": "Object that contains the details of the customer's bank account for refund performing"
            },
            "AccountInfoAtMerchant": {
                "type": "object",
                "properties": {
                    "additional": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "Additional information about the customer's account in free text such as its identifier"
                    },
                    "date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date created account. Format: DD-MM-YYYY"
                    },
                    "change_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date of the most recent change of account data, excluding password updates or resets. Format: DD-MM-YYYY"
                    },
                    "pass_change_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date of the most recent password change or reset. Format: DD-MM-YYYY"
                    },
                    "purchase_number": {
                        "type": "integer",
                        "maximum": 9999,
                        "description": "Number of purchases made via the customer's account in the last 6 months, 4 characters maximum"
                    },
                    "provision_attempts": {
                        "type": "integer",
                        "maximum": 999,
                        "description": "Number of attempts to add a new card to a customer's account in the last 24 hours"
                    },
                    "activity_day": {
                        "type": "integer",
                        "maximum": 999,
                        "description": "Number of payment attempts in the last 24 hours"
                    },
                    "activity_year": {
                        "type": "integer",
                        "maximum": 999,
                        "description": "Number of payment attempts in the last 365 days"
                    },
                    "payment_age": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Card record creation date. Format: DD-MM-YYYY"
                    },
                    "suspicious_activity": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicator specifying whether the merchant has experienced suspicious activity on the cardholder account. Possible values: `01` —no suspicious activity detected, `02`—suspicious activity detected"
                    },
                    "auth_method": {
                        "type": "string",
                        "pattern": "^0[1-4]$",
                        "description": "Indicator specifying how the customer was authenticated during their most recent login to the web service. Possible values: `01`—no authentication, `02`—logging in with authentication data kept on file by the merchant,`03`—logging in with the federated identity credentials (for example, Google Account or Facebook ID), `04`—logging in with the use of FIDO authenticator (Fast Identity Online)"
                    },
                    "auth_time": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$",
                        "description": "Date and time of the customer's most recent account login. Format: DD-MM-YYYYhh:mm. Example: `01-10-202213:12`"
                    },
                    "auth_data": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Additional login information in free text"
                    },
                    "age_indicator": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "Number of days since the customer account was created. Possible values: `01`—guest checkout, `02`—the account was created at the moment of making a payment, `03`—fewer than 30 days, `04`—between 30 and 60 day, `05`—more than 60 days"
                    },
                    "change_indicator": {
                        "type": "string",
                        "pattern": "^0[1-4]$",
                        "description": "Number of days since the most recent change to the account, except for the password change or password reset. Possible values: `01`—the account was updated on the day when the payment was made, `02`—fewer than 30 days, `03`—between 30 and 60 days, `04`—more than 60 days"
                    },
                    "pass_change_indicator": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "Number of days since the most recent password change or reset. Possible values: `01`—password was not changed or reset, `02`—password was changed or reset on the day when the payment was made, `03`—fewer than 30 days, `04`—between 30 and 60 days, `05`—more than 60 days"
                    },
                    "payment_age_indicator": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "Number of days since the payment card details were saved to a customer's account. Possible values: 01—guest checkout, 02—card details were saved on the day when the payment was made, 03—fewer than 30 days, 04—between 30 and 60 days, 05—more than 60 days"
                    }
                },
                "description": "An object that contains account data in merchant's web service."
            },
            "AccountOnlineBankingPayoutInfo": {
                "type": "object",
                "properties": {
                    "number": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1,
                        "description": "Customer's account number. Example: `21312`"
                    },
                    "bank_code": {
                        "type": "string",
                        "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`"
                    },
                    "clearinghouse": {
                        "type": "string",
                        "maxLength": 255,
                        "minLength": 1,
                        "description": "Registration country of the interbank clearing center used by the bank of the account holder. Example: `SWEDEN`"
                    }
                },
                "description": "Object that contains the account details for payout processing"
            },
            "AccountVerificationPaymentInfo": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 0,
                        "description": "Payment amount in minor currency units, should be passed with zero value"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in ISO 4217 alpha-3 format"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description or comment"
                    },
                    "debt_account": {
                        "type": "string",
                        "maxLength": 10,
                        "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`"
                    }
                },
                "description": "Stub object that contains necessary details for payment instrument verification. Amount should be passed with zero value"
            },
            "AccountVerificationPaymentInfoForCard": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/AccountVerificationPaymentInfo"
                    },
                    {
                        "$ref": "#/components/schemas/CryptoPayment"
                    },
                    {
                        "type": "object",
                        "description": "Stub object that contains necessary details for payment instrument verification. Amount should be passed with zero value",
                        "properties": {
                            "debt_account": {
                                "type": "string",
                                "maxLength": 10,
                                "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`"
                            }
                        }
                    },
                    {
                        "$ref": "#/components/schemas/MotoInfo"
                    }
                ]
            },
            "ACSReturnUrl": {
                "type": "object",
                "properties": {
                    "return_url": {
                        "type": "string",
                        "description": "Return url for authenticated status"
                    },
                    "3ds_notification_url": {
                        "type": "string",
                        "description": "Url for callback from ACS"
                    }
                }
            },
            "AddendumData": {
                "type": "object",
                "properties": {
                    "lodging": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddendumLodgingInitial"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/AddendumLodgingInitial"
                                }
                            }
                        ]
                    },
                    "airlines": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddendumAirlines"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/AddendumAirlines"
                                }
                            }
                        ]
                    },
                    "professional_services": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddendumProfessionalServices"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/AddendumProfessionalServices"
                                }
                            }
                        ]
                    },
                    "retail": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddendumRetail"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/AddendumRetail"
                                }
                            }
                        ]
                    }
                }
            },
            "Addendum": {
                "type": "object",
                "properties": {
                    "lodging": {
                        "$ref": "#/components/schemas/AddendumLodging"
                    }
                }
            },
            "AddendumAirlines": {
                "required": [
                    "departure_airport",
                    "departure_date",
                    "departure_time",
                    "ticket",
                    "trip_leg"
                ],
                "type": "object",
                "properties": {
                    "departure_date": {
                        "type": "string",
                        "maxLength": 10,
                        "pattern": "^(?:\\d{2})(1[012]|0?[1-9])(3[01]|[12][0-9]|0?[1-9])$",
                        "description": "Departure date in YYMMDD format"
                    },
                    "departure_airport": {
                        "type": "string",
                        "maxLength": 3,
                        "description": "Originating airport name’s standard abbreviation"
                    },
                    "departure_time": {
                        "type": "string",
                        "maxLength": 4,
                        "pattern": "^([0-1][0-9]|2[0-3])[0-5][0-9]$",
                        "description": "Time of departure provided by the airline. Format: HHMM"
                    },
                    "arrival_time": {
                        "type": "string",
                        "maxLength": 4,
                        "pattern": "^([0-1][0-9]|2[0-3])[0-5][0-9]$",
                        "description": "Arrival time provided by the airline: Format: HHMM"
                    },
                    "endorsements_restr": {
                        "type": "string",
                        "maxLength": 20,
                        "description": ""
                    },
                    "exchange_ticket": {
                        "type": "string",
                        "maxLength": 15,
                        "description": "Original ticket number replaced by a new ticket number"
                    },
                    "ticket": {
                        "$ref": "#/components/schemas/AddendumAirlinesTicket"
                    },
                    "trip_leg": {
                        "$ref": "#/components/schemas/AddendumAirlinesTripLeg"
                    }
                }
            },
            "AddendumAirlinesTicket": {
                "required": [
                    "customer_ref",
                    "issuing_carrier",
                    "passenger_name",
                    "ticket_number"
                ],
                "type": "object",
                "properties": {
                    "passenger_name": {
                        "type": "string",
                        "maxLength": 20,
                        "description": "Name of the passenger to whom the ticket was issued"
                    },
                    "ticket_number": {
                        "type": "string",
                        "maxLength": 15,
                        "description": "Number on the ticket"
                    },
                    "issuing_carrier": {
                        "type": "string",
                        "maxLength": 2,
                        "description": "Standard abbreviation for the airline carrier issuing the ticket"
                    },
                    "customer_ref": {
                        "type": "string",
                        "maxLength": 25,
                        "description": "Number or code that identifies the customer or consumer."
                    },
                    "travel_agency_code": {
                        "type": "string",
                        "maxLength": 8,
                        "description": "Code assigned to the travel agency"
                    },
                    "travel_agency_name": {
                        "type": "string",
                        "maxLength": 25,
                        "description": "Name of the travel agency issuing the ticket"
                    },
                    "restricted_ticket_indicator": {
                        "type": "boolean",
                        "description": "Identifier noting that the ticket purchased has some restriction associated with its use"
                    },
                    "ticket_issue_date": {
                        "type": "string",
                        "maxLength": 10,
                        "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$",
                        "description": "Date in which the Ticket was Issued"
                    },
                    "total_tax_amount": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800`"
                    }
                }
            },
            "AddendumAirlinesTripLeg": {
                "required": [
                    "carrier_code",
                    "destination_airport",
                    "fare_bassis",
                    "flight_number",
                    "service_class",
                    "stop_over_code"
                ],
                "type": "object",
                "properties": {
                    "carrier_code": {
                        "type": "string",
                        "maxLength": 2,
                        "description": "Standard abbreviation for the airline carrier"
                    },
                    "service_class": {
                        "type": "string",
                        "maxLength": 1,
                        "pattern": "^([F|J|Y|W])$",
                        "description": "Service type (such as coach or first class)"
                    },
                    "destination_airport": {
                        "type": "string",
                        "maxLength": 3,
                        "description": "Destination airport name’s standard abbreviation"
                    },
                    "stop_over_code": {
                        "type": "boolean",
                        "description": "Code indicating whether there was a direct or a non-direct flight or route on the same ticket number"
                    },
                    "fare_bassis": {
                        "type": "string",
                        "maxLength": 6,
                        "description": "Code that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable"
                    },
                    "flight_number": {
                        "type": "string",
                        "maxLength": 5,
                        "description": "Number that the operating or marketing carrier assigned"
                    }
                }
            },
            "AddendumInitialCard": {
                "type": "object",
                "description": "Available to merchants with eligible MCCs",
                "properties": {
                    "airlines": {
                        "$ref": "#/components/schemas/AddendumAirlinesCard"
                    },
                    "lodging": {
                        "$ref": "#/components/schemas/AddendumLodgingInitial"
                    }
                }
            },
            "AddendumAirlinesCard": {
                "required": [
                    "ticket_number",
                    "passenger_name",
                    "customer_ref",
                    "ticket_issuer_code",
                    "ticket_issue_date",
                    "trip_legs"
                ],
                "type": "object",
                "properties": {
                    "ticket_number": {
                        "type": "string",
                        "maxLength": "15",
                        "description": "Ticket number assigned by the issuer",
                        "example": "1051426005635"
                    },
                    "passenger_name": {
                        "type": "string",
                        "maxLength": "20",
                        "description": "Full passenger name (name and last name, title if available)",
                        "example": "EDDINGTON/ARTHUR MR"
                    },
                    "ticket_issuer_code": {
                        "type": "string",
                        "maxLength": "2",
                        "description": "IATA 2-character code of the airline that issued the ticket",
                        "example": "AY"
                    },
                    "ticket_issue_date": {
                        "type": "string",
                        "format": "date",
                        "description": "Date of ticket issuance, in ISO 8601 (YYYY-MM-DD) format",
                        "example": "2025-10-04"
                    },
                    "customer_ref": {
                        "type": "string",
                        "maxLength": "25",
                        "description": "Identifier of the passenger record in the reservation system",
                        "example": "T7H3PD"
                    },
                    "travel_agency_code": {
                        "type": "string",
                        "maxLength": "8",
                        "description": "IATA-accreditation code assigned to a travel agency",
                        "example": "2921540"
                    },
                    "travel_agency_name": {
                        "type": "string",
                        "maxLength": "25",
                        "description": "Name of the travel agency that issued the ticket",
                        "example": "Deep Sky Tours"
                    },
                    "restricted_ticket_indicator": {
                        "type": "boolean",
                        "description": "Indicator that specifies refund restrictions applied to the ticket, (i.e. the ticket is non-refundable or can be returned)",
                        "example": true
                    },
                    "computerized_reservation_system": {
                        "type": "string",
                        "maxLength": "4",
                        "description": "Code of the computerised reservation system, may be needed for payments in Germany, (STRT – Start, PARS – TWA, DATS – Delta, SABR – Sabre, DALA – Covia-Apollo, BLAN – Dr. Blank, DERD – DER, TUID – TUI)",
                        "example": "TUID"
                    },
                    "total_fare_amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Total amount of the ticket",
                        "example": 23500
                    },
                    "total_tax_amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Amount of all the taxes associated with the ticket",
                        "example": 135
                    },
                    "total_fees_amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Amount of the fees associated with the ticket",
                        "example": 1447
                    },
                    "trip_legs": {
                        "required": [
                            "trip_leg1"
                        ],
                        "type": "object",
                        "properties": {
                            "trip_leg1": {
                                "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg"
                            },
                            "trip_leg2": {
                                "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg"
                            },
                            "trip_leg3": {
                                "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg"
                            },
                            "trip_leg4": {
                                "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg"
                            }
                        }
                    }
                }
            },
            "AddendumAirlinesCardTripLeg": {
                "required": [
                    "flight_number",
                    "carrier_code",
                    "departure_airport",
                    "departure_at",
                    "destination_airport",
                    "arrival_at",
                    "stop_over_code",
                    "service_class",
                    "fare_bassis"
                ],
                "type": "object",
                "properties": {
                    "flight_number": {
                        "type": "string",
                        "maxLength": "5",
                        "description": "The flight number assigned by operating or marketing carrier. Airline carrier code must not be included",
                        "example": "156"
                    },
                    "carrier_code": {
                        "type": "string",
                        "maxLength": "2",
                        "description": "2-character IATA carrier code",
                        "example": "AY"
                    },
                    "departure_airport": {
                        "type": "string",
                        "maxLength": "3",
                        "description": "3-character IATA code of the departure airport",
                        "example": "IVL"
                    },
                    "departure_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Date and time of departure, in the YYYY-MM-DDThh:mm:ss±hh:mm format (according to ISO 8601)",
                        "example": "2025-10-31T16:05:00+02:00"
                    },
                    "destination_airport": {
                        "type": "string",
                        "maxLength": "3",
                        "description": "3-character IATA code of the destination airport",
                        "example": "PFO"
                    },
                    "arrival_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Date and time of arrival, in the YYYY-MM-DDThh:mm:ss±hh:mm format (according to ISO 8601)",
                        "example": "2025-10-31T20:15:00+02:00"
                    },
                    "stop_over_code": {
                        "type": "boolean",
                        "description": "Indicates whether the flight is direct (no stopover) or non-direct (includes stopover)",
                        "example": true
                    },
                    "service_class": {
                        "type": "string",
                        "maxLength": "1",
                        "description": "IATA code of service class (R – Supersonic, P – First Class Premium, F – First Class, A – First Class Discounted; J – Business Class Premium, C – Business Class, {D, I, Z} – Business Class Discounted; W – Economy/Coach Premium, {S, Y} – Economy/Coach, {B, H, K, L, M, N, Q, T, V, X} – Economy/Coach Discounted)",
                        "example": "Y"
                    },
                    "fare_bassis": {
                        "type": "string",
                        "maxLength": "6",
                        "description": "Particular fare applied by the carrier",
                        "example": "YE3MFI"
                    },
                    "exchange_ticket": {
                        "type": "string",
                        "maxLength": "15",
                        "description": "The original ticket number replaced by a new ticket number (if applicable)",
                        "example": "3904082308998"
                    },
                    "conjunct_ticket": {
                        "type": "string",
                        "maxLength": "15",
                        "description": "The ticket that contains additional coupons on an itinerary that is more than four segments (if present)",
                        "example": "6065511855011"
                    },
                    "coupon_number": {
                        "type": "string",
                        "maxLength": "3",
                        "pattern": "\\d",
                        "description": "Number of a coupon assigned to the leg inside the ticket",
                        "example": "1"
                    },
                    "endorsements_restr": {
                        "type": "string",
                        "maxLength": "20",
                        "description": "Added notation specifying any relevant information about restrictions, additional data, and endorsement information",
                        "example": "No changes allowed"
                    }
                }
            },
            "AddendumLodging": {
                "type": "object",
                "properties": {
                    "check_out_date": {
                        "maxLength": 19,
                        "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$",
                        "type": "string",
                        "description": "Customer's check-out date in the dd-mm-yyyy format. Example: `22-12-2019`"
                    },
                    "room": {
                        "type": "object",
                        "properties": {
                            "rate": {
                                "maximum": 999999999999,
                                "type": "integer",
                                "description": "Daily room charges exclusive of taxes and fees. Is used to calculate base lodging cost. This psrsmeter is provided in minor units of currency. Example: `12`"
                            },
                            "number_of_nights": {
                                "maximum": 99,
                                "minimum": 1,
                                "type": "integer",
                                "description": "Total number of nights for which a room was contracted during a lodging stay.  Example: `10"
                            }
                        }
                    },
                    "total_tax": {
                        "maximum": 999999999999,
                        "minimum": 0,
                        "type": "number",
                        "description": "Total amount of sales tax or value added tax (VAT) on the total purchase amount. This parameter is provided in minor units of the payment's currency"
                    },
                    "charges": {
                        "$ref": "#/components/schemas/AddendumLodgingCharges"
                    }
                },
                "description": "Available only if MCC is 3501-3999 or 7011"
            },
            "AddendumLodgingCharges": {
                "type": "object",
                "properties": {
                    "room_service": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the room service charges. This parameter provided in minor units of currency"
                    },
                    "bar_or_lounge": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the lounge or bar charges. This parameter provided in minor units of currency"
                    },
                    "transportation": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the transportation charges. This parameter provided in minor units of currency"
                    },
                    "gratuity": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the gratuity charges. This parameter provided in minor units of currency"
                    },
                    "conference_room": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the charges associated with conference room use. This parameter provided in minor units of currency"
                    },
                    "audio_or_visual": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the audiovisual equipment charges. This parameter provided in minor units of currency"
                    },
                    "banquet": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the banquet charges. This parameter provided in minor units of currency"
                    },
                    "internet_access": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of the Internet access charges. This parameter provided in minor units of currency"
                    },
                    "early_departure": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount charged because of early departure. This parameter provided in minor units of currency"
                    },
                    "phone": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of charges for all phone calls. This parameter provided in minor units of currency"
                    },
                    "restaurant": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of all restaurant charges. This parameter provided in minor units of currency"
                    },
                    "minibar": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of in-room “mini-bar” service charges. This parameter provided in minor units of currency"
                    },
                    "gift_shop": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of all gift shop and specialty shop charges. This parameter provided in minor units of currency"
                    },
                    "laundry_or_cleaning": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount of cleaning charges. This parameter provided in minor units of currency"
                    },
                    "valet": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Charges associated with the use of valet services. This parameter provided in minor units of currency"
                    },
                    "movie": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount charged for in-room movies. This parameter provided in minor units of currency"
                    },
                    "business_center": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount charged for business center use and supplies. This parameter provided in minor units of currency"
                    },
                    "health_club": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "Amount charged for health club use and supplies. This parameter provided in minor units of currency"
                    }
                }
            },
            "AddendumLodgingInitial": {
                "required": [
                    "check_in_date",
                    "check_out_date",
                    "customer_service_toll_free_number",
                    "fire_safety_act_indicator",
                    "folio_number",
                    "room"
                ],
                "type": "object",
                "properties": {
                    "customer_service_toll_free_number": {
                        "type": "string",
                        "maxLength": 17,
                        "description": "A toll-free phone number for the customer service of the booked hotel or other type of accommodation. Example: `18005553535`"
                    },
                    "hotel_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Name of the hotel or other type of accommodation where the customer is staying. Example:`Best Eastern`"
                    },
                    "check_in_date": {
                        "type": "string",
                        "maxLength": 19,
                        "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$",
                        "description": "Customer's check-in date in the dd-mm-yyyy format. Example: `10-12-2019`"
                    },
                    "check_out_date": {
                        "type": "string",
                        "maxLength": 19,
                        "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$",
                        "description": "Customer's check-out date in the dd-mm-yyyy format. Example: `22-12-2019`"
                    },
                    "folio_number": {
                        "type": "string",
                        "maxLength": 25,
                        "description": "Card acceptor’s internal invoice or billing ID reference number. Example: `56265655ABC`"
                    },
                    "room": {
                        "description": "Object with room details",
                        "properties": {
                            "tax": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 999999999999,
                                "description": "Tax amount information such as the daily room tax, occupancy tax, energy tax, and tourist tax amounts. Example: `25`"
                            },
                            "rate": {
                                "type": "integer",
                                "maximum": 999999999999,
                                "description": "Daily room charges exclusive of taxes and fees. this parameter is used to calculate base lodging cost and is provided in minor units of currency. Example: `12`"
                            },
                            "number_of_nights": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 99,
                                "description": "Total number of nights for which room was contracted during lodging stay"
                            }
                        },
                        "required": [
                            "rate"
                        ]
                    },
                    "fire_safety_act_indicator": {
                        "type": "boolean",
                        "description": "Facility complies with the Hotel and Motel Fire Safety Act of 1990 (PL101-391) or similar legislation"
                    },
                    "guest_name": {
                        "type": "string",
                        "maxLength": 40,
                        "description": "Customer full name"
                    },
                    "guest_number": {
                        "type": "string",
                        "maxLength": 25,
                        "description": "Number assigned to the lodging customer"
                    },
                    "billing_adjustment": {
                        "type": "string",
                        "maxLength": 12,
                        "description": "Additional charges incurred after the cardholder departure"
                    },
                    "property_phone_number": {
                        "type": "string",
                        "maxLength": 17,
                        "description": "Specific lodging property location by its local phone number"
                    },
                    "no_show_indicator": {
                        "type": "boolean",
                        "description": "Customer did not show up after making lodging reservation"
                    },
                    "prepaid_expenses": {
                        "type": "integer",
                        "maximum": 999999999999,
                        "description": "Amount of deposit or other prepaid amounts for the lodging stay. This parameter is provided in minor units of currency."
                    },
                    "total_tax": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 999999999999,
                        "description": "The amount of all the taxes associated with the lodging. Applicable only to the Visa, Visa Electron and Maestro cards. Not applicable for Mastercard. This parameter is provided in minor units of the payment's currency"
                    },
                    "charges": {
                        "$ref": "#/components/schemas/AddendumLodgingCharges"
                    }
                },
                "description": "Available only if MCC is 3501-3999 or 7011"
            },
            "AddendumProfessionalServices": {
                "required": [
                    "admission_notice_url"
                ],
                "type": "object",
                "properties": {
                    "admission_notice_url": {
                        "type": "string",
                        "description": "Admission notice url"
                    }
                }
            },
            "AddendumRetail": {
                "required": [
                    "goods",
                    "quantity"
                ],
                "type": "object",
                "properties": {
                    "goods": {
                        "type": "string",
                        "description": "Name goods"
                    },
                    "quantity": {
                        "type": "integer",
                        "description": "Quantity goods"
                    }
                }
            },
            "AdditionalData": {
                "type": "object",
                "properties": {
                    "avs_data": {
                        "$ref": "#/components/schemas/AvsInfo"
                    }
                },
                "description": "Object that contains additional payment information submission for payment processing. The object can contain any objects requested by the payment platform as specified in the **clarification_fields** object"
            },
            "AnotherAccountBankInfo": {
                "description": "Object that contains the account details of bank which is used for payment processing. Used when account number is not required.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/AnotherAccountInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Account type."
                            },
                            "bank_id": {
                                "oneOf": [
                                    {
                                        "type": "string",
                                        "minLength": 1,
                                        "description": "Bank identifier received from the payment platform"
                                    },
                                    {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Bank identifier"
                                    }
                                ]
                            },
                            "customer_name": {
                                "type": "string",
                                "description": "Bank account's owner full name"
                            },
                            "security_code": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "First 2 digits of the password"
                            },
                            "swift_code": {
                                "type": "string",
                                "minLength": 8,
                                "maxLength": 11,
                                "description": "SWIFT bank identification code"
                            },
                            "routing_number": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Bank account's routing number"
                            },
                            "routing_type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Bank account's routing type"
                            },
                            "iban": {
                                "type": "string",
                                "minLength": 5,
                                "maxLength": 34,
                                "description": "International bank account number"
                            },
                            "bank_name": {
                                "type": "string",
                                "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`"
                            },
                            "bank_branch_name": {
                                "type": "string",
                                "description": "Bank branch name"
                            },
                            "bank_branch_code": {
                                "type": "string",
                                "description": "Bank branch code"
                            },
                            "bank_branch_city": {
                                "type": "string",
                                "description": "City of bank branch location"
                            },
                            "bank_branch_address": {
                                "type": "string",
                                "description": "Address of bank branch location"
                            },
                            "bank_code": {
                                "type": "string",
                                "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`"
                            },
                            "fin": {
                                "type": "string",
                                "description": "Financial institution number"
                            },
                            "country": {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Country code in the ISO 3166-1 alpha-2 format"
                            }
                        }
                    }
                ]
            },
            "AnotherAccountInfo": {
                "type": "object",
                "properties": {
                    "number": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1,
                        "description": "Customer's account number. Example: `21312`"
                    },
                    "save": {
                        "type": "boolean",
                        "default": false,
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    }
                },
                "description": "Object that contains the minimum required details of the customer's payment instrument - account/wallet/voucher etc. Used when account number is not required."
            },
            "ApplePaySessionPaymentInfo": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in the ISO 4217 alpha-3 format"
                    },
                    "customer_amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000000000000,
                        "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description or comment for additional data analisys by using Dashboard"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "best_before": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Payment expiration date in the date-time format according to the ISO 8601 standart"
                    },
                    "challenge_indicator": {
                        "type": "string",
                        "pattern": "^0[1-9]$",
                        "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "challenge_window": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "The dimensions of a window in which the authentication page opens.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "reorder": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_purchase": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Parameter specifying whether the current purchase is pre-ordered.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format"
                    },
                    "gift_card": {
                        "$ref": "#/components/schemas/GiftCardInfo"
                    },
                    "device_channel": {
                        "type": "string",
                        "pattern": "^0[1-3]$",
                        "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined"
                    }
                },
                "description": "Object that contains payment details"
            },
            "AuthenticationData": {
                "required": [
                    "xid"
                ],
                "type": "object",
                "properties": {
                    "cavv": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Cardholder authentication verification value. Mandatory if `authentication_status`=`Y` or `A`"
                    },
                    "ds_operation_id": {
                        "type": "string",
                        "maxLength": 36,
                        "description": "Operation identifier assigned by the Directory Server"
                    },
                    "eci": {
                        "type": "string",
                        "enum": [
                            "00",
                            "01",
                            "02",
                            "05",
                            "06",
                            "07"
                        ],
                        "description": "The electronic commerce indicator"
                    },
                    "threeds_version": {
                        "type": "string",
                        "enum": [
                            "3ds_1",
                            "3ds_2",
                            "non_3ds"
                        ],
                        "description": "Indicator of the 3‑D Secure authentication"
                    },
                    "xid": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "The operation identifier (Base64-encoded, 20 bytes in a decoded form)"
                    },
                    "enrollement_status": {
                        "type": "string",
                        "enum": [
                            "Y",
                            "N",
                            "U"
                        ],
                        "description": "The enrollment response from the VERes message from the directory server ('Y','N','U'). Supported for 3D Secure 1"
                    },
                    "authentication_status": {
                        "type": "string",
                        "enum": [
                            "Y",
                            "U",
                            "A"
                        ],
                        "description": "Customer's authentication status. Possible values: `Y`—the cardholder was successfully authenticated by their card issuer, `A`—the cardholder authentication was attempted, `U`—the card issuer was unavailable during the authentication attempt"
                    },
                    "authentication_flow": {
                        "type": "string",
                        "enum": [
                            "Frictionless",
                            "Challenge"
                        ],
                        "description": "The indicator of the flow that was used for the customer 3-D Secure 2 authentication on the merchant side within the operation being processed"
                    },
                    "threeds_full_version": {
                        "type": "string",
                        "description": "The full version of the 3-D Secure protocol",
                        "example": "2.3.1",
                        "maxLength": 8,
                        "minLength": 5,
                        "pattern": "^(\\d{1,2})\\.(\\d{1,2})\\.(\\d{1,2})(\\.(\\d{1,2}))?$"
                    },
                    "authentication_status_reason_code": {
                        "type": "string",
                        "description": "Reason code for `authentication_status`",
                        "maxLength": 2,
                        "minLength": 2,
                        "example": "01"
                    }
                },
                "description": "Object that contains 3DS Authentication Data from merchant"
            },
            "AvsInfo": {
                "required": [
                    "avs_post_code",
                    "avs_street_address"
                ],
                "type": "object",
                "properties": {
                    "avs_post_code": {
                        "type": "string",
                        "description": "Postal code of the customer. Example: `WS13 6LG`",
                        "minLength": 1
                    },
                    "avs_street_address": {
                        "type": "string",
                        "description": "Address of the customer. Example: `4 Breadmarket Street`",
                        "minLength": 1
                    }
                },
                "description": "Object that contains customer details for verification by the Address Verification Service. For more information, see [AVS Check](https://developers.ecommpay.com/en/en_Gate_avs.html)"
            },
            "BankTransferCustomerInfo": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "building": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Customer building number"
                            }
                        }
                    }
                ]
            },
            "BookingInfo": {
                "type": "object",
                "description": "Object that contains general booking details",
                "properties": {
                    "bookers": {
                        "type": "array",
                        "description": "List of customers included in the booking",
                        "additionalProperties": false,
                        "uniqueItems": true,
                        "items": {
                            "type": "object",
                            "description": "Object that contains booker details",
                            "additionalProperties": false,
                            "properties": {
                                "first_name": {
                                    "maxLength": 255,
                                    "type": "string",
                                    "description": "First name of the customer provided at the time of booking. Example: `William`"
                                },
                                "last_name": {
                                    "maxLength": 255,
                                    "type": "string",
                                    "description": "Last name of the customer provided at the time of booking. Example: `Herschel`"
                                },
                                "email": {
                                    "maxLength": 255,
                                    "type": "string",
                                    "format": "email",
                                    "description": " Email provided at the time of booking.  Example: `rsfellow@mail.com`"
                                }
                            }
                        }
                    },
                    "items": {
                        "type": "array",
                        "description": "List of services included in the booking",
                        "additionalProperties": false,
                        "uniqueItems": true,
                        "items": {
                            "type": "object",
                            "description": "Object that contains the details of each service included in the booking",
                            "additionalProperties": false,
                            "properties": {
                                "description": {
                                    "type": "string",
                                    "maxLength": 255,
                                    "description": "Description of the service included in the booking. Example: `VIP Arrival`"
                                },
                                "start_date": {
                                    "type": "string",
                                    "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                    "description": "Starting date of the service included in the booking, in the DD-MM-YYYY format. Example: `12-08-2026`"
                                },
                                "end_date": {
                                    "type": "string",
                                    "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                    "description": "Ending date of the service included in the booking, in the DD-MM-YYYY format. Example: `12-08-2026`"
                                }
                            }
                        }
                    },
                    "start_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Starting date of the booked service, in the DD-MM-YYYY format. Example: `12-08-2026`"
                    },
                    "end_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Ending date of the booked service, in the DD-MM-YYYY format. Example: `13-08-2026`"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Free-form description of the booked service. Example: `Siders music festival full pass`"
                    },
                    "total": {
                        "type": "integer",
                        "description": "The total cost of the booking in minor units of currency. Value cannot be`0`. Example: `200000`"
                    },
                    "pax": {
                        "type": "integer",
                        "description": "Number of people per booking. Value cannot be `0`. Example: `4`"
                    },
                    "reference": {
                        "type": "string",
                        "maxLength": 255,
                        "description": " Booking reference, which can be the URL, the name of the booked service, or its code in the merchant's web service. Example: `musicfestlink`"
                    },
                    "id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Identifier of the booking, unique in the merchant's web service. Example: `83`"
                    }
                }
            },
            "CallbackInfo": {
                "type": "object",
                "properties": {
                    "delay": {
                        "type": "integer",
                        "description": "Delay time for sending callbacks, in seconds. Example: `42`",
                        "minimum": 0,
                        "maximum": 600
                    },
                    "force_disable": {
                        "type": "boolean",
                        "description": "Indicator for disabling callbacks. Possible values: `true`—for disabling callbacks with information about the given payment, and `false`—for enabling these callbacks"
                    }
                },
                "description": "Object that contains additional callback sending conditions"
            },
            "CancelPaymentInfo": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Refund amount in minor currency units"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Currency code in ISO-4217 alpha-3 format"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Refund description or comment"
                    }
                },
                "description": "Object that contains information about refund"
            },
            "CardInfo": {
                "required": [
                    "month",
                    "pan",
                    "year"
                ],
                "type": "object",
                "properties": {
                    "pan": {
                        "type": "string",
                        "format": "pan",
                        "maxLength": 32,
                        "description": "For cards - the number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. For network tokens - the token without masked characters, spaces, or other separator. Example:`4314220000000056`"
                    },
                    "year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "For cards - the year of the card's expiration date. For network tokens - the year of the token's expiration date (according to the Gregorian calendar)"
                    },
                    "month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "For cards - the month of the card's expiration date. For network tokens - the month of the token's expiration date"
                    },
                    "card_holder": {
                        "type": "string",
                        "maxLength": 255,
                        "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                        "description": "Name of the cardholder as specified on the payment card"
                    },
                    "cvv": {
                        "type": "string",
                        "pattern": "^[0-9]{3,4}$",
                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession"
                    },
                    "security_code": {
                        "type": "string",
                        "pattern": "^[0-9]{2}$",
                        "description": "First 2 digits of the password."
                    },
                    "save": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    },
                    "stored_card_type": {
                        "$ref": "#/components/schemas/StoredCardType"
                    }
                },
                "description": "Object that contains the information about customer's card that is used for payment. Contains parameters to specify card details or the information about the network token associated with the card"
            },
            "CardInfoForSaleAuth": {
                "required": [
                    "month",
                    "pan",
                    "year"
                ],
                "type": "object",
                "properties": {
                    "pan": {
                        "type": "string",
                        "format": "pan",
                        "maxLength": 32,
                        "description": "For cards - the number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. For network tokens - the token without masked characters, spaces, or other separator. Example:`4314220000000056`"
                    },
                    "year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "For cards - the year of the card's expiration date. For network tokens - the year of the token's expiration date (according to the Gregorian calendar)"
                    },
                    "month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "For cards - the month of the card's expiration date. For network tokens - the month of the token's expiration date"
                    },
                    "card_holder": {
                        "type": "string",
                        "maxLength": 255,
                        "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                        "description": "Name of the cardholder as specified on the payment card"
                    },
                    "cvv": {
                        "type": "string",
                        "pattern": "^[0-9]{3,4}$",
                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession"
                    },
                    "security_code": {
                        "type": "string",
                        "pattern": "^[0-9]{2}$",
                        "description": "First 2 digits of the password"
                    },
                    "save": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    },
                    "stored_card_type": {
                        "$ref": "#/components/schemas/StoredCardType"
                    }
                },
                "description": "Object that contains the information about customer's card that is used for payment. Contains parameters to specify card details or the information about the network token associated with the card"
            },
            "CardInfoForTokenize": {
                "required": [
                    "month",
                    "pan",
                    "year"
                ],
                "type": "object",
                "properties": {
                    "pan": {
                        "type": "string",
                        "format": "pan",
                        "maxLength": 32,
                        "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`"
                    },
                    "year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "Year of the card's expiration date, intended to indicate the last valid year for card usage"
                    },
                    "month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "Month of the card's expiration date, intended to indicate the last valid month for card usage"
                    },
                    "card_holder": {
                        "type": "string",
                        "maxLength": 255,
                        "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                        "description": "Name of the cardholder as specified on the payment card"
                    }
                },
                "description": "Object that contains the customer's card details that is used for tokenize"
            },
            "CardInfoLight": {
                "required": [
                    "pan"
                ],
                "type": "object",
                "properties": {
                    "pan": {
                        "type": "string",
                        "format": "pan",
                        "maxLength": 32,
                        "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`"
                    },
                    "year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "Year of the card's expiration date, intended to indicate the last valid year for card usage"
                    },
                    "month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "Month of the card's expiration date, intended to indicate the last valid month for card usage"
                    },
                    "issue_year": {
                        "type": "integer",
                        "maximum": 9999,
                        "description": "Year of issuing date of the card"
                    },
                    "issue_month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "Month of issuing date of the card"
                    },
                    "card_holder": {
                        "type": "string",
                        "maxLength": 255,
                        "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                        "description": "Name of the cardholder as specified on the payment card"
                    },
                    "cvv": {
                        "type": "string",
                        "pattern": "^[0-9]{3,4}$",
                        "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession"
                    },
                    "save": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    },
                    "stored_card_type": {
                        "$ref": "#/components/schemas/StoredCardType"
                    }
                },
                "description": "Object that contains the customer's card details that is used for payment"
            },
            "CupReturnUrl": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/ReturnUrl"
                    },
                    {
                        "type": "object",
                        "required": [
                            "success"
                        ]
                    }
                ]
            },
            "CustomerGeneralInfo": {
                "required": [
                    "id",
                    "project_id",
                    "signature"
                ],
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Customer identifier unique within the project"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    }
                },
                "description": "Object that contains general customer details in merchant project"
            },
            "CustomerInfo": {
                "description": "Object that contains customer details",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfoBase"
                    },
                    {
                        "type": "object",
                        "required": [
                            "ip_address"
                        ]
                    }
                ]
            },
            "CustomerInfoBase": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer identifier unique within the project"
                    },
                    "identification_level": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Indicator specifying whether the customer is trusted; provided by the merchant. Example: `1`—the customer is trusted"
                    },
                    "country": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                    },
                    "city": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "Name of customer's address city"
                    },
                    "state": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "Name of the region (state, province, or other administrative subdivision type) of the customer's address. Example: `Greater London`"
                    },
                    "phone": {
                        "type": "string",
                        "pattern": "^[0-9]{4,24}$",
                        "description": "Customer's phone number, can be 4 to 24 digits long"
                    },
                    "iin": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer's individual identification number. Issued by the government or other official authority. Can be used for identity verification, regulatory compliance, and fraud prevention checks"
                    },
                    "home_phone": {
                        "type": "string",
                        "pattern": "^[0-9]{4,24}$",
                        "description": "Customer's home phone number, can be 4 to 24 digits long"
                    },
                    "work_phone": {
                        "type": "string",
                        "pattern": "^[0-9]{4,24}$",
                        "description": "Customer's work phone number, can be 4 to 24 digits long"
                    },
                    "save": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    },
                    "account_save": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's account details should be saved"
                    },
                    "day_of_birth": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                    },
                    "person_type": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Type of the customer as a legal person, for example, a company or an individual, used for compliance"
                    },
                    "birthplace": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Name of the customer's birthplace (e.g., town, city, or other settlement type). Example: `London`"
                    },
                    "first_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "First name of the customer. Example: `Jane`"
                    },
                    "middle_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Middle, second, or patronymic name of the customer. Example: `Mary`"
                    },
                    "last_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Last name of the customer. Example: `Smith`"
                    },
                    "email": {
                        "type": "string",
                        "maxLength": 255,
                        "format": "email",
                        "description": "Email address of the customer. The string consists of a local-part and a domain name, separated by the `@` symbol. Example: `helen@example.com`."
                    },
                    "browser": {
                        "type": "string",
                        "maxLength": 512,
                        "description": "Name and version of the customer's browser used to access the web service. Can be used to identify the customer environment for risk and fraud analysis"
                    },
                    "ip_address": {
                        "type": "string",
                        "maxLength": 255,
                        "format": "ip-address",
                        "description": "IP address of the customer's device. Can be used for security checks, geolocation, and fraud prevention"
                    },
                    "device_type": {
                        "type": "string",
                        "description": "Browser engine that can be used for rendering web pages. Example: `WebKit`"
                    },
                    "device_id": {
                        "type": "string",
                        "description": "Identifier of the customer's device"
                    },
                    "datetime": {
                        "type": "string",
                        "format": "dateTime",
                        "description": "Date and time when the payment form was opened by the customer in the YYYY-MM-DD hh-mm-ss format. Useful for tracking customer activity and timing of payment initiation. Example: `2022-01-01 15:15:15`"
                    },
                    "screen_res": {
                        "type": "string",
                        "description": "Screen resolution of the customer's device, in pixels, with an `x` character as a delimiter. Example: `360x640`"
                    },
                    "session_id": {
                        "type": "string",
                        "description": "Identifier of the session cookie used by the customer"
                    },
                    "language": {
                        "type": "string",
                        "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`"
                    },
                    "zip": {
                        "type": "string",
                        "maxLength": 10,
                        "description": "Postal or zip code in the customer's address. Example: `75001`"
                    },
                    "address": {
                        "type": "string",
                        "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the customer. Example: `Via Dietro Duomo 36`"
                    },
                    "district": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "District of the customer's address"
                    },
                    "street": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Name of the street in the customer's address. Example: `Breadmarket Street`"
                    },
                    "building": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Building number in the customer’s address. Example: `4`"
                    },
                    "account_id": {
                        "type": "string",
                        "description": "Identifier of the customer's account in the external payment system"
                    },
                    "gender": {
                        "type": "string",
                        "enum": [
                            "male",
                            "female"
                        ],
                        "description": "Identifier of the customer's gender. Possible values: male or female"
                    },
                    "qq_account_number": {
                        "type": "string",
                        "description": "Customer login in QQ social network"
                    },
                    "ssn": {
                        "type": "integer",
                        "maxLength": 4,
                        "description": "The last 4 digits of the customer's US social security number"
                    },
                    "device_fingerprint": {
                        "type": "string",
                        "description": "Identifier generated based on a device's characteristics such as browser type, screen resolution, operating system, fonts, and others"
                    },
                    "identify": {
                        "type": "object",
                        "description": "Object that contains customer identification document details",
                        "properties": {
                            "doc_number": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Identifier of the document serving as a proof of identity for the customer. Example: `65432334567`"
                            },
                            "doc_type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Type of identification document"
                            },
                            "doc_issue_date": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Date when the identification document was issued. Used for identity verification. Example: `20.12.2012`"
                            },
                            "doc_issue_by": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Name of the authority that issued the identification document. Can be used for identity verification. Example: `12346`"
                            },
                            "doc_issue_country": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Name of the country where the identification document was issued. Can be used for identity verification"
                            }
                        }
                    },
                    "billing": {
                        "type": "object",
                        "description": "Object contains customer billing address details",
                        "properties": {
                            "country": {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                            },
                            "region": {
                                "type": "string",
                                "description": "Region or state of the customer's billing address"
                            },
                            "region_code": {
                                "type": "string",
                                "pattern": "^[0-9A-Z]{1,3}$",
                                "description": "The region or state code of the customer's billing address in ISO 3166-2 format"
                            },
                            "city": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "Name of the place of residence (e.g., town, city, or other settlement type) in the customer's billing address. Example: `London`"
                            },
                            "address": {
                                "type": "string",
                                "maxLength": 512,
                                "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the customer's billing address. Example: `Via Dietro Duomo 36`"
                            },
                            "postal": {
                                "type": "string",
                                "maxLength": 16,
                                "description": "Postal code in the customer's billing address.Example: `BR1 1AA`"
                            },
                            "canadian_province": {
                                "type": "string",
                                "enum": [
                                    "ON",
                                    "BC",
                                    "AB",
                                    "MB",
                                    "SK",
                                    "QC",
                                    "NS",
                                    "NB",
                                    "NF",
                                    "PE",
                                    "NT",
                                    "NU",
                                    "YT"
                                ],
                                "description": "Abbreviation of Canadian province"
                            }
                        }
                    },
                    "citizenship": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Сode of the sender's country of citizenship in ISO 3166-1 alpha-2"
                    },
                    "accept_header": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Value of the HTTP Accept request header as received from the customer's browser"
                    },
                    "color_depth": {
                        "type": "integer",
                        "description": "Colour depth of the screen as supported by the customer's browser, bits per pixel"
                    },
                    "java_enabled": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's browser supports Java"
                    },
                    "js_enabled": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's browser supports JavaScript"
                    },
                    "timezone_offset": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Difference between the time in UTC (Coordinated Universal Time) and the local time of the browser, specified in minutes. Example: `-110`"
                    },
                    "timezone_name": {
                        "type": "string",
                        "description": "Name of the time zone the customer's browser is set to. Example: `Europe/London`"
                    },
                    "address_match": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the customer's billing address matches the address specified in the shipping object. Possible values: `true`—addresses match, `false`—addresses do not match"
                    },
                    "account": {
                        "$ref": "#/components/schemas/AccountInfoAtMerchant"
                    },
                    "shipping": {
                        "$ref": "#/components/schemas/ShippingInfo"
                    },
                    "mpi_result": {
                        "$ref": "#/components/schemas/MpiResult"
                    },
                    "accept_language_header": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Indicates the preferred language(s) of the customer's browser, derived from the Accept-Language HTTP header, for example `en-GB,en;q=0.8,fr;q=0.3`"
                    }
                },
                "description": "Object that contains customer details without ip_address. Use CustomerInfo instead of this"
            },
            "CustomerInfoBnplSale": {
                "description": "Object that contains customer details",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfoBase"
                    },
                    {
                        "type": "object",
                        "properties": {},
                        "required": [
                            "id",
                            "ip_address"
                        ]
                    }
                ]
            },
            "CustomerInfoCard": {
                "type": "object",
                "description": "Object that contains customer details",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "card_product_type": {
                                "description": "Card product type: business or individual",
                                "type": "string",
                                "enum": [
                                    "Business Card",
                                    "Individual Card"
                                ]
                            }
                        },
                        "required": [
                            "id"
                        ]
                    }
                ]
            },
            "CustomerInfoInvoice": {
                "required": [
                    "id"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer identifier unique within the project"
                    },
                    "country": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                    },
                    "city": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "Customer's address city name"
                    },
                    "state": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "State"
                    },
                    "phone": {
                        "type": "string",
                        "pattern": "^[0-9]{4,24}$",
                        "description": "Customer's phone number, can be 4 to 24 digits long"
                    },
                    "day_of_birth": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                    },
                    "birthplace": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer's place of birth"
                    },
                    "first_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer first name"
                    },
                    "middle_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer's patronymic"
                    },
                    "last_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Customer last name"
                    },
                    "email": {
                        "type": "string",
                        "maxLength": 255,
                        "format": "email",
                        "description": "Customer email"
                    },
                    "language": {
                        "type": "string",
                        "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`"
                    },
                    "address": {
                        "type": "string",
                        "description": "Customer’saddress"
                    },
                    "ssn": {
                        "type": "integer",
                        "maxLength": 4,
                        "description": "The last 4 digits of the social security number of US."
                    },
                    "billing": {
                        "type": "object",
                        "description": "Object contains billing address fields",
                        "properties": {
                            "country": {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                            },
                            "region": {
                                "type": "string",
                                "description": "The region or state of the customer's billing address"
                            },
                            "city": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "City of the billing customer address"
                            },
                            "address": {
                                "type": "string",
                                "maxLength": 512,
                                "description": "Street account address of the customer"
                            },
                            "postal": {
                                "type": "string",
                                "maxLength": 16,
                                "description": "Postal code of the billing address of the customer"
                            }
                        }
                    },
                    "accept_language_header": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Indicates the preferred language(s) of the customer's browser, derived from the Accept-Language HTTP header, for example `en-GB,en;q=0.8,fr;q=0.3`"
                    },
                    "account_id": {
                        "type": "string",
                        "description": "Customer identifier in external payment system that is used for payment performing"
                    }
                },
                "description": "Object that contains information about the customer"
            },
            "CustomerInfoNameValidation": {
                "description": "Object that contains customer details for name validation",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "name_validation": {
                                "type": "boolean",
                                "description": "Parameter that indicates name validation is required for the request"
                            }
                        }
                    }
                ]
            },
            "CustomerInfoPayout": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Customer identifier unique within the project"
                            }
                        },
                        "required": [
                            "id"
                        ]
                    }
                ]
            },
            "CustomerInfoWalletRecurring": {
                "description": "Object that contains customer details for recurring payments performing by using e-wallets",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "required": [
                            "id"
                        ]
                    }
                ]
            },
            "CustomerInfoWithId": {
                "description": "Object that contains customer details with mandatory identifier",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "required": [
                            "id"
                        ]
                    }
                ]
            },
            "CryptoPayment": {
                "type": "object",
                "properties": {
                    "cryptocurrency_type": {
                        "type": "string",
                        "enum": [
                            "cbdc",
                            "stablecoins_fiat_backed",
                            "native_tokens",
                            "other"
                        ],
                        "description": "Indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies"
                    }
                }
            },
            "Descriptor": {
                "type": "object",
                "properties": {
                    "descriptor": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "also known as billing descriptor, which is the text identifying the merchant and providing additional information about the payment (for example, the customer identifier, phone number, location information, etc.). In case of card payments, the merchant descriptor is sent to the issuing bank and can be shown on the customer’s bank statement. It can also be utilised otherwise as per specifics of various payment methods."
                    }
                }
            },
            "ErrorItem": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "integer",
                        "description": "Error code intended to represent the result of the operation processing. Example: `3287`"
                    },
                    "message": {
                        "type": "string",
                        "description": "Message intended to provide additional details clarifying the cause of the error. Example: `The payment currency is required`"
                    },
                    "field": {
                        "type": "string",
                        "description": "Name of the parameter that was erroneously specified (if such parameter is identified)"
                    },
                    "constraint": {
                        "type": "string",
                        "description": "Information about the error. This information can be used to clarify the failure. Example: `required`"
                    }
                },
                "description": "Object that contains single error information"
            },
            "ErrorItems": {
                "type": "object",
                "properties": {
                    "errors": {
                        "type": "array",
                        "description": "Array that contains information of one or more error messages",
                        "items": {
                            "$ref": "#/components/schemas/ErrorItem"
                        }
                    }
                },
                "description": "Object that contains information of one or more error messages"
            },
            "ErrorResponse": {
                "required": [
                    "status"
                ],
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Status of receiving of the request"
                    },
                    "code": {
                        "type": "string",
                        "description": "Error code"
                    },
                    "message": {
                        "type": "string",
                        "description": "Message that clarifies the cause of the error"
                    }
                },
                "description": "Object that contains information about request registration or processing error. Detailed information about the error see in the message parameter of the response"
            },
            "ETokenInfoLight": {
                "required": [
                    "token"
                ],
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string",
                        "description": "Token from payment system"
                    }
                },
                "description": "Information about token from payments system"
            },
            "GateSuccessResponse": {
                "required": [
                    "payment_id",
                    "project_id",
                    "request_id",
                    "status"
                ],
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Status indicating the result of the request acceptance"
                    },
                    "request_id": {
                        "type": "string",
                        "maxLength": 100,
                        "description": "Identifier of the request specified by the payment platform"
                    },
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`"
                    },
                    "payment_id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    }
                },
                "description": "Object that contains information about request acceptance or execution in the payment platform"
            },
            "GeneralInfo": {
                "type": "object",
                "description": "Object that contains general request details",
                "required": [
                    "project_id",
                    "payment_id",
                    "signature"
                ],
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "payment_id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "strict": true,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    },
                    "merchant_callback_url": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`"
                    }
                }
            },
            "GeneralInfoInvoice": {
                "required": [
                    "payment_id",
                    "project_id",
                    "signature"
                ],
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "payment_id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "strict": true,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "merchant_callback_url": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    }
                },
                "description": "Object that contains parameters for generating and submitting a payment link purchase to the payment platform"
            },
            "GeneralInfoClarification": {
                "type": "object",
                "description": "Object that contains general request details",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "payment_id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "strict": true,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    }
                },
                "required": [
                    "project_id",
                    "payment_id",
                    "signature"
                ]
            },
            "GeneralInfo3DS": {
                "type": "object",
                "description": "Object that contains general request details",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "payment_id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "strict": true,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    }
                },
                "required": [
                    "project_id",
                    "payment_id",
                    "signature"
                ]
            },
            "GiftCardInfo": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "maxLength": 3,
                        "description": "Currency code in ISO 4217 alpha-3 format"
                    },
                    "count": {
                        "type": "integer",
                        "maximum": 99,
                        "description": "Number of gift cards"
                    }
                },
                "description": "Object that contains information about gift card"
            },
            "GooglePayETokenInfoLight": {
                "required": [
                    "token"
                ],
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string",
                        "description": "Token from the Google Pay service"
                    },
                    "google_gateway_type": {
                        "type": "string",
                        "description": "GooglePay gateway type. Possible values: `gateway`—the payment data is processed by Ecommpay's acquiring system, `merchant`—the payment data is processed through a third-party payment system"
                    },
                    "google_tokenization_type": {
                        "type": "string",
                        "description": "GooglePay tokenisation type. Possible values: `DIRECT`—decryption of the Google Pay response on third-party servers, `PAYMENT_GATEWAY`—decryption of the Google Pay response on the Ecommpay side as the payment gateway"
                    },
                    "google_gateway_id": {
                        "type": "string",
                        "description": "Identifier of the gateway. This parameter is assigned by Google Pay"
                    },
                    "google_merchant_id": {
                        "type": "string",
                        "description": "Identifier of the merchant. This parameter is assigned by Google Pay"
                    },
                    "google_gateway": {
                        "type": "string",
                        "description": "Payment gateway in Google Pay, for example `ecommpay` for Ecommpay"
                    },
                    "google_transaction_id": {
                        "type": "string",
                        "description": "Identifier of the Google Pay payment"
                    }
                },
                "description": "Information about token from payments system"
            },
            "Installment": {
                "type": "object",
                "properties": {
                    "ext_plan_id": {
                        "type": "string",
                        "description": "Installment plan ID assigned by VIS"
                    },
                    "count": {
                        "type": "integer",
                        "description": "Number of installment periods"
                    },
                    "frequency": {
                        "type": "string",
                        "enum": [
                            "A",
                            "B",
                            "C",
                            "M",
                            "Q",
                            "S",
                            "T",
                            "W",
                            "2"
                        ],
                        "description": "Payment frequency"
                    },
                    "terms_and_conditions": {
                        "type": "object",
                        "description": "Terms and conditions of the contract",
                        "properties": {
                            "language": {
                                "type": "string",
                                "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`"
                            },
                            "version": {
                                "type": "number",
                                "description": "Version"
                            }
                        }
                    }
                }
            },
            "MerchantAuthGeneralInfo": {
                "required": [
                    "payment_id",
                    "project_id",
                    "signature",
                    "type"
                ],
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "payment_id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "strict": true,
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "start",
                            "finish"
                        ],
                        "description": "Type of merchant auth request"
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    }
                },
                "description": "Object that contains required details of the merchant auth request (customer authentication by the payment system on merchant's request)"
            },
            "MerchantInfo": {
                "type": "object",
                "properties": {
                    "descriptor": {
                        "type": "string",
                        "pattern": "^[^!@&~№{}|<>\\[\\]Ёё]*$",
                        "maxLength": 255,
                        "description": "also known as billing descriptor, which is the text identifying the merchant and providing additional information about the payment (for example, the customer identifier, phone number, location information, etc.). In case of card payments, the merchant descriptor is sent to the issuing bank and is shown on the customer’s bank statement. It can also be utilised otherwise as per specifics of various payment methods."
                    },
                    "data": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Information about the payment provided by the merchant. Can include details about the purchased items or services (number, description, SKU, etc.) or any other relevant data. This information is not sent to the payment provider or other third parties and is used at the merchant’s discretion"
                    }
                },
                "description": "Object that contains additional information provided by the merchant"
            },
            "MotoInfo": {
                "type": "object",
                "description": "Object that contains payment details including MO/TO type",
                "properties": {
                    "moto_type": {
                        "type": "integer",
                        "default": 0,
                        "enum": [
                            0,
                            1,
                            2
                        ],
                        "description": "Type of a Mail Order/telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment"
                    }
                }
            },
            "MpiResult": {
                "type": "object",
                "properties": {
                    "acs_operation_id": {
                        "type": "string",
                        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
                        "description": "Operation identifier in ACS"
                    },
                    "authentication_flow": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "The indicator of the flow that was used for the customer 3-D Secure 2 authentication within the previous operation"
                    },
                    "authentication_timestamp": {
                        "type": "string",
                        "pattern": "^\\d{12}$",
                        "description": "Date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result. Format: A numeric string containing exactly 12 digits with no spaces, letters, or special characters"
                    }
                },
                "description": "An object that contains information about previous mpi result"
            },
            "OperationInfo": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Unique identifier of the operation in the payment platform"
                    },
                    "type": {
                        "type": "string",
                        "description": "Operation type"
                    },
                    "status": {
                        "type": "string",
                        "description": "Operation status"
                    },
                    "date": {
                        "type": "string",
                        "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format"
                    },
                    "created_date": {
                        "type": "string",
                        "description": "Date and time when the operation was created in the payment platform in the format according to the ISO 8601 standart"
                    },
                    "sum_initial": {
                        "$ref": "#/components/schemas/Sum"
                    },
                    "sum_converted": {
                        "$ref": "#/components/schemas/Sum"
                    },
                    "request_id": {
                        "type": "string",
                        "description": "Identifier of the request specified by the payment platform"
                    },
                    "provider": {
                        "$ref": "#/components/schemas/ProviderResultInfo"
                    },
                    "code": {
                        "type": "string",
                        "description": "Operation processing result code"
                    },
                    "message": {
                        "type": "string",
                        "description": "Operation processing result message"
                    },
                    "eci": {
                        "type": "string",
                        "description": "Electronic Commerce Indicator, used for communicating whether the authentication was initiated and what was its outcome as well as whether the issuer or the merchant is responsible for approving payment processing and will take potential financial responsibility if a chargeback occurs. For more information, see [Electronic Commerce Indicators](https://developers.ecommpay.com/en/en_ECI_codes.html)"
                    },
                    "operation_fee": {
                        "type": "object",
                        "properties": {
                            "amount": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 10000000000000,
                                "description": "Operation fee amount in minor currency units. Example: `31`"
                            },
                            "currency": {
                                "type": "string",
                                "pattern": "^[:_A-Z0-9]{3,27}$",
                                "description": "Currency code in the ISO-4217 alpha-3 format. Example: `USD`"
                            }
                        }
                    }
                },
                "description": "Object that contains operation details"
            },
            "PaymentBanksInfo": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in the ISO 4217 alpha-3 format"
                    },
                    "customer_amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000000000000,
                        "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description or comment for additional data analisys by using Dashboard"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "best_before": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Payment expiration date in the date-time format according to the ISO 8601 standart"
                    },
                    "challenge_indicator": {
                        "type": "string",
                        "pattern": "^0[1-9]$",
                        "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "challenge_window": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "The dimensions of a window in which the authentication page opens.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "reorder": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_purchase": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Parameter specifying whether the current purchase is pre-ordered.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format"
                    },
                    "gift_card": {
                        "$ref": "#/components/schemas/GiftCardInfo"
                    },
                    "local_conversion_currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Conversion currency code, provided in ISO 4217 alpha-3 format"
                    },
                    "details": {
                        "type": "object",
                        "description": "Object that contains customer identification document details",
                        "properties": {
                            "document_number": {
                                "type": "string",
                                "description": "Number of the identification document used for verification"
                            },
                            "document_date": {
                                "type": "string",
                                "description": " Date when the relevant contract or document was concluded"
                            }
                        }
                    },
                    "device_channel": {
                        "type": "string",
                        "pattern": "^0[1-3]$",
                        "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined"
                    }
                },
                "description": "Object that contains payment details"
            },
            "PaymentInfo": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in ISO-4217 alpha-3 format. Example: `USD`"
                    },
                    "customer_amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Description of the payment intended to provide additional context or comments"
                    },
                    "end_to_end_id": {
                        "type": "string",
                        "maxLength": 35,
                        "description": "Identifier provided by the SEPA payment initiator. This parameter is intended to be routed through the entire SEPA payment process"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "best_before": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Payment link expiry date and time, in the ISO 8601 format"
                    },
                    "challenge_indicator": {
                        "type": "string",
                        "pattern": "^0[1-9]$",
                        "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "challenge_window": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "Dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "reorder": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeated purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_purchase": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Parameter specifying whether the current purchase is pre-ordered.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format"
                    },
                    "gift_card": {
                        "$ref": "#/components/schemas/GiftCardInfo"
                    },
                    "local_conversion_currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment conversion currency code, provided in ISO 4217 alpha-3 format"
                    },
                    "details": {
                        "type": "object",
                        "description": "Object intended to contain the customer's identification document details",
                        "properties": {
                            "document_number": {
                                "type": "string",
                                "description": "Number of the identification document used for verification"
                            },
                            "document_date": {
                                "type": "string",
                                "description": "Date when the relevant contract or document was concluded"
                            }
                        }
                    },
                    "device_channel": {
                        "type": "string",
                        "pattern": "^0[1-3]$",
                        "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined"
                    },
                    "is_fast": {
                        "type": "boolean",
                        "description": "Indicator specifying whether the payment is processed using a fast payment method"
                    }
                },
                "description": "Object that contains payment details"
            },
            "PaymentInfoDirectDebit": {
                "required": [
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[:_A-Z0-9]{3,27}$",
                        "description": "Payment currency in the ISO 4217 alpha-3 format"
                    },
                    "customer_amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Textual comment or description of the payment, can be used for additional data analysis and reporting in Dashboard"
                    },
                    "end_to_end_id": {
                        "type": "string",
                        "maxLength": 35,
                        "description": "SEPA identifier (provided by initiating SEPA transaction end-customer), routed through the whole payment process."
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "best_before": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Payment expiration date in the date-time format according to the ISO 8601 standart"
                    },
                    "challenge_indicator": {
                        "type": "string",
                        "pattern": "^0[1-9]$",
                        "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "challenge_window": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "The dimensions of a window in which the authentication page opens.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "reorder": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_purchase": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Parameter specifying whether the current purchase is pre-ordered.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format"
                    },
                    "gift_card": {
                        "$ref": "#/components/schemas/GiftCardInfo"
                    },
                    "local_conversion_currency": {
                        "type": "string",
                        "pattern": "^[:_A-Z0-9]{3,27}$",
                        "description": "Payment conversion currency code, provided in ISO 4217 alpha-3 format"
                    },
                    "details": {
                        "type": "object",
                        "description": "Object intended to contain customer identification document details",
                        "properties": {
                            "document_number": {
                                "type": "string",
                                "description": "Number of the identification document that can be used for verification"
                            },
                            "document_date": {
                                "type": "string",
                                "description": "Date when the relevant contract or document was concluded"
                            }
                        }
                    },
                    "device_channel": {
                        "type": "string",
                        "pattern": "^0[1-3]$",
                        "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined"
                    },
                    "is_fast": {
                        "type": "boolean",
                        "description": "Indicator intended to show whether the payment is processed using a fast payment method"
                    }
                }
            },
            "PaymentInfoForCard": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/PaymentInfoWMoTo"
                    },
                    {
                        "$ref": "#/components/schemas/CryptoPayment"
                    },
                    {
                        "type": "object",
                        "description": "Object that contains payment details for card",
                        "properties": {
                            "debt_account": {
                                "type": "string",
                                "maxLength": 10,
                                "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`"
                            },
                            "allow_partial_approval": {
                                "type": "boolean",
                                "description": "Parameter that indicates whether the merchant accepts partial approval for this purchase"
                            }
                        }
                    }
                ]
            },
            "PaymentInfoInvoice": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/PaymentInfoInvoiceByToken"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "force_method": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Identifier of the payment method intended to be opened by default, without the option for the customer to select a different payment method. For complete list of payment methods codes, see [Payment method codes](https://developers.ecommpay.com/en/en_pm_codes.html)"
                            }
                        }
                    }
                ]
            },
            "PaymentInfoInvoiceByToken": {
                "required": [
                    "amount",
                    "best_before",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in ISO 4217 alpha-3 format"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "best_before": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Date and time of payment expiration. Keep in mind that the validity period of the payment link cannot exceed 30 days"
                    },
                    "moto_type": {
                        "type": "integer",
                        "default": 0,
                        "enum": [
                            0,
                            1,
                            2
                        ],
                        "description": "Type of a Mail Order/Telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment"
                    }
                },
                "description": "Object which contains payment information for invoice by token"
            },
            "PaymentInfoPayoutOnlineBanking": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in ISO 4217 alpha-3 format"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    }
                },
                "description": "Object which contains payment information"
            },
            "PaymentInfoRecurring": {
                "required": [
                    "amount",
                    "currency"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Payment amount in minor units of currency"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in the ISO 4217 alpha-3 format. Example: `USD`"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Payment description or comment for additional data analisys by using Dashboard"
                    },
                    "extra_param": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Parameter for passing additional settings for customise the payment processing flow"
                    },
                    "challenge_indicator": {
                        "type": "string",
                        "pattern": "^0[1-9]$",
                        "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "challenge_window": {
                        "type": "string",
                        "pattern": "^0[1-5]$",
                        "description": "The dimensions of a window in which the authentication page opens.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "reorder": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeated purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_purchase": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Parameter specifying whether the current purchase is pre-ordered.  For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`"
                    },
                    "preorder_date": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format"
                    },
                    "gift_card": {
                        "$ref": "#/components/schemas/GiftCardInfo"
                    },
                    "local_conversion_currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Payment currency code in the ISO 4217 alpha-3 format"
                    },
                    "details": {
                        "type": "object",
                        "description": "Object that contains customer identification document details",
                        "properties": {
                            "document_number": {
                                "type": "string",
                                "description": "Number of the identification document used for verification"
                            },
                            "document_date": {
                                "type": "string",
                                "description": "Date when the relevant contract or document was concluded"
                            }
                        }
                    },
                    "device_channel": {
                        "type": "string",
                        "pattern": "^0[1-3]$",
                        "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined"
                    }
                },
                "description": "Object that contains payment details"
            },
            "PaymentInfoWMoTo": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/PaymentInfo"
                    },
                    {
                        "type": "object",
                        "description": "Object that contains payment details including MO/TO type",
                        "properties": {
                            "moto_type": {
                                "type": "integer",
                                "default": 0,
                                "enum": [
                                    0,
                                    1,
                                    2
                                ],
                                "description": "Type of a Mail Order/telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment"
                            }
                        }
                    }
                ]
            },
            "PaymentResultInfo": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "payment id"
                    },
                    "payment_system_id": {
                        "type": "integer",
                        "description": "Identifier of the payment provider in the payment platform"
                    },
                    "method": {
                        "type": "string"
                    },
                    "endpoint_id": {
                        "type": "integer"
                    },
                    "result_code": {
                        "type": "string"
                    },
                    "result_message": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string",
                        "description": "Date of the payment processing"
                    }
                },
                "description": "information about external payment system used"
            },
            "PaymentStatusResponse": {
                "required": [
                    "operations",
                    "payment",
                    "project_id",
                    "signature"
                ],
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`"
                    },
                    "payment": {
                        "type": "object",
                        "description": "Object that contains payment details",
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "Unique identification of the payment in the payment platform"
                            },
                            "type": {
                                "type": "string",
                                "description": "Payment type"
                            },
                            "status": {
                                "type": "string",
                                "description": "Payment status",
                                "minLength": 1
                            },
                            "sum": {
                                "$ref": "#/components/schemas/Sum"
                            },
                            "date": {
                                "type": "string",
                                "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format"
                            },
                            "description": {
                                "type": "string",
                                "description": "Description of the payment passed in the initial request"
                            },
                            "method": {
                                "type": "string",
                                "description": "Payment method that used to perform the payment"
                            }
                        },
                        "required": [
                            "status"
                        ]
                    },
                    "operations": {
                        "type": "array",
                        "description": "List of operations performed within the payment",
                        "items": {
                            "$ref": "#/components/schemas/OperationInfo"
                        }
                    },
                    "customer": {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    "recurring": {
                        "type": "object",
                        "description": "Object that contains recurring registration details of the payment. Details is submitted if the initial request for payment is passed with `recurring_registration=1` and the payment is successfully processed",
                        "properties": {
                            "id": {
                                "type": "integer",
                                "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases"
                            },
                            "currency": {
                                "type": "string",
                                "description": "Payment currency code in ISO 4217 alpha-3 format"
                            },
                            "valid_thru": {
                                "type": "string",
                                "description": "Expiration date of the record about a series of funds debiting. Example: `2025-03-30 16:15:00`"
                            }
                        }
                    },
                    "account": {
                        "type": "object",
                        "description": "Object that contains customer's payment instrument (card, bank account, wallet, etc.) details",
                        "properties": {
                            "number": {
                                "type": "string",
                                "description": "Customer's account number. Example: `21312`",
                                "minLength": 1
                            },
                            "type": {
                                "type": "string",
                                "description": "Payment instrument type"
                            },
                            "card_holder": {
                                "type": "string",
                                "description": "Name of the cardholder as specified on the payment card"
                            },
                            "token": {
                                "type": "string",
                                "description": "Customer's card token identifier"
                            },
                            "token_created_at": {
                                "type": "string",
                                "description": "Date and time of the token generation, specified in the ISO 8601 format with the UTC offset. Example: `2024-07-21T03:31:24+0000"
                            }
                        },
                        "required": [
                            "number"
                        ]
                    },
                    "acs": {
                        "type": "object",
                        "description": "Object that contains 3-D Secure data in case the card requires 3-D Secure authentication",
                        "properties": {
                            "pa_req": {
                                "type": "string",
                                "description": "Payer Authentication Request message received during the 3‑D Secure authentication",
                                "minLength": 1
                            },
                            "md": {
                                "type": "string",
                                "description": "Merchant data received from a global card network during the 3‑D Secure authentication",
                                "minLength": 1
                            },
                            "acs_url": {
                                "type": "string",
                                "description": "URL of the page to which the customer is redirected for the 3‑D Secure authentication (Access Control Server page)",
                                "minLength": 1
                            }
                        },
                        "required": [
                            "pa_req",
                            "md",
                            "acs_url"
                        ]
                    },
                    "errors": {
                        "type": "array",
                        "description": "Array of error messages",
                        "items": {
                            "$ref": "#/components/schemas/ErrorItem"
                        }
                    },
                    "signature": {
                        "type": "string",
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)."
                    }
                },
                "description": "Object that contains the payment details passed to the request for payment status clarifying"
            },
            "ProviderResultInfo": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Payment provider identifier in the payment platform. Example: `123`"
                    },
                    "payment_id": {
                        "type": "string",
                        "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`"
                    },
                    "auth_code": {
                        "type": "string",
                        "description": "Authorisation code received from a provider or a payment system. Example: `591748`"
                    },
                    "endpoint_id": {
                        "type": "integer",
                        "description": "Identifier of the payment gateway provided by the payment provider or system in CRC32 format. Example: `2`"
                    },
                    "result_code": {
                        "type": "string",
                        "description": "Result code provided by the payment provider or the payment system intended to indicate the result of the operation. Example: `00`"
                    },
                    "result_message": {
                        "type": "string",
                        "description": "Message with the result of operation. The parameter is provided by the payment provider or the payment system and offers additional details regarding the operation status and any related information. Example: `Success`"
                    },
                    "date": {
                        "type": "string",
                        "description": "Date and time when processing of the payment was completed on a provider or a payment system side. Example: `2022-02-22T19:52:14+0000`"
                    }
                },
                "description": "Object containing information from the payment provider regarding the result of the operation"
            },
            "ReceiptData": {
                "type": "object",
                "properties": {
                    "positions": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ReceiptPositionData"
                        },
                        "minItems": 1,
                        "maxItems": 300
                    },
                    "total_tax_amount": {
                        "type": "integer",
                        "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800``"
                    },
                    "common_tax": {
                        "type": "number",
                        "multipleOf": 0.01,
                        "description": "Applicable tax rate, specified if it is the same for all line items in the order. Example: `18`"
                    }
                },
                "description": "Object that contains the list of line items to be sent to the customer in the receipt once the payment is processed"
            },
            "ReceiptPositionData": {
                "required": [
                    "amount"
                ],
                "type": "object",
                "properties": {
                    "quantity": {
                        "type": "number",
                        "multipleOf": 0.000001,
                        "description": "Quantity of the goods and services. Example: `3`"
                    },
                    "amount": {
                        "type": "integer",
                        "description": "Total cost for a particular line item. Calculated by multiplying the quantity of that item by its unit price. Specified in minor units of currency. Example: `10000`"
                    },
                    "tax": {
                        "type": "number",
                        "multipleOf": 0.01,
                        "description": "Tax percentage applicable to the product or service. Example: `18`"
                    },
                    "tax_amount": {
                        "type": "integer",
                        "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800`"
                    },
                    "description": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Description of a specific product or service being purchased. Example: `Photo frame`"
                    }
                },
                "description": "Object that contains information about each line item in the purchase"
            },
            "RecipientForCard": {
                "anyOf": [
                    {
                        "required": [
                            "wallet_owner",
                            "wallet_id"
                        ],
                        "type": "object",
                        "description": "Object that contains the data of the payment recipient",
                        "properties": {
                            "wallet_owner": {
                                "type": "string",
                                "maxLength": 255,
                                "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                                "description": "First and last name of the recipient who owns the digital wallet to which the funds will be credited. Example: `Fran Petrarca`"
                            },
                            "wallet_id": {
                                "type": "string",
                                "maxLength": 64,
                                "pattern": "^[^!@&~№{}|<>\\[\\]]*$",
                                "description": "Identifier of the digital wallet. Specified as is, without masked characters, spaces, or other separators. Example:`WID20071304`"
                            },
                            "card_holder": {
                                "type": "string",
                                "maxLength": 255,
                                "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                                "description": "Name of the recipient (as specified on the card)"
                            },
                            "country": {
                                "maxLength": 2,
                                "pattern": "^[A-Z]{2}$",
                                "type": "string",
                                "description": "Recipient's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                            },
                            "address": {
                                "maxLength": 99,
                                "type": "string",
                                "description": "Recipient address"
                            },
                            "city": {
                                "maxLength": 25,
                                "type": "string",
                                "description": "Name of recipient's address city"
                            },
                            "state_code": {
                                "maxLength": 3,
                                "pattern": "^[A-Z]+$",
                                "type": "string",
                                "description": "State code of recipient"
                            },
                            "day_of_birth": {
                                "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                "type": "string",
                                "description": "Recipient's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                            }
                        }
                    },
                    {
                        "required": [
                            "card_holder",
                            "pan"
                        ],
                        "type": "object",
                        "description": "Object that contains the data of the transfer recipient",
                        "properties": {
                            "card_holder": {
                                "type": "string",
                                "maxLength": 255,
                                "pattern": "^[a-zA-Z0-9\\s\\-.']+$",
                                "description": "Name of the cardholder as specified on the payment card"
                            },
                            "pan": {
                                "type": "string",
                                "pattern": "^[0-9]{15,19}$",
                                "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`"
                            },
                            "country": {
                                "maxLength": 2,
                                "pattern": "^[A-Z]{2}$",
                                "type": "string",
                                "description": "Recipient's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                            },
                            "address": {
                                "maxLength": 99,
                                "type": "string",
                                "description": "Recipient address"
                            },
                            "city": {
                                "maxLength": 25,
                                "type": "string",
                                "description": "Namr of recipient's address city"
                            },
                            "state_code": {
                                "maxLength": 3,
                                "pattern": "^[A-Z]+$",
                                "type": "string",
                                "description": "State code of recipient"
                            },
                            "day_of_birth": {
                                "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                "type": "string",
                                "description": "Recipient's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                            }
                        }
                    }
                ]
            },
            "RecurringIdInfo": {
                "required": [
                    "id"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Unique identifier of the recurring payment in the payment platform"
                    }
                },
                "description": "Object that contains Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier"
            },
            "RecurringInfo": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "pattern": "^[RCU]$",
                        "description": "Payment type"
                    },
                    "expiry_year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "Year of expiration for credential-on-file (COF) payment. Can be used to define the last year when COF payment are allowed. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)"
                    },
                    "expiry_month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "Month of expiration for credential-on-file (COF) payment. Can be used together with `expiry_year` to set the final period of recurring payment validity. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)"
                    },
                    "expiry_day": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 31,
                        "description": "Day of expiration for credential-on-file (COF) payment. Can be used together with `expiry_month` and `expiry_year` to specify the exact expiration date. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)"
                    },
                    "interval": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100,
                        "description": "Interval of performing regular purchases. This parameter should be assigned a numeric value from `1` to `100` (for example, each three weeks) and is necessarily used in conjunction with the **period** parameter. May be used to configure payment recurrence frequency"
                    },
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Amount of payment in minor currency units"
                    },
                    "period": {
                        "type": "string",
                        "pattern": "^[DWMQY]$",
                        "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year"
                    },
                    "time": {
                        "type": "string",
                        "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$",
                        "description": "Time of performing subsequent debits (for a regular purchase) in the hh:mm:ss format. The parameter may be used if the **period** parameter is specified in the request"
                    },
                    "register": {
                        "type": "boolean",
                        "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment"
                    },
                    "scheduled_payment_id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Identifier assigned to the payment (as **payment_id**) within which scheduled debits are performed; it must differ from the identifier of the payment made to register a  credential-on-file purchase and must be unique within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return Example: `A2323`"
                    },
                    "start_date": {
                        "type": "string",
                        "maxLength": 19,
                        "pattern": "^([0-3]\\d-){2}[1-2]\\d{3}$",
                        "description": "First automatic payment date and time in DD-MM-YYYY format. Obligatory when `scheduled_payment_id` is set. Applicable only when **recurring.type = R** and **recurring.period** is set. Is used to authorize and perform the next recurring payment. **start_date** can't be less than the response date of the initial *sale/auth* request within which the recurring was registered"
                    }
                },
                "description": "Object that contains recurring payment details and conditions"
            },
            "RecurringInfoSuccess": {
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`"
                    },
                    "recurring": {
                        "type": "object",
                        "description": "Object that contains information about the credential-on-file (COF) purchase. For more information, see [Credential-on-file (COF) purchases](https://developers.ecommpay.com/en/en_Gate__payments_on_saved_data.html)",
                        "properties": {
                            "id": {
                                "type": "integer",
                                "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases"
                            },
                            "type": {
                                "type": "string",
                                "description": "Indicator of the credential-on-file purchase type. Example: `R`"
                            },
                            "period": {
                                "type": "string",
                                "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year"
                            },
                            "period_interval": {
                                "type": "string",
                                "description": "Multiplicator to increase debiting period, for example to run debiting every third week, `period` should be set to `W` and `interval` should be set to `3`. Possible values: from `1` to `100`. Example: `3`"
                            },
                            "start_date": {
                                "type": "string",
                                "description": "Date to perform the first debit in the yyyy-mm-dd format."
                            },
                            "start_time": {
                                "type": "string",
                                "description": "Time of subsequent debiting in the HH:mm format"
                            },
                            "amount": {
                                "type": "string",
                                "description": "Debit amount in minor units of currency"
                            },
                            "currency": {
                                "type": "string",
                                "description": "Currency code in ISO-4217 alpha-3 format"
                            },
                            "payment_method": {
                                "type": "string",
                                "description": "Code of the payment method that was used to make the payment to register a COF purchase (according to [the reference table](https://developers.ecommpay.com/en/en_pm_codes.html), with relevant codes listed in the Gate, Dashboard column)"
                            },
                            "last_payment_at": {
                                "type": "string",
                                "description": "The date when the last debit was made. Example: `2025-03-30 16:15:00`"
                            },
                            "valid_thru": {
                                "type": "string",
                                "description": "Expiration date of the record about a series of funds debiting"
                            },
                            "status": {
                                "type": "string",
                                "description": "Indicator of the current state of the debiting series record created after a successful COF purchase registration. Example: `active`"
                            },
                            "description": {
                                "type": "string",
                                "description": "Description of the credential-on-file purchase",
                                "maxLength": 255
                            },
                            "schedule_date": {
                                "type": "object",
                                "properties": {
                                    "next": {
                                        "type": "string",
                                        "description": "Next scheduled payment date in the YYYY-MM-DD hh-mm-ss format"
                                    },
                                    "last": {
                                        "type": "string",
                                        "description": "Last scheduled payment date in the YYYY-MM-DD hh-mm-ss format"
                                    }
                                }
                            }
                        }
                    },
                    "retry_info": {
                        "type": "object",
                        "description": "Object that contains information about the credential-on-file purchase retry attempts",
                        "properties": {
                            "trigger_operation_id": {
                                "type": "integer",
                                "description": "Identifier of the debit operation that is being retried. Example: `092384`"
                            },
                            "next_retry_exists": {
                                "type": "boolean",
                                "description": "Indicator that shows whether the next scheduled attempt is available. Possible values: `true`—specified when the debiting resulted in decline and there is an available retry attempt (the number of attempts and the time allocated for making them are not used up); `false`—in all other cases"
                            },
                            "next_retry_date": {
                                "type": "string",
                                "description": "Scheduled date and time of the next retry attempt. Example: `2023-05-24T16:58:02+0000`"
                            }
                        }
                    }
                },
                "description": "Object that contains general information about the credential-on-file purchase"
            },
            "RecurringRequiredInfo": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/RecurringInfo"
                    },
                    {
                        "required": [
                            "type"
                        ]
                    }
                ]
            },
            "RecurringUpdateInfo": {
                "required": [
                    "id"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases"
                    },
                    "expiry_year": {
                        "type": "integer",
                        "minimum": 2020,
                        "maximum": 9999,
                        "description": "Year of expiration for credential-on-file (COF) payment. Can be used to define the last year when COF payment are allowed"
                    },
                    "expiry_month": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12,
                        "description": "Month of expiration for credential-on-file (COF) payment. Can be used together with expiry_year to set the final period of recurring payment validity"
                    },
                    "expiry_day": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 31,
                        "description": "Day of expiration for credential-on-file (COF) payment. Can be used together with expiry_month and expiry_year to specify the exact expiration date"
                    },
                    "interval": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100,
                        "description": "Interval of performing regular purchases. This parameter should be assigned a numeric value from `1` to `100` (for example, each three weeks) and is necessarily used in conjunction with the **period** parameter. May be used to configure payment recurrence frequency"
                    },
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Amount of payment in minor currency units"
                    },
                    "period": {
                        "type": "string",
                        "pattern": "^[DWMQY]$",
                        "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year"
                    },
                    "time": {
                        "type": "string",
                        "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$",
                        "description": "Time of performing subsequent debits (for a regular purchase) in hh:mm:ss format. The parameter may be used if the **period** parameter is specified in the request"
                    },
                    "scheduled_payment_id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Identifier assigned to the payment (as **payment_id**) within which scheduled debits are performed; it must differ from the identifier of the payment made to register a  credential-on-file purchase and must be unique within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return Example: `A2323`"
                    },
                    "start_date": {
                        "type": "string",
                        "maxLength": 19,
                        "pattern": "^([0-3]\\d-){2}[1-2]\\d{3}$",
                        "description": "First automatic payment date and time in format **DD-MM-YYYY**. Obligatory when scheduled_payment_id is set. Applicable only when **recurring.type = R** and **recurring.period** is set. Is used to authorize and perform the next recurring payment. **start_date** can't be less than the response date of the initial *sale/auth* request within which the recurring was registered"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description for recurring",
                        "maxLength": 255
                    }
                },
                "description": "Object that contains updating recurring payment details"
            },
            "RefundPaymentInfo": {
                "required": [
                    "description"
                ],
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Refund amount in minor currency units"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Currency code in ISO-4217 alpha-3 format"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Refund description or comment"
                    },
                    "merchant_refund_id": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Identifier of the refund for representing the refund operation within the merchant’s service"
                    }
                },
                "description": "Object that contains refund processing details"
            },
            "ReturnUrl": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "string",
                        "description": "URL for redirecting the customer to the merchant's web service after the payment is completed"
                    },
                    "decline": {
                        "type": "string",
                        "description": "URL for redirecting the customer to the merchant's web service after the payment is declined"
                    },
                    "return": {
                        "type": "string",
                        "description": "URL for redirecting the customer to the merchant's web service when the customer decides not to complete the payment"
                    }
                },
                "description": "Object that contains the URLs to which customer is redirected while or after payment performing"
            },
            "SavedAccount": {
                "required": [
                    "id",
                    "number"
                ],
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Identifier of the payment instrument in the payment platform"
                    },
                    "number": {
                        "type": "string",
                        "description": "Masked number or another identifier of the customer's payment instrument (for example, a payment card, an account, or a digital wallet). Example: `424242***4243`"
                    },
                    "type": {
                        "type": "string",
                        "description": "Type of the saved payment instrument. Example: `card`"
                    },
                    "additional": {
                        "type": "object",
                        "description": "Object intended to contain supplementary details related to the payment instrument and customer",
                        "properties": {
                            "country": {
                                "type": "string",
                                "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                            },
                            "phone": {
                                "type": "string",
                                "description": "Customer's phone number, can be 4 to 24 digits long"
                            },
                            "email": {
                                "type": "string",
                                "description": "Customer's email address"
                            },
                            "card": {
                                "type": "object",
                                "description": "Card information",
                                "properties": {
                                    "expiry": {
                                        "type": "string",
                                        "description": "Expiration date of the card intended to indicate the final valid month and year in the MM/YY format. Example: `02/24`"
                                    },
                                    "holder": {
                                        "type": "string",
                                        "description": "Name of the cardholder on the payment card"
                                    },
                                    "type": {
                                        "type": "string",
                                        "description": "Payment card brand that was used in the processing of the payment, for example, Mastercard, Visa, and others"
                                    },
                                    "country": {
                                        "type": "string",
                                        "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`",
                                        "pattern": "^[A-Z]{2}$"
                                    },
                                    "product_name": {
                                        "type": "string",
                                        "description": "Name of the card product. Example: `PREPAID`"
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`"
                                    }
                                }
                            },
                            "recurring_enable": {
                                "type": "boolean",
                                "description": "Indicator showing whether credential-on-file purchase is created and active"
                            }
                        }
                    },
                    "last_deposit_date": {
                        "type": "string",
                        "description": "Date indicating the most recent deposit operation using this payment instrument"
                    },
                    "last_payout_date": {
                        "type": "string",
                        "description": "Date indicating the most recent payout operation using this payment instrument"
                    },
                    "last_tokenize_date": {
                        "type": "string",
                        "description": "Date indicating when this payment instrument was most recently tokenized"
                    },
                    "token": {
                        "type": "string",
                        "description": "Payment card token"
                    },
                    "operation_type": {
                        "type": "array",
                        "description": "Indicator that specifies the type of the operation during which the payment instrument was saved. Example: `sale`"
                    }
                },
                "description": "Object that contains the customer's saved payment instrument details"
            },
            "SenderInfo": {
                "type": "object",
                "properties": {
                    "first_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Sender's first name. Example: `Jane`"
                    },
                    "middle_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Sender's middle, second, or patronymic name. Example: `Mary`"
                    },
                    "last_name": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Sender's last  name. Example: `Smith`"
                    },
                    "day_of_birth": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Sender's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`"
                    },
                    "birthplace": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Name of the sender's birthplace (e.g., town, city, or other settlement type). Example: `London`"
                    },
                    "phone": {
                        "type": "string",
                        "pattern": "^[0-9]{4,24}$",
                        "description": "Sender's phone number, can be 4 to 24 digits long"
                    },
                    "residence": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Code of the country in the sender's billing address, specified in ISO 3166-1 alpha-2"
                    },
                    "citizenship": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Сode of the sender's country of citizenship in ISO 3166-1 alpha-2"
                    },
                    "person_type": {
                        "type": "string",
                        "description": "Type of the customer as a legal person, for example, a company or an individual, used for compliance"
                    },
                    "account_number": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Account number of the sender. Can be used for payment processing and compliance check"
                    },
                    "payment_purpose": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Declared purpose of the payment provided for anti-money laundering (AML) compliance checks."
                    },
                    "source_of_income": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Declared source of income of the sender used for anti-money laundering (AML) compliance"
                    },
                    "beneficiary_relationship": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Relationship between the sender and the recipient such as `employee` or `buyer`"
                    },
                    "identify": {
                        "type": "object",
                        "description": "Object that contains sender's identification details",
                        "properties": {
                            "doc_number": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Identity document number"
                            },
                            "doc_type": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Type of identity document"
                            },
                            "doc_issue_date": {
                                "type": "string",
                                "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                                "description": "Date of issue of identity document"
                            },
                            "doc_issue_by": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Who issued the identity document"
                            }
                        }
                    },
                    "billing": {
                        "type": "object",
                        "description": "Object contains billing address fields",
                        "properties": {
                            "country": {
                                "type": "string",
                                "pattern": "^[A-Z]{2}$",
                                "description": "Country code of the sender's billing address in ISO 3166-1 alpha-2 format"
                            },
                            "city": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "City of the billing sender address"
                            },
                            "state": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "State of the sender address"
                            },
                            "address": {
                                "type": "string",
                                "maxLength": 512,
                                "description": "Street account address of the sender"
                            },
                            "postal": {
                                "type": "string",
                                "maxLength": 16,
                                "description": "Postal code of the billing address of the sender"
                            }
                        }
                    },
                    "pan": {
                        "type": "string",
                        "maxLength": 32,
                        "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`"
                    },
                    "wallet_id": {
                        "type": "string",
                        "maxLength": 64,
                        "pattern": "^[^!@&~№{}|<>\\[\\]]*$",
                        "description": "Identifier of the digital wallet. Specified as is, without masked characters, spaces, or other separators. Example:`WID20071304`"
                    },
                    "address": {
                        "maxLength": 255,
                        "type": "string",
                        "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the payment sender. Example: `Via Certado 18`"
                    },
                    "zip": {
                        "maxLength": 255,
                        "type": "string",
                        "description": "Sender's postal code. Example:`50142`"
                    },
                    "city": {
                        "maxLength": 256,
                        "type": "string",
                        "description": "Name of the place of residence (e.g., town, city, or other settlement type) in the address of the payment sender. Example:`Florence`"
                    },
                    "country": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Sender's country code in the ISO 3166-1 alpha-2 format. Example: `GB`"
                    },
                    "state": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "Sender's state"
                    }
                },
                "description": "Object that contains information about the sender"
            },
            "SenderInfoPayout": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/SenderInfo"
                    },
                    {
                        "$ref": "#/components/schemas/Descriptor"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "funding_ips_id": {
                                "type": "string",
                                "maxLength": 50,
                                "description": "Transaction ID from from a preceding AFT"
                            }
                        }
                    }
                ]
            },
            "SenderInfoSale": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/SenderInfo"
                    },
                    {
                        "$ref": "#/components/schemas/Descriptor"
                    }
                ]
            },
            "SessionGeneralInfo": {
                "required": [
                    "display_name",
                    "domain_name",
                    "project_id",
                    "signature",
                    "validation_url"
                ],
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                        "minimum": 1,
                        "maximum": 4294967295
                    },
                    "signature": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                    },
                    "validation_url": {
                        "type": "string",
                        "description": "URL received during the integration through Apple Pay JS API. Example: `https://apple-pay-gateway.apple.com/paymentservices/startSession`"
                    },
                    "domain_name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Domain name of the merchant's web service. Example: `appay.eu.ngrok.io`"
                    },
                    "display_name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64,
                        "description": "Name of the merchant store to display. This parameter is provided in UTF-8 encoding. Example: `Cosmoshop`"
                    }
                },
                "description": "Object that contains parameters for initiating an Apple Pay session"
            },
            "SessionResponse": {
                "required": [
                    "merchantSession"
                ],
                "type": "object",
                "properties": {
                    "merchantSession": {
                        "type": "object",
                        "description": "Object that contains the merchant session information"
                    }
                },
                "description": "Object that contains Apple Pay session information"
            },
            "ShippingInfo": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "pattern": "^0[1-7]$",
                        "description": "Delivery type"
                    },
                    "delivery_time": {
                        "type": "string",
                        "pattern": "^0[1-4]$",
                        "description": "Delivery time. Possible values: `01`—digital same day delivery, `02`—same day delivery, `03`—next day delivery, `04`—delivery more than one day after the purchase was made"
                    },
                    "delivery_email": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Email to deliver purchased digital content to if the customer chooses email delivery",
                        "format": "email"
                    },
                    "address_usage": {
                        "type": "string",
                        "pattern": "^\\d{2}-\\d{2}-\\d{4}$",
                        "description": "Date  when the specified shipping address was used for the first time in DD-MM-YYYY format"
                    },
                    "name_indicator": {
                        "type": "string",
                        "pattern": "^0[1-2]$",
                        "description": "Indicator whether the customer's name matches the recipient's name. Possible values: `01`—names match, `02`—names do not match"
                    },
                    "city": {
                        "type": "string",
                        "maxLength": 50,
                        "description": "City from delivery address"
                    },
                    "country": {
                        "type": "string",
                        "pattern": "^[A-Z]{2}$",
                        "description": "Country code from delivery address in ISO 3166-1 alpha-2 format"
                    },
                    "address": {
                        "type": "string",
                        "maxLength": 150,
                        "description": "Street from delivery address"
                    },
                    "postal": {
                        "type": "string",
                        "maxLength": 16,
                        "description": "Index from delivery address"
                    },
                    "address_usage_indicator": {
                        "type": "string",
                        "pattern": "^0[1-4]$",
                        "description": "Indicator whether the shipping address used for this transaction was first used with the 3DS Requestor"
                    },
                    "region_code": {
                        "type": "string",
                        "pattern": "^[0-9A-Z]{1,3}$",
                        "description": "The region or state code of the customer billing address in ISO 3166-2 format. For example, `CA` in US or `ON` for Canada"
                    }
                },
                "description": "An object that contains information about delivery"
            },
            "SkrillCustomerInfo": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "maxLength": 255,
                                "description": "Customer identifier unique within the project"
                            },
                            "subject": {
                                "type": "string",
                                "maxLength": 250,
                                "description": "Subject line of the email notification sent to the customer"
                            },
                            "note": {
                                "type": "string",
                                "maxLength": 2000,
                                "description": "Textual comment included in the email notification sent to the customer. Can be used for providing additional information"
                            }
                        },
                        "required": [
                            "id"
                        ]
                    }
                ]
            },
            "SourceInfo": {
                "type": "integer",
                "properties": {
                    "id": {
                        "type": "integer",
                        "enum": [
                            7
                        ],
                        "description": "Interface type which is used for payment performing: 7 - Payment Page in iframe mode"
                    },
                    "user": {
                        "type": "string",
                        "maxLength": 255,
                        "format": "email",
                        "description": "User's email from the source"
                    }
                },
                "required": [
                    "id"
                ]
            },
            "StoredCardType": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6,
                "description": "Indicator of a credential-on-file (COF) purchase type. For more information, see [COF purchases](https://developers.ecommpay.com/en/en_Gate__payments_on_saved_data.html)"
            },
            "Sum": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10000000000000,
                        "description": "Amount in minor currency units"
                    },
                    "currency": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$",
                        "description": "Currency code in ISO 4217 alpha-3 format"
                    }
                },
                "description": "Object that contains the amount and currency"
            },
            "TokenData": {
                "required": [
                    "token_type"
                ],
                "type": "object",
                "properties": {
                    "token_type": {
                        "type": "string",
                        "enum": [
                            "network_token"
                        ],
                        "description": "Indicator specifying the type of the token"
                    },
                    "cryptogram": {
                        "type": "string",
                        "minLength": 28,
                        "maxLength": 28,
                        "description": "Network token verification code, received when the token is collected from the card network"
                    },
                    "eci": {
                        "type": "string",
                        "maxLength": 2,
                        "enum": [
                            "01",
                            "02",
                            "05",
                            "06",
                            "07"
                        ],
                        "description": "The ECI that corresponds to the network token, received when the token is collected from the card network"
                    },
                    "trid": {
                        "type": "string",
                        "minLength": 11,
                        "maxLength": 11,
                        "description": "Identifier of the merchant assigned when the merchant registers in the card network service for creating network tokens"
                    }
                }
            },
            "TokenizeCustomerInfo": {
                "description": "Object that contains the customer details",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/CustomerInfoBase"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "project_id": {
                                "type": "integer",
                                "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`",
                                "minimum": 1,
                                "maximum": 4294967295
                            },
                            "signature": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 255,
                                "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)"
                            }
                        },
                        "required": [
                            "project_id",
                            "signature"
                        ]
                    }
                ]
            },
            "TransactionStatusResponse": {
                "required": [
                    "general",
                    "status"
                ],
                "type": "object",
                "properties": {
                    "general": {
                        "$ref": "#/components/schemas/GeneralInfo"
                    },
                    "payment": {
                        "$ref": "#/components/schemas/PaymentResultInfo"
                    },
                    "customer": {
                        "$ref": "#/components/schemas/CustomerInfo"
                    },
                    "request_id": {
                        "type": "string"
                    },
                    "transaction": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "type": {
                                "type": "string"
                            },
                            "date": {
                                "type": "string",
                                "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format"
                            }
                        },
                        "description": "Object that contains information about processing of the payment in the payment platform"
                    },
                    "status": {
                        "type": "string"
                    },
                    "sum_request": {
                        "$ref": "#/components/schemas/Sum"
                    },
                    "sum_real": {
                        "$ref": "#/components/schemas/Sum"
                    },
                    "sum_refund": {
                        "$ref": "#/components/schemas/Sum"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of the payment"
                    },
                    "operations": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "type": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "date": {
                                    "type": "string"
                                },
                                "sum": {
                                    "$ref": "#/components/schemas/Sum"
                                }
                            }
                        }
                    },
                    "acs": {
                        "required": [
                            "acs_url",
                            "md",
                            "pa_req"
                        ],
                        "type": "object",
                        "properties": {
                            "pa_req": {
                                "type": "string",
                                "description": "Payer Authentication Request message received during the 3‑D Secure authentication"
                            },
                            "md": {
                                "type": "string",
                                "description": "Merchant data received from a global card network during the 3‑D Secure authentication"
                            },
                            "acs_url": {
                                "type": "string",
                                "description": "URL of the page to which the customer is redirected for the 3‑D Secure authentication (Access Control Server page)"
                            }
                        },
                        "description": "Object that contains data required to redirect to the 3-D Secure authentication page"
                    },
                    "return_url": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ErrorItem"
                        }
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "Card payments"
        },
        {
            "name": "Payment links"
        },
        {
            "name": "Payment Page payouts"
        },
        {
            "name": "Token operations"
        },
        {
            "name": "Additional information submission"
        },
        {
            "name": "Verification of Payee Service"
        },
        {
            "name": "ADVCash"
        },
        {
            "name": "Apple Pay"
        },
        {
            "name": "ATM"
        },
        {
            "name": "Bancontact"
        },
        {
            "name": "Banks"
        },
        {
            "name": "Bank Transfer"
        },
        {
            "name": "Blik"
        },
        {
            "name": "BNPL"
        },
        {
            "name": "Cash in Kazakhstan"
        },
        {
            "name": "China UnionPay"
        },
        {
            "name": "Direct Debit"
        },
        {
            "name": "EcoPayz"
        },
        {
            "name": "Flutterwave"
        },
        {
            "name": "Google Pay"
        },
        {
            "name": "Interac E-Transfer"
        },
        {
            "name": "M-Pesa"
        },
        {
            "name": "Mobile"
        },
        {
            "name": "Neosurf"
        },
        {
            "name": "Neteller"
        },
        {
            "name": "Online Banking"
        },
        {
            "name": "Pix"
        },
        {
            "name": "Skrill"
        },
        {
            "name": "Turkey QR"
        },
        {
            "name": "Wallet"
        },
        {
            "name": "Requests for customer details"
        },
        {
            "name": "Requests for information"
        },
        {
            "name": "Requests for recurring"
        },
        {
            "name": "Requests for refunding specific payments"
        }
    ]
}

---

# Dashboard {#en_dbl_about}

A section with information about working with Dashboard, an interface intended for use by merchant employees, and the Data API for retrieving operation data.

This section provides the information about working with the Dashboard interface.

## Overview and getting started {#section_b5y_grc_c5b .section}

The information about the Dashboard interface and how to start using it:

-   [Overview](en_dbl_overview.md)introduces the interface, its special characteristics, and how to access it.
-   [Core capabilities and role-based access model](en_dbl_roles_overview.md)covers core capabilities, supported access roles and their specific characteristics as well as distribution of access rights to different roles.
-   [Interaction with the interface](en_dbl_interfaces.md)describes essential interface elements: main menu, sections, and lists.
-   [Managing projects](en_dbl_projects.md)goes over individual settings of your projects you can configure in Dashboard and working with callback settings.

## Working with the interface {#section_wn2_vrc_c5b .section}

The information about a range of tasks that Dashboard allows you to accomplish and the necessary instructions:

-   [Monitoring and performing payments](en_dbl_payments.md)covers monitoring payments, performing various types of purchases, refunds, and payouts as well as managing regular COF purchases \(subscriptions\) via Dashboard.
-   [Financial accounting](en_dbl_balances.md)discusses balances and the special aspects of their use as well as monitoring balances via Dashboard.
-   [Risk management](en_dbl_risks.md)introduces the basics of risk management and goes over monitoring fraudulent operations and using whitelists and blacklists via Dashboard.

## Related interfaces {#section_q21_bsc_c5b .section}

The information about features and technical aspects of the Data API interface that allows you to get data about operations, chargebacks, and balances–[Using Data API](en_dbl_api_protocol.md).

-   **[Overview](en_dbl_overview.md)**  
An article with the introductory information about the Dashboard interface, its special aspects and access model.
-   **[Core capabilities and role-based access model](en_dbl_roles_overview.md)**  
An article about core capabilities of Dashboard, supported access roles, and distribution of access rights to different roles.
-   **[Interaction with the interface](en_dbl_interfaces.md)**  
An article about working with the essential interface elements of Dashboard: main menu, sections, and lists.
-   **[Managing projects](en_dbl_projects.md)**  
An article about the capabilities of configuring project settings in Dashboard, including callback settings and Apple Pay domain verification.
-   **[Monitoring and performing payments](en_dbl_payments.md)**  
An article about the capabilities of monitoring payments, performing various types of purchases, refunds, and payouts as well as managing regular COF purchases \(subscriptions\) via Dashboard.
-   **[Receiving financial statements via email](en_dbl_financial_statements.md)**  

-   **[Financial accounting](en_dbl_balances.md)**  
An article about balances for working with the platform and the special aspects of their use as well as monitoring balances and currency exchange rates and working with bank accounts via Dashboard.
-   **[Risk management](en_dbl_risks.md)**  
An article about risk management in ecommerce and the capabilities of monitoring fraudulent operations and configuring blacklists via Dashboard.
-   **[Working with chargeback callbacks](en_dbl_chargeback_callbacks.md)**  
An article about the capabilities of working with callbacks that communicate information about events occurring within the chargeback process.
-   **[Using Data API](en_dbl_api_protocol.md)**  
Articles about the capabilities and technical specifics of the Data API that allows retrieving information about operations, chargebacks, and balances.
-   **[Data API](data_api.md)**  
The Data API specification with the descriptions of data structures and schemas for generating requests to different endpoints.



---

# Overview {#en_dbl_overview}

An article with the introductory information about the Dashboard interface, its special aspects and access model.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Main use and special characteristics {#en_dbl_overview_main_use}

Dashboard is a web interface intended for use by merchants of Ecommpay. This interface is available at [dashboard.ecommpay.com](https://dashboard.ecommpay.com) and allows merchant employees to accomplish a range of tasks related to all projects of their company in the Ecommpay payment platform. They can:

-   Analyse and monitor payment processing and consolidated financial datawith an option to break it down by different characteristics and with the help of visualisation tools.
-   Perform various types of purchases, issue partial and full refunds as well as payouts to the customers of the merchant's web service with the use of individual and batch requests.
-   Customise the design of Payment Page\(when it is used for projects that involve integration with the Ecommpay payment platform\).
-   Monitor and prevent fraud cases as wellas monitor and accept chargebacks.
-   Create a range of reportswith consolidated information on payment processing and financial results.
-   View and set up available projects.

This list of capabilities continues to grow.

![](images/ecommpay/dbl/en_dbl_overview.svg)

From the start, Dashboard was designed with the consideration of leading development methodologies and technologies including elements of design thinking. As a result, the interface includes a number of solutions which have already been tested with the help of prospective and real-life users, and any clients of Ecommpay can contribute to the further development of the interface—if you are interested, let your account manager know.

If you have questions about using Dashboard, refer to this documentation or contact Ecommpay specialists.

## How to access {#en_dbl_overview_access}

Since Dashboard provides access to financial data and allows executing financial operations, the following protective measures are implemented to ensure secure handling of data:

-   Access control via user accounts with permissions distributed according to assigned access roles \([learn more](en_dbl_roles_overview.md)\).
-   Additional user authentication that requires the second "authentication factor"–with Google Authenticator app.
-   Confirmation of payouts with one-time verification codes sent to the phone numbers previously provided by Dashboard users\(to learn more about using this capability, contact your Ecommpay account manager\).

These measures comply with the requirements of PSD2 \(Revised Directive on Payment Services, Directive \(EU\) 2015/2366\) and ensure user convenience and security.

Certain permissions granted to use Dashboard do not require providing the second authentication factor. This applies to the following sections and the corresponding permissions:

-   In My profile it applies to editing user profileandmanaging API tokens.
-   In Payments it applies to viewing payment registry, viewing payment information, using configuration, issuing refunds, and capturing and releasing held funds as part of executing a two-step purchase.
-   In Reports it applies to managing reports.
-   In Projects it applies to viewing projects.
-   In Subscriptions it applies to viewing the registry of regular COF purchases \(subscriptions\), viewing detailed COF purchase information, updating its settings and cancelling it.
-   In Manual payments it applies to issuing refunds, capturing and releasing held funds.
-   In Remittances it applies to creating and editing remittance recipient accounts and viewing lists of the recipient accounts and the remittances.

Any permission not included in the list above implies that the user should provide the phone number and enable two-factor authentication.

**Note:** Only users with the `Merchant admin` role permissions have access to the rights distribution information and are able to add phone numbers to user account \(in the **My team** section\).

First time users with permissions that require the use of two-factor authentication should proceed as follows when they access Dashboard:

1.  If they need to add the phone number, they should contact the user with the `Merchant admin` role who will add the number to the required user account.
2.  They should specify their username and password when signing in.
3.  They should activate the two-factor authentication in the Google Authenticator app using the verification code sent by text \(SMS\).
4.  Verify their identity in Dashboard with the one-time code generated by the Google Authenticator app.

Users in roles that do not require two-factor authentication can activate it and add a phone number in the user account if they have the appropriate permission.

To provide a phone number and activate two-factor authentication,

1.  Open the user profile.

    Click the user name or the user account icon in the top right corner and select **My profile** in the dropdown menu.

2.  Add the phone number:
    1.  Switch to the editing mode by clicking **Edit** on the **User Profile** panel.
    2.  Enter and confirm the phone number.

        The phone number should be specified in international format \(`+{international country code}{phone number}`\) in the corresponding field. To confirm, enter the SMS verification code in the popup window.

    3.  Save changes by clicking **Save** on the upper-right side of the **User Profile** panel.
3.  Enable two-factor authentication.

    Turn on the **Two-factor Authentication** toggle switch located on the **Security** panel and follow the instructions provided in the interface.

4.  Make sure all changes have been saved.

    The two-factor authentication switch should be on, and the phone number should be shown in the user profile.




---

# Core capabilities and role-based access model {#en_dbl_roles_overview}

An article about core capabilities of Dashboard, supported access roles, and distribution of access rights to different roles.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_roles_overview_info}

Dashboard is a unified interface intended for use by employees of the merchant. It supports a full range of required features, and itimplements a role-based access model in order to distribute rights to access different features among various specialists\(with consideration of organization structure and other factors\).

This section describes core capabilities, supported access roles andtheir specific characteristics as well as granting access rights to different roles.

## Capabilities {#en_dbl_roles_overview_capabilities}

Capabilities of Dashboard can be divided into the following categories:

-   Monitoring and analysing payment processing—users are able to view, filter, search, and visualize data on both completed payments and payments in-progress.
-   Executing financial operations—users are able to performvarious types of purchases, issue payouts and refunds \(both full and partial\) as well as manage regular COF purchases \(subscriptions\).
-   Remittances—users are able to make single and bulk B2B payments to corporate accounts \([learn more](en_b2bremit_about.md)\).
-   Payment Page design customisation—users are able to view, create, modify, and delete different design styles of the payment form \([more](en_PP__design_customisation.md)\).
-   Financial accounting and reporting—users are able to prepare and view various reports with access to the balance sheets.
-   Riskand chargeback management—users are able to monitor detected fraud cases, which includes managing whitelists and blacklists, as well as to monitor chargebacks and accept specific chargebacks without going through an arbitration process.
-   Interface access administration—users \(with appropriate permissions\) are able to manage user accounts and distribution of access roles as well as to monitor user actions and to view settings of available projects as well as to configure some of these settings.

To access one or more of these capability categories, the following roles are used.

## Access roles {#en_dbl_roles_overview_roles}

|The following roles with the corresponding capabilities are used in Dashboard when access rights are distributed:|
| |**Designer**|**Support**|**Operations**|**Finance**|**Risks**|**Merchant admin**|
|-   Monitoring and analysing payment processing

|–|±|+|+|+|+|
|-   Executing financial operations

|–|±|+|–|–|+|
|-   Financial accounting and reporting

|–|–|–|+|–|+|
|-   Riskand chargeback management

|–|–|–|–|+|+|
|-   The Dashboard interface access administration

|–|–|–|–|–|+|
|-   Payment Page design customisation

|+|–|–|–|–|+|
|These roles can be applicable for employees with the following job titles:|
| |-   Product owner
-   UX/UI Designer
-   Marketing

|-   Support manager
-   Monitoring manager

|-   Finance manager
-   Product owner
-   Product/project manager
-   Payments specialist

|-   Finance manager
-   Treasury specialist
-   Accountant

|-   Fraud Prevention Manager
-   Risk Manager
-   Fraud Team

|-   Chief Operation Officer
-   Product owner
-   Chief Executive Officer

|

This selection of roles is permanent, which means that the merchant is not able to create other roles. However, for certain user accounts the permission set determined by the role can be modified; in addition, a single user account can take on several roles simultaneously. This widens the range of permissions available to the user by combining permissions initially only available in separate sets of the default selection. For instance, if a user account with the Operations role access requires rights to view the balance sheet, then you can grant this user account the access rights of the Finance role which permits viewing balance information in **Finance** section.

User accounts with the assigned Merchant Admin role are granted a full set of permissions to access all merchant's projects, and such user accounts can only be created by Ecommpay technical support specialists. User accounts with permissions granted by other roles \(including accessing projects\) can be created and configured by the merchant's employees with the assigned Merchant Admin role. It is important to keep in mind, however, that permissions granted to a user account apply to all projects which this user account is allowed to access. There is no selective applicability of permissions depending on the project that a user account has access to.

## Access rights {#en_dbl_roles_overview_rights}

Access rights to work with different sections of Dashboard are distributed among the roles as shown in the following table. In addition to these rights, you can request a number of permissions with the extended scope from the Ecommpay technical support—on condition that such permissions are used in the platform and are available for the use by the merchant.For example, to ensure that your employees have access to editing whitelists, you need to request a corresponding permission.

| |Designer|Support|Operations|Finance|Risks|Merchant admin|
|:-|--------|-------|----------|-------|-----|:-------------|
|**My team**|
|Viewing the list of user accounts|–|–|–|–|–|+|
|Managing user accounts|–|–|–|–|–|+|
|**Finance**|
|Viewing the balance information|–|–|–|+|–|+|
|Viewing the bank accounts information|–|–|–|+|–|+|
|Creating and editing records with the details of bank accounts|–|–|–|+|–|+|
|**Reports**|
|Viewing and managing reports|–|+|+|+|+|+|
|**Payments**|
|Viewing the payments list|–|+|+|+|+|+|
|Configuring the list's display mode|–|+|+|+|+|+|
|Viewing the payment's detailed information|–|+|+|+|+|+|
|Issuing refunds|–|–|+|–|–|+|
|Performing capture operations|–|–|+|–|–|+|
|Performing cancel operations|–|–|+|–|–|+|
|**B2B remittances**|
|Viewing the lists of remittances and remittance recipient accounts|–|+|+|+|–|+|
|Creating and editing remittance recipient accounts|–|–|+|–|–|+|
|Sending remittance recipient accounts for approval and deleting accounts|–|–|+|–|–|+|
|Creating remittance orders|–|–|+|–|–|+|
|**Payment links**|
|Viewing the list of payment link purchases|–|–|+|–|–|+|
|Creating payment links|–|–|+|–|–|+|
|Deactivating payment links|–|–|+|–|–|+|
|**Manual Payments**|
|Viewing the payouts and mass payouts lists|–|–|+|–|–|+|
|Configuring the display mode of the lists|–|–|+|–|–|+|
|Viewing the payment's detailed information|–|–|+|–|–|+|
|Issuing payouts|–|–|+|–|–|+|
|Issuing refunds|–|–|+|–|–|+|
|Performing capture operations|–|–|+|–|–|+|
|Performing cancel operations|–|–|+|–|–|+|
|Taking MO/TO payments|–|–|+|–|–|+|
|**Subscriptions**|
|Viewing the list of subscriptions|–|+|+|–|–|+|
|Viewing the subscription's detailed information|–|+|+|–|–|+|
|Managing subscriptions|–|–|+|–|–|+|
|**Risks**|
|Viewing the list of fraudulent operations|–|–|–|–|+|+|
|Viewing whitelists and blacklists|–| |–|–|+|+|
|Editing blacklists|–|–|–|–|+|+|
|**Chargebacks**|
|Viewing the list of chargebacks|–|–|–|–|+|+|
|Viewing the chargeback's detailed information|–|–|–|–|+|+|
|Accepting a chargeback|–|–|–|–|+|+|
|**My profile**|
|Editing user account's general information|+|+|+|+|+|+|
|Managing Data API tokens|–|+|+|+|+|+|
|Managing technical support bot|–|+|+|–|–|+|
|**Analytics**|
|Viewing Analytics section|–|–|+|+|+|+|
|Managing analytic boards|–|–|+|+|+|+|
|**Projects**|
|Viewing projects|+|+|+|+|+|+|
|Editing project settings|–|–|–|–|–|+|
|Managing Payment Page Designer|+|–|–|–|–|+|
|**Help**|
|Viewing information|+|+|+|+|+|+|



---

# Interaction with the interface {#en_dbl_interfaces}

An article about working with the essential interface elements of Dashboard: main menu, sections, and lists.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_interface_overview}

Dashboard interface is divided into topic-driven sections with each focused on the corresponding data segment and employing specific operation tools. These sections contain a number of standard items while most tasks are solved with the use of registers. To search for data and perform a range of operations, use the main menu located at the top of the page. To switch from one section to another, use the navigation panel on the left.

The following is a summary of using the main menu, sections, and lists.

## Main menu {#en_dbl_upper_panel}

### Overview {#section_s42_rkl_hlb .section}

The main menu located at the top of the Dashboard interface contains buttons that allow the user to customise the interface, access subsidiary sections, and log out.

![](images/ecommpay/dbl/en_dbl_main_menu.svg)

*The main menu with an expanded navigation panel: 1—navigation panel button; 2—clock; 3—help; 4—language switcher; 5—notifications and search panel buttons; 6—user information; 7—logout button.*

### Navigation panel {#section_txz_15m_hlb .section}

The navigation panel is located on the left side of the interface and contains buttons for switching between the sections that are available for the user account. The panel can be shown expanded with the sections' names and the corresponding icons or collapsed \(with the sections' icons and the tooltips with the corresponding names\). To expand or collapse the navigation panel, use the ![](images/universal/dbl/icon_menu.svg) button on the left of the main menu.

### Clock {#section_pzs_ztm_hlb .section}

The clock with an option to select the time zone is located in the centre of the main menu. Selecting the time zone affects the way the data is shown in the payments list, but it does not impact the way business days are determined and counted. Business days for reporting purposes are set in UTC + 00:00.

### Search panel {#section_r4t_f5m_hlb .section}

Search panel contains a set of fields allowing users to find necessary payments quickly and efficiently. To increase usability and optimise search speed, the panel shows only the most frequently requested parameters, and the search is carried out only if the attributes provided fully match. The search results can be found in the payments list of **Payments** section.

![](images/ecommpay/dbl/en_dbl_search_panel.svg "The main menu with a shown search panel")

If the fields are shown but are not enabled, it means they are still in development and optimisation.

## Sections {#en_dbl_sections}

Dashboard interface includes the following sections:

-   **My profile**—it contains the user information and the tools to configure the user account.
-   **Finance**—it contains the merchant's current balances broken down by projects.
-   **Reports**—it contains the tools to prepare reports according to specified parameters and to view and export the reports that have been drawn.
-   **Payments**—it contains the list of all payments, both completed and in-progress, as well as tools for configuring the way the data is displayed in the list. This section also allows users to view detailed payment informationand issue single refunds.
-   **Remittances**—it contains the list of remittance recipient accounts and tools for managing recipient accounts and creating single and mass remittance orders. This section also allows users to view lists of all B2B payments, both completed and in-progress, and the detailed information about each payment.
-   **Payment links**—it contains the list of all payment link purchases, both completed and in-progress, as well as tools for managing payment links to create, deactivate, and set up auto-sending of payment links to customers.
-   **Manual payments**—it contains the list of all payouts, completed and in-progress, as well as tools for configuring the way the data is displayed in the list. This section also allows users to view detailed payment information and issue single and mass payouts as well as mass refunds.
-   **Subscriptions**—it contains the list of registered regular COF purchases \(subscriptions\) as well as tools for configuring the way the data is displayed in the list. This section also allows users to view detailed subscription information, update subscription settings and cancel subscriptions.
-   **Risks**—it contains the list of fraudulent operations and the list of criteria of merchant whitelists and blacklists, as well as tools for configuring the way the data is displayed in the lists. This section also allows users to manage criteria of whitelists and blacklists.
-   **Chargebacks**—it contains the list of all chargebacks, both completed and in-progress, as well as tools for configuring the way the data is displayed in the list. This section also allows users to view detailed chargeback information and accept chargebacks withoutgoing through an arbitration process.
-   **My team**—it contains the list of all user accounts of the merchant's employees as well as the tools to manage the user accounts and to view user actions history.
-   **Analytics**—it contains a pre-configured set of analytic panels for online analysis of payment and operation processing for the merchant's projects \(accessible with the appropriate permissions of the user account\).
-   **Projects**—it contains the information about individual settings of the merchant's projects \(accessible with the appropriate permissions of the user account\) and the instruments to configure these settings.
-   **Help**—it contains the information that covers how to use Dashboard and its sections \(accessible with the appropriate permissions of the user account\).

## Lists {#en_dbl_registry}

Dashboard implements lists to display large volumes of records with payment data or user account information. One section can contain one or several lists. To switch between them, use tabs with the names of the corresponding lists.

![](images/ecommpay/dbl/en_dbl_risks_switch_between_registries.svg "Switching between lists")

Lists have a uniform design, and all of them allow you to configure the number and the order of columns, filter recorded data and perform a number of actions including switching to detailed payment information or deleting a user account.

Each section which contains a list includes the following types of filters:

-   *Predefined filters*—they are available via the buttons located at the top of the list, in the filter area.These filters allow users to select or deselect filtering with the use of a single parameter, for example, payment currency in one-click.
-   *Custom filters*—they are available in a separate panel which is opened with the button on the right located in the filter area.They allow users to filter recorded data according to a total of selected parameters. The settings of such filters can be flexibly configured and saved for future use.

Moreover, depending on the purpose of the list, they include additional tools for working with them. For instance, the payments list allows users to configure the number and the order of columns with the use of the custom filter manager which is opened with the button on the right located in the filter area.

|![](images/ecommpay/dbl/en_dbl_payments_list.svg)

*Payments list in **Payments** section: 1—a tab with the list of all payments; 2—predefined filters; 3—buttons to reset all filters, to show custom filters and to configure payments list display mode.*|
|![](images/ecommpay/dbl/en_dbl_payouts_list.svg)

*Payouts list in **Manual payments** section: 1—tabs with lists; 2—a button to issue payments; 3—predefined filters; 4—buttons to reset all filters, to show custom filters and to configure payments list display mode.*|
|![](images/ecommpay/dbl/en_dbl_user_list.svg)

 *User account list in **My team** section: 1—tabs with lists; 2—a button to create a new user account; 3—predefined filters; 4—buttons to reset all filters, to show custom filters and to configure users list display mode; 5—tools to edit a user account.*

|



---

# Managing projects {#en_dbl_projects}

An article about the capabilities of configuring project settings in Dashboard, including callback settings and Apple Pay domain verification.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_projects_overview}

Dashboard interface allows you to view and configure individual settings of your projects in the **Projects** section. This section can be accessed with a separate set of permissionsprovided by default to user accounts with the assigned `Merchant Admin` role. In addition, user accounts with access rights of other roles can be permitted to view the information in this section \([more](en_dbl_roles_overview.md)\).

![](images/ecommpay/dbl/en_dbl_projects.svg "Project information card")

In the **Projects** section you can find cards with information about individual projects. In each, you can switch between the following tabs:

-   **General**—to view general information about the project and work with the secret keyrequired for accepting MO/TO payments via Dashboard
-   **Payment methods**—to view supported payment methodswith the option to request enabling Apple Pay and PayPal
-   **Redirect URLs**—to set up URLs that redirect customers to the web service when Payment Page is used \([learn more](en_PP_redirect_modes.md)\)
-   **Callbacks**—to configure callback settings
-   **Payment Page Designer**—to customise the appearance of the payment form \([learn more](en_PP__design_customisation.md)\)

    **Note:** The **Payment Page Designer** tab is not displayed if Dashboard is opened on mobile devices.

-   **Apple Pay Domain Verification**—to register domains in the Apple Pay service and manage them
-   **Subscription retry settings**—to configure a debiting retry schedule \(which applies to all regular COF purchases within one project\)

Keep in mind that you cannot create or delete projects in Dashboard. To do so, contact your Ecommpay account manager.

## Working with callback settings {#en_dbl_projects_callbacks}

### Overview {#section_fbh_3vp_nsb .section}

In case of payment processing via the Ecommpay payment platform, callbacks are sent to the merchant's web service to communicate different kinds of information: for example, to notify where to redirect customers or to deliver results of performing an operation. The description of the callback structure and the information on how to work with callbacks can be found in [Handling callbacks](en_platform_callbacks.md).

Callbacks can be sent to the URLs that merchants provide at the time of integration and the URLs specified via Dashboard. Using the tools of the **Projects** section, you can configure an unlimited number of callbacks in each case determining the specific event that will trigger a certain callback and specifying the URL to which this callback will be sent. Along with that, in this section you can view the list of all callbacks with their specific settings regardless of whether they were configured at the time of integration or added via Dashboard. You can also manage previously configured settings of standard callbacks: they can be activated, deactivated, and deleted.

![](images/ecommpay/dbl/en_dbl_projects_callbacks.svg "Callback configuration tools")

### Callback settings structure and configuration specifics {#section_lqt_5vp_nsb .section}

For each callback, you configure a set of conditions that determine the event that triggers this callback and the URL it is sent to. You can specify the payment type, the event type \(**Result type** in Dashboard\), and the payment method. Each of these parameters can have only one value. You can select the following values:

-   Payment types `purchase, recurring, payout, account verification`, and `all` \(that includes all types listed here\).
-   Event types `success, decline, tokenize, refund, recurring, error`, and `all` \(that includes all types listed here\).
-   IDs of the payment methods supported for the project. The parameter field can also be left blank \(to include all supported payment methods\).

At the same time, when configuring callbacks via Dashboard, keep in mind that:

-   The list shows configured callbacks for all payment and event types specified above. However, settings of callbacks with custom formats can be configured and managed only by the Ecommpay support specialists.
-   Callbacks configured for `purchase` payments are triggered both by one-step purchases and two-step purchases, therefore, such callbacks are shown separately in the list—for payment types `purchase` \(one-step\) and `purchase_dms` \(two-step\). If necessary, redundant callbacks can be deleted.
-   Configuring callbacks for the `error` event type is supported only when `all` is selected in the payment type field.
-   If one set of conditions applies to several callbacks sent to different URLs, then identical callbacks will be sent to all of these URLs with no specific order of preference and no regard to the stage at which these URLs were provided \(at the time of integration or via Dashboard\).

    For example, in case of callbacks with IDs `96071` and `96081` shown in the illustration below, every time a scheduled debiting occurs as part of the registered COF purchase, the callbacks are sent to each of the specified URLs since this condition applies to both of the configured callbacks.

    ![](images/ecommpay/dbl/en_dbl_projects_callbacks_example.svg)

-   When you deactivate or delete a configured callback with a certain set of conditions, either of the following will happen: if there are other active callbacks with identical settings, the callbacks will continue to be sent to the URLs specified in the configured settings of these callbacks; otherwise, callbacks will no longer be sent if this specific event takes place.

### Configuring and managing callbacks {#section_isx_kwp_nsb .section}

To add a new callback and to configure its settings:

1.  Select the project you need.

    Go to **Projects** and select the required project in the **Your projects** dropdown list on the settings tab.

2.  Open the **Callbacks** tab on the left of the project information card.
3.  Specify conditions that will trigger a callback in accordance with the callback settings application aspects described above.
4.  Save the configured settings of the callback.

    **Note:** If the **Save** button is not enabled, it means that either certain required information is missing or the provided URL is invalid.


To activate or deactivate a configured callback, use the **Status** toggle switch in the corresponding row of the list.

To delete a configured callback, click the ![](images/universal/dbl/icon_trashbin.svg) button in the corresponding row of the list and confirm the action.

## Working with domain verification for Apple Pay {#en_dbl_projects_apple_pay_domain_verification}

### Overview {#section_fbh_3vp_nsb .section}

If in any of your projects you need to open Payment Page in an iframe element \(directly on the web service page\) or in a modal window when using the Apple Pay method for payment processing, you have to register relevant domains of your web service in the Apple Pay service. Dashboard allows you to manage the list of domains of your web service relevant for working with Apple Pay in the **Apple Pay Domain Verification** tab of the **Projects** section. There are no restrictions on the number of domains that can be registered for the project.

![](images/ecommpay/dbl/en_dbl_projects_domains.svg "Domain verification form")

### Requirements {#section_bvq_zsh_jgc .section}

When registering domains to work with the Apple Pay method via Payment Page \(with opening the payment form in an iframe element or a modal window\), keep in mind the following:

-   All domains intended for use with a payment form supporting Apple Pay must be registered.Note that you need to specify the full domain name \(FQDN\) including all domain levels from lowest to highest. If one of these domains is not registered, the Apple Pay method will still be displayed in the payment form. However, any payment attempts with this method will be declined.
-   Domains can be registered only if they are specified in a contract with Ecommpayor approved in consultation with your account manager.
-   Only the verification file provided by Ecommpay can be used \(details [below](en_dbl_projects.md#section_lqt_5vp_nsb)\).Third-party files cannot be used with Payment Page of Ecommpay.
-   Verification files must be hosted only at the specified addresses on registered domains.Modification of these addresses or redirection to external resources is not permitted.

### Managing the list of domains {#section_lqt_5vp_nsb .section}

To register a domain:

1.  Perform the required preliminary technical work.

    To do so, take the following steps:

    1.  Download the `apple-developer-merchantid-domain-association` domain verification file [from the Ecommpay repository](https://paymentpage.ecommpay.com/.well-known/apple-developer-merchantid-domain-association).
    2.  Add the downloaded file to the `.well-known` folder of each active domain in the root directory \(resulting in the following full URL: `https://<fully qualified domain name of your service>/.well-known/apple-developer-merchantid-domain-association`\).
    3.  Allow Apple IP addresses to enable domain verification and payment processing \([details](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server)\).
2.  Access the Dashboard interface.
3.  Open the domain registration form.

    Go to the **Apple Pay Verification Domain** tab and click **Add new**.

4.  Select the legal entity you needin the **Legal entity** dropdown list.
5.  Specify the domain names.

    To do so, specify the full domain name for each \(the fully qualified domain name, including domains of all levels, for example, `www.traveltowels.cosmoshop.vrg`\) in the **Domain name** tab and confirm by clicking the ![plus](images/ecommpay/dbl/icon_add.svg) button. Keep in mind that no more than ten domain names can be added at a time. Incorrectly specified domains can be removed using the ![trashbin](images/universal/dbl/icon_trashbean2.svg) button.

6.  Submit the domain registration request by clicking **Save**.

    **Note:** If the **Save** button is not enabled, it means that no **Legal entity** has been selected, and at least one **Domain name** has not been filled in.

    If the registration request is rejected, a corresponding error message is displayed in the Dashboard interface, as well as the recommendations for resolving the issue.

    If the issue cannot be resolved independently, contact the Ecommpay technical support specialists for assistance.

7.  Make sure that the domains are registered.

    To do so, check for the presence of relevant entries on the domain list in the **Apple Pay Verification Domain** tab.


Note that domains cannot be deleted from the list after registration; however, if necessary, domains can be deactivated.

To deactivate a registered domain or to reactivate a previously deactivated one, use the **Status** toggle switch in the corresponding row of the list. Keep in mind when activating domains that just like when registering them, you may encounter errors. Such errors are accompanied by relevant notifications displayed in the Dashboard interface.

### Useful links {#section_isx_kwp_nsb .section}

The following articles can be useful when you work with the Apple Pay method via Payment Page in an iframe element or a modal window:

-   [Apple Pay](pm_applepay.md)—about the Apple Pay method and the specifics of working with it.
-   [Opening Payment Page in an iframe element of an HTML page](en_PP_method_Embedded.md)—about opening the payment form in an iframe element.
-   [Opening Payment Page in a modal window](en_PP_method_ModalWindow.md)—about opening the payment form in a modal window.



---

# Monitoring and performing payments {#en_dbl_payments}

An article about the capabilities of monitoring payments, performing various types of purchases, refunds, and payouts as well as managing regular COF purchases \(subscriptions\) via Dashboard.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_payments_overview}

Dashboard interface allows you to monitor payment processing and perform payments in the following sections:

-   **Payments**—a section for monitoring information on all payment typesand performing certain operations, which includes initiating capture and cancel operations within a two-step purchase, refunding purchases of any type, and issuing payouts.
-   **Payment links**—a section for performing payment link purchases.
-   **Manual payments**—a section for performing singleMO/TO payments and payouts as well as sending batch requests to capture held funds or cancel authorisation holds and to issue mass refunds and payouts.
-   **Subscriptions**—a section for managing subscriptions.
-   **Remittances**—a section for making B2B payments to corporate accounts \([learn more](en_b2bremit_about.md)\).

In both**Payments**and **Manual payments** sections, payment processing can be monitored in the corresponding consolidated register, with the possibility to filter data. In each register, users can also view detailed payment information about individual payments. Detailed payment information is shown in separate tabs, which allows users to switch between the register and the tabs more efficiently.

![](images/ecommpay/dbl/en_dbl_overview.svg "Payments list in the Payments section")

When performing payment operations in the Dashboard interface, you can initiate a:

-   `single` operation when parameters are specified directly in the Dashboard interface and one request is sent to execute one operation.
-   `mass` operation when parameters are uploaded in a file of the specified format following which a batch request is sent to execute multiple operations.

Access to sections **Payments**, **Payment links**,and **Manual Payments** and their specific features is granted through a relevant set of permissions. Therefore, if any of the features described below is not available to a certain user, you need to verify whether the user account in question has the appropriate set of permissions.Moreover, in order to perform MO/TO payments andpayouts, users are required to have two-factor authentication enabled when accessing Dashboard. Payouts may also need to enter verification codes sent by text \(SMS\) to confirm executing the operations. To learn more, see [How to access](en_dbl_overview.md).

The guidelines on how to monitor payment processing, initiate payments, and work with batch requests are provided below.

## Monitoring payment processing {#en_dbl_payments_control}

Dashboard users can monitor information about amounts, statuses, and other attributes of the processed payments. For this purpose, you can use the **Payments** section with the comprehensive information about all payment types and the sections with the information about specific payment types. Each of these sections contains a list with the standard filtering tools \([learn more](en_dbl_interfaces.md)\). In addition, sections **Payments**, **Manual payments**, and **Subscriptions** have payment information tabs that specify details of individual payments and all operations initiated within them \(to open the payment information tab, click the row of the payment you need in the list\).

![](images/ecommpay/dbl/en_dbl_payment_details.svg "Payment information tab")

To monitor information about specific payments:

1.  Select the section you need: **Payments**, **Payment links**, **Manual payments**, or **Subscriptions**.
2.  Find rows with the information about specific payments in the list. Use filters, if necessary.
3.  Verify the information you need, either in the list or in the payment information tabs, if they are available.

However, when you work with lists, keep in mind the following:

-   Information in lists and payment information tabs is shown with a time lag which can take up to several minutes. While automatic data refresh is not supported, you can refresh data in the payments list with the use of the ![](images/ecommpay/dbl/en_icon_refresh.svg) button located in the left corner above the list.
-   The number and the order of columns in the lists can be customised, which means that with the appropriate set of permissions the lists can be arranged according to individual needs.
-   Key attributes of payments, which include identifier, type, status, amount, and currency, are by default shown in the first columns of the lists. They are used for filtering data with predefined filters on the filtering panel. It depends on the list which attributes and filters are available for filtering data.
-   The **Amount** field shows the payment's *base amount* to which the status of the said payment currently applies.

    For example, if a partial refund for 20 EUR was issued for the payment of 100 EUR, then the status `partially refunded` applies to the amount of 100 EUR, while the refund amount and the remaining amount are shown in the **Refunded** and **Available for refund** fields.

    Another example is a regular COF purchase. For this payment type, the `Amount` field shows the actual amount of the received funds.


If you have any questions about working with lists, contact your account manager.

## Performing purchases {#en_dbl_payments_purchases}

### Overview {#en_dbl_payments_purchases_overview}

Dashboard allows users to:

-   Create, send, and deactivate payment links in order to process one-time purchasesand register regular COF purchases \(if necessary\). General description of the payment link purchase workflow and possible statuses can be found in the [corresponding article](en_platform_invoice_model.md).
-   Take MO/TO \(Mail Order / Telephone Order\) payments using a payment form when the customer provides payment card details over the phone, by email, or other means of communication. MO/TO payments are processed as one-time purchases according [to the workflow](en_platform_sms_model.md).[Certain restrictions](en_Gate_moto.md) may apply.
-   Manage authorisation holds as part of executing two-step purchases. Held funds can be captured or released with the use of individual and batch requests. General description of the two-step purchase workflow and possible statuses can be found in the [corresponding article](en_gate_payment_auth.md).

### Requirements {#en_dbl_payments_purchases_requirements}

To perform purchases by using Dashboard, the following requirements must be met:

-   Two-factor authentication is required for accessing Dashboard in order to take MO/TO payments.
-   The user account must be granted the appropriate permissions. Each action, including capturing held funds and releasing authorisation holds, requires a specific permission.
-   Required actions are supported for the selected projectand the payment method.

If any issues regarding access rights occur, they can be solved with the merchant's specialists.

### Payment link purchases {#en_dbl_payments_purchases_payment_link_purchases}

You can use payment links to accept one-time purchasesand, if necessary, also register regular COF purchases performed as part of subscription payments. For example, the customer can use the link to pay for an airline ticket or subscribe to a streaming service with the first month subscription fee debited from their account.

![](images/ecommpay/dbl/en_dbl_payment_invoice.svg "Specifying payment parameters")

![](images/ecommpay/dbl/en_dbl_payment_invoice_booking_info.svg "Specifying booking information")

![](images/ecommpay/dbl/en_dbl_payment_subscription_via_invoice.svg "Specifying parameters to perform a purchase and register a subscription")

![](images/ecommpay/dbl/en_dbl_payment_invoice_complete.svg "Notification that the link has been created")

![](images/ecommpay/dbl/en_dbl_payment_invoice_registry.svg "Monitoring purchase processing in the payment links list")

To perform a one-time purchase with the use of a payment link\(while also registering a regular COF purchase if necessary\):

1.  Open the tab to create a new payment link.

    Go to **Payment links**, click **New payment link** on the left of the filtering panel, and select **One Time**if you need to perform a purchase or **Subscription** if you need to perform a purchase and register a subscription.

    You can also open the **Subscription** tab by clicking **Create Subscription** in the **Subscriptions** section.

2.  Specify purchase parameters and create the link.

    Fill in the fields and click **Create payment link**.

    When filling in the fields, keep in mind that:

    -   The amount is entered as a decimal number with a point to separate fractional part \(for example, `314.15`\).
    -   Payment method selection is not available until the payment ID and the project have been specified.
    -   The validity period of the payment link cannot exceed 30 days.
    -   If the toggle switch **Send e-mail to the Customer** is on, then the payment link is sent to the provided customer's email address automatically; if the toggle switch is off, make sure you send the payment link to the customer.
    -   If the subsequent scheduled debits are registered, you must use correct identifiers in the **Subscription** tab: an identifier of the initial payment \(specified in the **Payment ID** field\) and an identifier of the payment within which scheduled debits are performed \(specified in the **Subscription Payment ID** field\) are not the same, and each must be unique within the project.
    -   If the COF purchase is registered for an undefined period, the end date of that period is set as follows: it will be either the expiry date of the relevant payment card \(for card payments\) or a date 10 years after the last day of the month in which the COF purchase was registered \(for all other payment methods\).
    -   If any of the following payment methods—**Card payments**, **Apple Pay**, **Click to Pay**, or **Google Pay**—is selected, and passing start and end dates of the booked service is set as required for the project, you must specify these dates \(applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922; for more details, refer to your Ecommpay account manager\).
    -   If **Card payments** is a selected payment method, then it isrecommended that you specify the customer's email. If it is not provided, the customer will be requested to specify it when entering payment data.
    -   If the fields are filled incorrectly, the error messages are shown.
    -   The **Create payment link** button is enabled when all required parameters have been specified correctly \(payment description and the customer's email are not required, but it is recommended you provide them to minimize risks during payment processing\).
3.  If necessary, send the payment link to the customer.

    This may be needed if, for example, auto-sending was not turned on when you were completing the new payment link form. In this case, in the notification window that opens, copy the link using the ![](images/universal/dbl/icon_copy.svg) button and send it to the customer.

4.  Make sure that the purchase has been processedand, if relevant, the subscription has been registered.

    You can do this by checking the status of the purchase in the payments list or in the payment links list—it should state `success`. The comprehensive list of possible statuses for payment link purchases can be found in [the corresponding article](en_platform_invoice_model.md).

    If you perform a purchase to register a subscription, then you can check its status in various registries: in the payments list it should state `scheduled recurring processing`, in the payment links list it should state `success` while in the subscriptions list it should state `active`. The comprehensive list of possible statuses for regular COF purchases can be found in [the corresponding article](en_platform_sheduled_recurring_model.md).

    Once a regular COF purchase is registered, you can update its settings if you have the appropriate permissions in Dashboard. The steps are described [below](en_dbl_payments.md).


If you need to deactivate the payment link \(before the customer makes the payment\), turn on the toggle switch **Deactivate** in the corresponding row of the list in the **Payment links** section.The link will no longer be valid, even if the link was already sent to the customer, and the customer will not be able to use it for making the payment.

### MO/TO payments {#en_dbl_payments_purchases_moto}

To take a MO/TO payment:

1.  Go to the **Virtual Terminal** tab.

    Go to **Manual payments**, click **Request** on the left of the filtering panel, and switch to the **Virtual Terminal** tab.

2.  Specify payment parameters and send the request to open the payment form by filling in the fields and clicking **Pay**.

    When filling in the fields, keep in mind that:

    -   The payment ID must be unique for the specified project.
    -   The amount is entered as a decimal number with a point to separate fractional part \(for example, `314.15`\).
    -   The **Pay** button is enabled when all required parameters have been specified.
    ![](images/ecommpay/dbl/en_dbl_payment_moto_initiation.svg)

3.  In the payment form specify the required data and confirm the payment by filling in the fields in the payment form that opened and click the **Pay** button.

    If the field **Country** is used, enter the country code in accordance with ISO 3166-1 alpha-2. The list of country codes can be found in [Country codes](en_country_codes.md)\).

    ![](images/ecommpay/dbl/en_dbl_payment_moto_pp.svg)

4.  Make sure that the payment has been processed.

    You can do this by checking the status of this payment in the payments list—it should state `success`.

    If the payment has been declined, its status switches to `decline`. The decline can happen due to a variety of reasons. For example, it can be caused by providing incorrect card details, in which case you should initiate another payment with a new payment ID while making sure that the card details are specified correctly.


### Single capture and cancel operations {#en_dbl_payments_purchases_single_capture_cancel}

To initiate debiting of the authorised amount \(cancel authorisation hold\) as part of executing an individual two-step purchase:

1.  If necessary, locate the purchase that requires debiting \(release\) of the authorised amount.

    You can use the Search function \(search by payment ID, for example\) or go to the **Payments** section and apply necessary filters in the lists \(for example, filter by operation type—`auth`, or by payment status—`awaiting capture`\).

2.  Open the payment information tab for the target purchase.

    Click the corresponding row in the list of the **Payments** section.

3.  Send a capture \(cancel\) request.
    1.  Click the **Capture** button located on the payment management panel \(at the top left of the payment information tab\) to initiate the debiting of the authorised amount \(click the **Cancel** button to release the authorisation hold\).

        ![](images/ecommpay/dbl/en_dbl_payment_capture_cancel.svg)

    2.  In the window that opens, specify the required amount, which can be the entire authorised amount or its part.

        When changing the authorised amount, keep in mind that this capability is not universally supported \(due to regional specifics or other reasons\) and that certain restrictions are imposed by payment systems \(to learn more, see [Request for partial debit or release of authorised amount](en_gate_payment_auth.md#section_flr_s1g_k3b)\).

    3.  Confirm your request by clicking **Capture** \(**Cancel**\).

        **Note:** If buttons **Capture** and **Cancel** remain inactive, it may mean that one of these operations is already being processed. If these buttons are absent, it may mean that performing such operations is not allowed for the payment.

4.  Make sure that the `capture` \(`cancel`\) operation has been processed.

    You can do this by checking the status of this operation in the tab with the detailed information about the target purchase. You can also check the status of this purchase in the payments list. The status of the operation \(`capture` or `cancel`\) should state `success`, while the status of the purchase should state `success` if the held funds were captured and `cancelled`—if the hold on funds was released.


If the operation request has been declined, its status switches to `decline` while the payment status remains `awaiting capture`.

### Mass capture and cancel operations {#en_dbl_payments_purchases_mass_capture_cancel}

To perform `capture` or `cancel` operations using a batch request:

1.  Create and prepare the file with the `capture` \(`cancel`\) operations data in the specified format.

    You can find the file requirements with the template and a file sample [below](en_dbl_payments.md).

    **Note:** When preparing the file, keep in mind that it must contain operations of only one type—either `capture` or `cancel`, while both the entire authorised amounts and the partial amounts can be specified as the amounts to capture \(cancel\). It is important to remember that changing the authorised amount is not universally supported \(due to regional specifics or other reasons\) and that certain restrictions are imposed by payment systems \(to learn more, see [Request for partial debit or release of authorised amount](en_gate_payment_auth.md#section_flr_s1g_k3b)\).

2.  Go to **Mass Captures** \(**Mass Cancels**\).

    Go to **Manual payments**, click **Request** on the left of the filtering panel, and switch to the **Mass Captures** \(**Mass Cancels**\) tab.

3.  Upload the file with the list of operations and check it for data consistency.

    Drag the file or use the **Browse** button to upload.

    Following the validity check, either the **Send request** button is enabled, or the error message is shown. In the latter case, you can view the details of the error \(using the **File preview** toggle and then the **File details** button\), correct the error and re-upload the file.

    ![](images/ecommpay/dbl/en_dbl_payment_capture_batch.svg)

4.  Send the batch request by clicking **Send request**.
5.  Make sure the requests have been processed.

    You can monitor statuses and indicators of batch processing and statuses of individual operations.

    To monitor the state of batch processing in the list of mass requests, click **Mass requests** on the filtering panel in the **Manual payments** section, find the row of the batch you need in the list and check its status and indicator. Keep in mind that the time it takes to process operations and to update their status information can significantly vary depending on the number of operations in the batch. When the batch has been processed, its status should state `Done`.

    To check the status of individual operations, check the status of the payments that require performing `capture` or `cancel` operations in the payments list \(they should have the status `success` when the authorised amount is debited or `cancelled` when the authorisation hold is released\). You can also check the statuses of operations in the corresponding payment information tabs \(they should state `success` or `decline` depending on the operation result\).


## Managing subscriptions {#en_dbl_payments_subscriptions}

### Overview {#en_dbl_payments_subscriptions_overview}

Along with other types and categories of payments, the Ecommpay payment platform allows you to process *regular COF purchases*, which a type of purchase when the merchant initiates a series of regularly recurring fund transfers from the customer to the merchant according to a set schedule. These debit operations are performed automatically in the platform, thus allowing the customers to pay for *subscriptions* for specific services of the merchant.

Dashboard allows users toregister regular COF purchases \(*subscriptions*\) and monitor their processing. You can:

-   Configure and update subscription settings.
-   Monitor processing of debits.
-   Manage debiting retries if an individual debiting is declined.
-   Cancel debiting series of the registered COF purchases when they are no longer needed.

To utilise these capabilities, you can use the **Subscriptions** section in Dashboard that can be accessed with an appropriate set of permissions \([details](en_dbl_roles_overview.md)\). This section has a subscriptions list and payment information tabs containing information about regular COF purchases.

**Note:** In the Dashboard interface, a regular COF purchase can be referred to as *subscription*, *recurring payment*, and *regular recurring*, all used synonymously.

You can view information about a regular COF purchase in the subscriptions list after this purchase has been registered in the platform. The following statuses can be assigned to a regular COF purchase:

-   **Not set** is assigned to regular COF purchases that do not have all of their settings specified, hence no automatic debits are executed.In this case, the payment information tab will contain a warning that the user needs to specify the regular COF purchase parameters.
-   **Active** is assigned to activated regular COF purchases with debiting terms already set and automatic debits executed on specified schedule.
-   **Cancelled** is assigned to regular COF purchases with subsequent automatic debits cancelled.

![](images/ecommpay/dbl/en_dbl_subscription.svg "Payment information tab with subscription details")

Each tab with information about a regular COF purchase \(subscription\) has several panels including the payment management panel, the **Registration payment** panel with information about the regular COF purchase registration, and the **Recurring payment** panel with the data of all regular COF purchase debits performed so far. To view information about any of the operations executed as part of the regular COF purchase, click the item you need in the list of operations on the panel. You can also manage subscription settings, cancel subsequent debiting executed as part of the subscription, and view change history in this tab. The buttons for performing these actions become active on the payment management panel if you have the appropriate permissions.

### Registering subscriptions {#en_dbl_payments_subscriptions_creating}

The Ecommpay payment platform allows you to register regular COF purchases with automatic debits in a variety of ways including when payments are processed via Payment Page \([details](en_pp_recurring.md)\)and Gate \([details](en_Gate__payments_on_saved_data.md)\)as well as by migrating information about COF purchases from other acquirers \([details](en_gate_data_migration.md)\).

In Dashboard you can register regular COF purchases with the use of payment links by specifying additional information when you create them \([details](en_dbl_payments.md)\).

### Configuring subscription settings {#en_dbl_payments_subscriptions_updating}

To specify or modify the debiting terms of the regular COF purchase \(subscription\):

1.  Open the payment information tab of the subscription you need.

    You can use the Search function \(search by payment identifier, for example\) or go to **Subscriptions** and use the registry and filters.

2.  Open the **Subscription settings** window and switch to editing mode.

    Click **Go to Settings** in the payment management panel and then click **Edit** at the bottom of the window that opens.

3.  Specify or modify the parameters of the regular COF purchase.

    Fill in the fields and click **Save**.

    When filling in the fields, keep in mind the following:

    -   If the regular COF purchase identifier was not provided at the time of registration, the **Recurring payment ID** field is required. If the identifier has been provided, this field is read only.
    -   Fields to specify the debiting amount, debiting period, and the date when the next debiting is supposed to occur are required. If at least one field is left empty, an attempt to save changes triggers an error notification.
    -   The date when the next debiting is supposed to occur cannot precede the current date and cannot occur later than the expiration date of the regular COF purchase.
    -   Fields **Currency** and **Subscription end date** are read only. The currency of the subscription is always the currency of the registration payment. If the last recurring date has not been specified in the regular COF purchase registration request, it is set according to the rules applied by the platform. If you need, you can cancel the payment before the subscription expires by using the subscription section \([details](en_dbl_payments.md)\). You can also configure the subscription schedule by using the corresponding endpoint of the Gate API \([details](en_gate_payment_recurring_manage.md)\).
    -   Fields **Every** \(for specifying the multiplier to increase debiting period\) and **Description** are optional.
    If you need to discard any unsaved changes to the subscription settings, click **Cancel**.

4.  Make sure that the changes have been saved.

    You can do this by clicking **Settings History** on the payment management panel: the registry of changes to subscription terms should contain a record of the update.


![](images/ecommpay/dbl/en_dbl_subscription_edit.svg)

### Managing debiting retry attempts {#en_dbl_payments_subscriptions_retry}

#### Overview {#section_u5b_r4s_wzb .section}

One attempt is usually enough to perform a scheduled debit operation executed as part of a COF purchase. However, in some cases, for example, when the customer's account has insufficient balance, it can be useful to retry debiting after a certain amount of time. The Ecommpay payment platform has the capability to retry COF purchase debits automatically \([learn more](en_gate_cof_retry_attempts.md)\).

This capability is set up upon agreement with your Ecommpay account manager, and when it is supported for the project, you can configure a custom schedule for debiting retries for each project \(which will be applied to every regular COF purchase within this project\) as well asmanage and cancel debiting retries in the Dashboard interface.

If the capability of debiting retries is set up for the project, the information about retry attempts is shown in subscription information tabs of Dashboard. These tabs allow you to switch between two viewing modes. You can view the information about retries by clicking the **Show retries** button. To return to viewing the information about the initial debit operation, click **Back to main operation**.

![](images/ecommpay/dbl/en_dbl_temp_operation.svg "Working with the debit operation")

![](images/ecommpay/dbl/en_dbl_temp_retry.svg "Working with the debiting retry")

Depending on the viewing mode, the panels contain the following information.

|Panel|Working with debit operations|Working with debiting retries|
|-----|-----------------------------|-----------------------------|
|1. Panel with the list of all actions|contains the list of debit operations and refunds for a specific regular COF purchase\(each list item corresponds to an individual debit operation, shows its status and can show the status of debiting retries\)

|contains the list of retry attempts for a specific debit operation\(each list item corresponds to an individual retry attempt, shows its status, and is marked with the `retry operation` attribute\)

|
|2. Panel for performing a specific action.|contains the information about a specific debit operation\(including an explanatory note to the status of the debiting retries\)  
 and buttonsto switch to the list of debiting retries, to customise the retry attempts settings, and to cancel the retry attempts

|contains the information about a specific retry\(including the `retry operation` attribute\) and the button to return to the list of all debit operations executed as part of a COF purchase

|
|3. Panel with information about a specific action|contains detailed information about a specific retry|contains detailed information about a specific retry|

The following statuses are assigned to the retries attempted as part of a scheduled debit operation:

-   `retries active`—the debiting retry has been scheduled in the payment platform\(when the scheduled debit operation was declined by the payment system or the issuer\).
-   `retry in progress`—the retry attempt is being performed.
-   `retries successful`—one of the attempted retries resulted in debiting the funds from the customer to the merchant.
-   `retries unsuccessful`—all available retries have been declined.
-   `retries cancelled`—retry attempts have been cancelled\(either by request from the merchant or automatically, due to modification of the COF purchase debiting terms or other reasons\).

#### Configuring the retry schedule {#section_gbs_vt4_b3c .section}

The payment platform allows you to implement one schedule of debiting retries which will apply to all regular COF purchaseswithin one project. It can be a default schedule from Ecommpay or a custom schedule that merchants can set up on their owndepending on the specific project.

The schedule implemented for a project can be customisedby modifying its specific parameters or by resetting them to default. Keep in mind that a retry attemptfor this project that was scheduled before the retry schedule was customised is performed according to the initially set time and date\(according to the previous schedule\). However, if any of these attempts is declined after the schedule was modified and it is possible to perform the next attempt of this debiting retry in the payment platform, then the new attempt is scheduled and performed according to the updated schedule.In either case, the information about each subsequent retry attempt is sent to the web service in the callback notifying that a debiting attempt was declined \([details](en_gate_cof_retry_attempts.md)\).

To modify the retry attempts schedule for the specific project:

1.  Open in the tab of the project you need the tab that allows configuring the subscription retry settings.

    To do so, navigate to the **Projects** section, select in the **Your projects** dropdown menu the project you need and open the **Subscription retry settings** tab. \(You can also get to this tab directly from the **Subscriptions settings** by clicking **Configure retries settings**. Make sure to check that the project selected in the dropdown menu is the one you need.\)

2.  Select the retry schedule you need.

    To use the default schedule, select **Default subscription retry schedule**.

    To use the custom schedule, select **Custom subscription retry schedule** and specify the days on which retries will be performed for each declined debit operation by clicking the buttons with the ordinal numerals of the days you need. You can schedule one to ten retry attempts with the minimum delay of 24 hours between them.

3.  Save changes by clicking **Save**.

    **Note:** Keep in mind that the changes will be applied when you click the **Save** button. You will not be asked to confirm the action additionally.

4.  Make sure that the new schedule has been saved.

    To do so, open the tab with the settings of the project you need and check the schedule implemented for this project.


![](images/ecommpay/dbl/en_dbl_payments_custom_subscription_schedule.svg "Configuring the retry schedule")

#### Monitoring retry attempts {#section_rcl_t4s_wzb .section}

Dashboard allows users tomonitor processing of debiting retries. This information can be accessed via subscription tabs that contain information about all debit operations performed as part of a regular COF purchase and retries of individual debitings\([details](en_dbl_payments.md#section_u5b_r4s_wzb)\).

To view information about retry attempts for a specific debit operation:

1.  Open the payment information tab of the subscription you need.

    You can use the Search function \(search by payment identifier, for example\) or go to **Subscriptions** or **Payments** and use the registry and filters.

2.  Go to the detailed information about the specific debit operation.

    Select the item on the panel with the list of debit operations on the left of the subscription tab.

3.  Open the list of the debiting retries.

    Click **Show retries** on the panel for managing the debit operation.

4.  Go to the detailed information about the specific retry.

    Select the item on the panel with the list of debiting retries on the left of the subscription tab.

5.  If necessary, return to the list of all debit operations.

    Click **Back to main operation** on the panel for managing the debiting retry or click ![](images/universal/dbl/icon_back.svg) in the top right corner of the panel with the list of retries.


#### Cancelling subsequent retry attempts {#section_iny_v4s_wzb .section}

To cancel retrying a specific debit operation:

1.  Open the payment information tab of the subscription you need.

    You can use the Search function \(search by payment identifier for example\) or go to **Subscriptions** or **Payments** and use the registry and filters.

2.  Go to the detailed information about the specific debit operation.

    Select the item on the panel with the list of debit operations on the left of the subscription tab.

3.  Cancel debiting retries.

    Click **Cancel retries** on the panel for managing the debit operation and confirm cancellation.

4.  Make sure that the subsequent retries have been cancelled.

    Check the status of the retries in the row of the corresponding debit operation on the panel with the list of all debit operations: it should change from `active` to `retries cancelled`.


### Cancelling the subscription {#en_dbl_payments_subscriptions_cancelling}

To cancel automatic debits executed as part of the regular COF purchase:

1.  Open the payment information tab of the subscription you need.

    You can use the Search function \(search by payment identifier, for example\) or go to **Subscriptions** and use the registry and filters.

2.  Open the **Subscription settings** window and select cancelling the subscription.

    Click **Go to Settings** in payment management panel and then click **Cancel Subscription** in the top left corner of the window that opens.

3.  Confirm cancellation in the modal window.
4.  Make sure that the subscription has been cancelled.

    Click **Settings History** on the payment management panel: the registry of changes to subscription terms should contain a record of the update. In addition, the status of the regular COF purchase in the subscriptions list should state **Cancelled**.

    ![](images/ecommpay/dbl/en_dbl_subscription_history.svg)


## Issuing refunds {#en_dbl_payments_refunds}

### Requirements {#section_fzj_3dq_k1c .section}

Dashboard interface allows users to refund all types of purchases either in full or in part, which includes refunding individual debits executed as part of the COF purchase. Issuing refunds can be done with the use of individual and batch requests, and in each case, the following requirements must be met:

-   The user account has been granted the right to issue refunds.
-   The purchase \(the individual debit executed as part of the COF purchase\) has been fully processed.
-   Refunds of the required type are supported for the payment method used to make the purchase.
-   The balance under which an initial payment was performed has enough funds for issuing a refund.

If any issues regarding these requirements occur, they can be solved with the specialists in charge of granting access rights and working with balances.

### Single refunds {#section_iks_3dq_k1c .section}

In Dashboard you can issue single refunds \(full and partial, for all types of purchases\) both in the payments list and in the payment information tabs \(for example, if you need to refund a specific operation within a COF purchase\).

![](images/ecommpay/dbl/en_dbl_refund_in_registry.svg "Initiating a refund in the payments list")

![](images/ecommpay/dbl/en_dbl_payment_refund.svg "Initiating a refund in the payment information tab")

To refund a single purchase:

1.  If necessary, locate the purchasethat needs to be refunded.

    You can use the Search function \(for example, search by payment identifier\) or go to the **Payments** section and apply necessary filters in the lists \(for example, filter by payment type: `purchase`, `recurring`, `invoice`, or `account verification`\).

2.  Open the window to initiate a refund.

    Click the ![](images/universal/dbl/icon_refund.svg) button in the corresponding row of the payments list, or open the payment information tab and click the **Refund** button located on the payment management panel or on the panel with the information about the specific operation of the COF purchase.

    **Note:** If the **Refund** button is disabled, it can mean that the purchase has not been fully processed yet. If this button is not shown at all, it can mean that refunding purchases is not supported for the utilised payment method \(in which case refer to your Ecommpay account manager for more details\).

3.  Send a refund request.

    In the window that opens, specify the amount you need to refund—full available or its part \(the amount available for refund is also shown in this window\), then click **Refund**.

    **Note:** Keep in mind that clicking the **Refund** button initiates the refunding operation. You will not be separately asked to confirm your request.

4.  Make sure that the refund has been issued.

    You can check the status of the `refund` operation in the payment information tab \(it should state `success`\) or the status of the payment in the payments list \(when the payment is refunded in full, the status is `refunded` or `reversed`; when only the part of the payment amount is returned, the status is `partially refunded`\).


If the refund has been declined, the status of the operation switches to `decline` while the status of the payment remains unchanged. The decline can happen due to a variety of reasons. For example, it can be caused by the lack of funds, in which case you can add funds to the balance and try to issue a refund again.

### Mass refunds {#section_upt_3dq_k1c .section}

To issue multiple refunds using a batch request:

1.  Create and prepare the file with the refund data in the specified format.

    You can find the file requirements with the template and a file sample [below](en_dbl_payments.md).

    **Note:** When preparing the file, keep in mind that to refund purchases, you must specify the identifier of the payment to be refunded in the `general.payment_id` field while to refund an individual debiting operation performed as part of the COF purchase, you must also include the identifier of the operation to be refunded in the `general.operation_id` field.

2.  Go to the **Mass Refunds** tab.

    Go to **Manual payments**, click **Request** on the left of the filtering panel and switch to the **Mass refunds** tab.

3.  Upload the file with the list of refunds and check it for data consistency.

    Drag the file or use **Browse** button to upload.

    Following the validity check, either the **Send request** button is enabled or the error message is shown. In the latter case, you can view the details of the error \(using the **File preview** toggle and then the **File details** button\), correct the error and re-upload the file.

    ![](images/ecommpay/dbl/en_dbl_mass_refund.svg)

4.  Send the batch request by clicking **Send request**.
5.  Make sure the refunds have been processed.

    After the batch request has been sent and you can see the notification that it has been accepted, it is important to check that the refunds have been processed. Look up the batch status in the list of mass requests—the status should state `Done` \(click **Mass requests** on the filtering panel in the **Manual payments** section and find the row of the batch you need in the list\). You can also monitor status information of individual refunds using the column **Indicator**. Keep in mind that the time it takes to process refunds and to update their status information can significantly vary depending on the number of refunds in the batch.

    To check the status of individual refunds, check the status of the payments that need to be refunded in the payments list \(they should have the status `refunded` or `reversed` when the payment is refunded in full and `partially refunded` when only the part of the payment amount is returned\). You can also check the status of a refund in the corresponding payment information tab \(it should state `success` or `decline` depending on the operation result\).

    ![](images/ecommpay/dbl/en_dbl_payment_mass_refund.svg)


If you have any questions about issuing refunds, contact technical support specialists.

## Performing payouts {#en_dbl_payments_payouts}

### Requirements {#en_dbl_payments_payouts_overview}

Dashboard interface allows users to perform payouts with the use of individual and batch requests. In both cases, the following requirements must be met:

-   Two-factor authentication is enabled for the Dashboard user account in question.
-   The user account has been granted the right to perform payouts.
-   Payouts are supported for the selected payment method.
-   The balance under which payouts are performed has enough funds.
-   If additional data is required to perform a payout, it has to be provided within 22 hours.

If any issues regarding these requirements occur, they can be solved with the specialists in charge of granting access rights and working with balances.

### Single payouts {#en_dbl_payments_payouts_single}

To perform a single payout:

1.  Go to the **Single payout** tab.

    Go to **Manual payments**, click **Request** on the left of the filtering panel and switch to the **Single payout** tab.

2.  Specify payout parameters and send a payout request.

    Fill in the fields and click **Send Request**; if needed, enter the SMS verification code in the popup window.

    When filling in the fields, keep in mind that:

    -   The amount is entered as a decimal number with a point to separate fractional part \(for example, `314.15`\).
    -   Fields for the payment method specific parameters are not available until the project, the amount, the currency, and the payment method have been specified.
    -   Among the specific fields only the required ones are shown.
    -   If the field is filled incorrectly, the error message "Specify payout parameters" is shown.
    -   The **Send Request** button is enabled when all parameters have been specified correctly.
    ![](images/ecommpay/dbl/en_dbl_payment_payout.svg)

3.  If additional payment information is required, specify the parameters needed \(you can also decline the payment\).

    When the payout is processed, its parameters are validated, following which a notification is displayed in the **Single payout** tab. If the parameters satisfy all requirements, the notification states that the request has been successfully processed. If certain parameters, which are not mandatory in general but can be required in a specific situation, are absent, fields where you can enter the required additional information are shown. In this case, to proceed with the payment, specify the information needed and click **Proceed**; to decline the payment, click **Reject Payout**.

    If for any reasons \(to get more accurate information, for example\) you need to pause and return to performing the payout later, you can find this payout in the payouts list using the **Clarification** filter and clicking the corresponding row.

    **Note:** By default, additional payment information has to be provided no later than 22 hours after the clarification request was received.However, certain payment systems may require additional information specified within shorter amounts of time. Contact technical support for more information about specific payment methods.

    ![](images/ecommpay/dbl/en_dbl_payment_payout_clarification.svg)

4.  Make sure that the payout has been processed.

    Verify the status of this payout in the Payouts or Payments list—it should state `success`.


If the payout is declined, the payment status switches to `decline`. It can happen due to a variety of reasons. For example, it can be caused by the lack of funds, in which case you can add funds to the balance and try to perform a payout again.

### Mass payouts {#en_dbl_payments_payouts_mass}

#### General steps {#section_dmf_4zl_rlb .section}

To perform a series of payouts using a batch request:

1.  Create and prepare a file with the payout data in the specified format.

    You can find the file requirements with the template and a file sample [below](en_dbl_payments.md).

2.  Go to the **Mass payouts** tab.

    Go to **Manual payments**, click **Request** on the left of the filtering panel and switch to the **Mass payouts** tab.

3.  Upload the file with the list of payouts and send the batch request.

    Drag the file or use the **Browse** button to upload. After the file has been uploaded, make sure the **Send request** button is enabled. Use this button to send the batch request; if needed, enter the SMS verification code in the popup window.

    If the file is incorrect, the **Send request** button remains inactive and the error message is shown. In this case, view the error details \(using the **File preview** toggle and then the **File details** button\), correct the errors, and re-upload the file.

    ![](images/ecommpay/dbl/en_dbl_mass_payout.svg)

4.  Make sure the specified data is sufficient and the payouts have been processed.

    After the batch request has been sent and you can see the notification that it has been accepted, it is important to check that the payouts have been processed. Look up the batch status in the list of mass requests—the status should state `Done`. Keep in mind that the time it takes to process payouts and to update their status information can significantly vary depending on the number of payouts in the batchand the payment methods used.

    If a single payout request in the entire batch requires additional information, the batch status switches to `Clarification`. In this case, you can either specify the parameters needed for the target payouts, or decline them. Learn more about these options below.

    You can also monitor status information of payouts in the batch using the column **Indicator** in the list of mass requests.

    ![](images/ecommpay/dbl/en_dbl_payment_mass_refund.svg)


#### Submitting additional information {#section_umd_4ty_1tb .section}

When the payout batch request is processed, parameters of each payout have to be validated. If the parameters satisfy the requirements, no additional actions are necessary. If certain parameters, which are not mandatory in general but can be required in a specific situation, are absent, you need to submit additional information. This necessity is indicated by the status `Clarification` for individual payouts and the entire batch in the list of mass requests.

If submitting additional information is necessary for certain payouts in the batch, you can selectively specify the required parameters or decline these payouts. In such cases, you can work with individual payouts \(which is convenient when additional information is required only for one payout in the entire batch, for example\) or several payouts at the same time \(when additional information is required for a series of payouts, for example\) and specify the information needed in the Dashboard interface or by uploading a file.

*To submit additional information for a single payout:*

1.  Locate and open the payout information tab you need.

    To find this payout in the**All requests** list, use the **Clarification** filter and click the corresponding row.

2.  Specify the requested data and click **Proceed**.

You can also use the payout information tab to decline the processing of this payout by clicking **Reject Payout**.

*To submit additional information for a series of payouts:*

1.  Locate and open the batch with the target payouts whose parameters require clarification.

    To find this batch in the **Mass requests** list, use the **Clarification** filter and click the corresponding row.

2.  Switch to editing mode by clicking **Manage** on the left of the filtering panel.
3.  Specify the required parameters.

    You can use the Dashboard interface directly by entering data into the cells marked with ![](images/universal/dbl/icon_pencil.svg) or update the file you have uploaded. In the latter case, download the file using the ![](images/universal/dbl/icon_file_download.svg) button. Specify the required parameters in the cells marked `*required*` and upload the updated file using the ![](images/universal/dbl/icon_file_upload.svg) button.

    In each of these cases, you can submit additional data for payouts that you need to be processed, not necessarily all that require it. The ones which you have decided not to specify additional information for are going to be declined after the clarification waiting time is over.

    **Note:** By default, additional payment information has to be provided no later than 22 hours after the clarification request was received.However, certain payment systems may require additional information specified within shorter amounts of time. Contact technical support for more information about specific payment methods.

    ![](images/ecommpay/dbl/en_dbl_masspayouts_clarification.svg)

4.  Save changes and send data by clicking **Apply**.

Editing mode also allows you to decline processing of individual payouts. Check the rows you need \(in the first column of the table\) and click **Reject**.

If you have any questions about performing payouts, contact technical support specialists.

## Mass payments data {#en_dbl_payments_mass_info}

### File upload requirements {#en_dbl_payments_mass_info_requirements}

To prepare the file, you can use the template available for download on Dashboard or [here](files_for_downloads/dashboard/TemplateMassPayments.csv).Having downloaded the template, you can fill it in any CSV file editor, for example, Microsoft Excel. Each file used for adding criteria in bulk must meet the following requirements:

-   The data files must be uploaded in CSV format and the character encoding must be UTF-8 without BOM \(Byte Order Mark string\).
-   The file size cannot exceed 128 MB.
-   The first row must contain the names of parameters. The order of parameters can be random.
-   The subsequent rows must contain values of target parameters. Specifying values for optional parameters is recommended but not required.
-   All parameter values in the file must meet the requirements provided [in the table below](en_dbl_payments.md).
-   If operation parameters are specified in strings \(not in table format\), parameter values in each row must be separated by a semicolon \(";"\). In addition, the fields without values are separated by semicolons in the same way as the fields with values, and two or more ";" characters can follow one another, for example:

    ![](images/universal/dbl/en_dbl_file_data_as_string.png)

    If you use Microsoft Excel to create and prepare the file, make sure that strings do not include incorrect separators or extra characters. You should use a different editor, for example Notepad, to check if extra characters have been added.


### Parameters for mass payments {#en_dbl_payments_mass_info_parameters}

When adding data to files, you can use the parameters presented in the table below.

|Parameter|Description|
|:--------|-----------|
|operation\_type  
 string, required

|Operation type. The value can be `capture`, `cancel`, `refund`,  and `payout`.  
 Example: `refund`

|
|general.project\_id  
 integer, required

|Project identifier assigned by Ecommpay at the stage of integration.  
 Example: `35`

|
|method  
 string, required

|Payment method identifier.For the full list, see [Payment method codes](en_pm_codes.md).  
 Example: `card`

|
|general.payment\_id  
 string, required \*

|Payment identifier unique within the merchant's project.  
 A string which contains between 1 and 255 characters and which can include any letters, digits, and symbols in UTF-8 encoding.  
 Example: `payment_536231`.  
 \* For refund, general.payment\_id must be the identifier of the purchase to be refunded

|
|general.operation\_id  
 string, required \*

|Payment operation identifier provided by Ecommpay.  
 A string which contains between 1 and 255 characters and which can include any digits in UTF-8 encoding.   
 Example: `58468298003`.  
 \* To refund a specific debiting operation performed as part of the COF purchase, specify the identifier of the operation to be refunded

|
|payment.amount  
 integer, required

|Payment amount in minor currency units.  
 An integer between `1` and `10000000000000` \(without a decimal separator between the integer and fractional parts\).  
 Example: `1905` for 19.05 and `190500` for 1905

|
|payment.currency  
 string, required

|Payment currency code in ISO 4217 alpha-3 format.  
 Example: `EUR`

|
|payment.description  
 string, optional \*

|Payment description.  
 A string, must not exceed 255 characters.  
 Example: `Deposit 12456`.  
 \* Required for refunds

|
|account.number  
 string, optional

|Account number of the customer.  
 A string, must contain between 1 and 100 characters.  
 Example: `1670033323`

|
|account.bank\_id  
 integer, optional

|Bank identifier received from Ecommpay. For more information about banks and their IDs, see the section on payment methods in the documentation, or contact Ecommpay technical support specialists.  
 An integer, must be `1` or greater.  
 Example: `421`

|
|account.customer\_name  
 string, optional

|First name and last name of the account holder.  
 A string, must contain 1 character or more.  
 Example: `John Johnson`

|
|account.branch  
 string, optional

|Name of the customer's bank branch.  
 A string, must not exceed 255 characters.  
 Example: `Bank branch`

|
|account.city  
 string, optional

|City of the bank branch location.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|account.region\_id  
 integer, optional

|Region or state identifier of the bank branch location received from Ecommpay.For more information about regions and their IDs, see the section on payment methods in the documentation, or contact Ecommpay technical support specialists.  
 An integer, must be `1` or greater.  
 Example: `3`

|
|card.pan  
 integer, optional \*

|Card number of the customer.  
 An integer, must contain 32 digits or fewer.  
 Example: `2333776109871312`.  
 \* Required for payouts if `token` is not present

|
|card.year  
 integer, optional \*

|Expiration year of the customer's card.  
 An integer between `2020` and `9999`.  
 Example: `2024`.  
 \* Required for payouts

|
|card.month  
 integer, optional \*

|Expiration month of the customer's card.  
 An integer between `1` and `12`.  
 Example: `12`.  
 \* Required for payouts

|
|card.card\_holder  
 string, optional  \*

|Name of the cardholder as specified on the card.  
 A string, must not exceed 255 characters.  
 Example: `John Johnson`.  
 \* Required for payouts

|
|token  
 string, optional \*

|Card token received from Ecommpay.  
 Example: `Z0yTL5shY8ddhpxdQyplRPJYmGV7Kv`.  
 \* Required for payouts if `card.pan` is not present

|
|customer.id  
 string, optional \*

|Identifier of the customer within the merchant's project.  
 A string, must not exceed 255 characters.  
 Example: `customer313`.  
 \* Required for payouts

|
|customer.country  
 string, optional \*

|Customer country code in ISO 3166-1 alpha-2 format.  
 Example: `GB`.  
 \* Required for payouts

|
|customer.city  
 string, optional \*

|Customer city.  
 A string, must not exceed 255 characters.  
 Example: `London`.  
 \* Required for payouts

|
|customer.state  
 string, optional

|Region or state of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `West Midlands`

|
|customer.zip  
 string, optional

|Postal code of the customer's billing address.  
 A string,must not exceed 10 characters.  
 Example: `B152SA`

|
|customer.street  
 string, optional

|Street of the customer's billing address.  
 Example: `Edgbaston`

|
|customer.first\_name  
 string, optional \*

|First name of the customer.  
 A string, must not exceed 255 characters.  
 Example: `John`.  
 \* Required for payouts

|
|customer.last\_name  
 string, optional \*

|Last name of the customer.  
 A string, must not exceed 255 characters.  
 Example: `Johnson`.  
 \* Required for payouts

|
|customer.day\_of\_birth  
 string, optional \*

|The customer's day of birth in `DD-MM-YYYY` format.  
 Example: `21-12-1989`.  
 \* Required for payouts

|
|customer.phone  
 string, optional

|Phone number of the customer.  
 A string, must be a sequence of digits, must contain between 4 and 24 characters, and can start with "+" .  
 Example: `4402035551981` or `+4402035551981`

|
|customer.email  
 string, optional

|Email of the customer.  
 A string, must not exceed 255 characters.  
 Example: `test@mail.com`

|
|customer.ip\_address  
 string, optional \*

|IP address of the customer.  
 A string, must not exceed 255 characters.  
 Example: `127.0.0.1`.  
 \* Required for payouts

|

### Possible errors {#en_dbl_payments_mass_info_errors}

The following error messages can appear after the validity check of the file uploaded to Dashboard has been performed.

|Error message|Possible reason|
|-------------|---------------|
|File is empty|File is empty|
|Columns are duplicated|Parameter has been duplicated|
|File does not contain required columns|Required parameters are missing|
|Incorrect file format|Extension or format of the file is incorrect|
|File is broken|Encoding or data structure is incorrect|
|Payment method is not available \(line\# number\)|Specified payment method is not available|
|Specified project\_id does not belong to specified merchant account|Project identifier is incorrect|
|Project\_id is not numeric \(line\# number\)|Project identifier is non-numeric|
|Project\_id does not exist \(line\# number\)|Nonexistent project identifier has been specified|
|Payment\_id is empty \(line\# number\)|Payment identifier has not been specified|
|Payment with payment\_id already exists \(line\# number\)|Specified payment identifier has already been registered in the payment platform|
|Amount is empty \(line\# number\)|Payment amount has not been specified|
|Incorrect Amount \(line\# number\)|Incorrect payment amount value|
|Currency is empty \(line\# number\)|Payment currency has not been specified|
|Incorrect Currency \(line\# number\)|Incorrect payment currency value|
|Invalid date|Card expiration date has not been specified or is incorrect|
|Card.year is in past \(line\# number\)|Expired card; expiration year is incorrect|
|Card.month is in past \(line\# number\)|Expired card; expiration month is incorrect|



---

# Financial accounting {#en_dbl_balances}

An article about balances for working with the platform and the special aspects of their use as well as monitoring balances and currency exchange rates and working with bank accounts via Dashboard.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_balances_overview}

Dashboard allows you to monitor the current state of the company's balances, get information about exchange rates used for currency conversion, and work with your designated bank accounts for funds withdrawal from the company's balances at Ecommpay in the **Finance** section. This section can be accessed only with a separate set of permissions provided by default to user accounts with the assigned `Finance` and `Merchant Admin` roles.

When working with the **Finance** section, you should keep in mind the following special aspects of using the information it contains:

-   *Availability.* Only **IN/OUT** and **OUT** balances are shown in the interface by default. To be able to view **IN** balances, contact your Ecommpay account manager.
-   *Applicability.* Information shown in the **Finance** section should be used for reference. It is not recommended that you use this information for performing final review and account reconciliations.The information should be seen as tentative because processing cash inflow and outflow data may lead to inevitable technical and organizational lags stemming from the specifics of interconnection between payment service providers, process of finalising fees, and other procedures. Dashboard presents a snapshot of data available at the moment, hence it may differ from the consolidated results.
-   *Accuracy.* Balance information is shown with a delay of up to 30 minutes. The time lag stems from the specifics of technical procedures including various calculations, checks, and transfer of information to long-term storage. If you need to obtain up-to-date information on specific operations, you can use payment information tabs, callbacks \([learn more](en_platform_callbacks.md)\) and HTTP requests to the Gate API \([learn more](en_Gate_payment_status_request.md)\).
-   *Data refreshing.* Auto updating of the information in the **Finance** section is not supported, but you can use the tab refresh feature of your browser.

The overview of balance information and guidelines on how to monitor balances, get information about exchange rates used for currency conversion, and work with bank accounts are provided below.

## Monitoring balances {#en_dbl_working_with_balance}

### Balances and the special aspects of their use {#en_dbl_balances_aspects}

Within the framework of the payment platform as a whole and Dashboard in particular, the term *balance* refers to a balance in a certain currency available for the merchant's operating activities which includes withdrawing these funds to the merchant's settlement accounts.On the basis of their intended operating purpose, balances are divided into the following types:

-   IN—for cash inflows from processing purchases and refunds
-   OUT—for cash outflows from issuing payouts
-   IN/OUT—for all kinds of operating cash inflows and outflows from processing purchases, refunds, and payouts

When working with balances, you should keep in mind the following special aspects and restrictions:

-   A balance can reflect data only in one currency.
-   Currencies in which balance data is shown are determined by Ecommpay. Default currencies include USD, GBP, and EUR; for availability of other currencies, refer to your account manager.

    In cases when currencies in which operations are processed differ from balance currency, currency conversion is performed.

-   Operations pertaining to *card* payments \(with the direct use of payment cards\) and to *alternative* payments \(with the use of alternative payment methods\) are always separated into different balances.
-   Operations pertaining to payments made with different alternative payment methods in one balance currency can be separated into different balances or consolidated in one.

    For instance, when several payment methods from one provider are integrated for payment processing in a specific region with local settlement currencies and one balance currency \(for example, EUR\), all operations pertaining to payments made with these methods can be consolidated in one balance.

-   Operations pertaining to purchases and payoutsmade with a specific payment method are consolidated in one IN/OUT balance and are not separated into balances of different types \(IN,OUT, IN/OUT\). IN orOUT balances can be used in case when only purchases oronly payouts are supportedfor a specific payment method.
-   The Ecommpay specialists set up balances and link them to the corresponding agreementsand payment methods only after the merchant submits a request to the account manager. If you have any questions related to working with balances, contact your account manager.

### Monitoring real-time balance data {#en_dbl_balances_real_time}

Real-time balance information includes total amounts for each currency used and the list of balances.\(Keep in mind that balance calculation may take up to 30 minutes and, consequently, balance information may reflect the aforementioned delay.\)

1.  Open the **Real-time** tab of the **Finance** section.
2.  Expand the tab you need\(**IN**,**OUT**, **IN/OUT**\)and make sure the balance register displays the required information: total amounts in available currencies at top of the tab and the list with balance information below.

    If the **IN** tab is not available in the **Finance** section, you should contact your Ecommpay account manager.

3.  If necessary, filter the information by relevant agreements.

    You can use the dropdown list of agreements concluded with Ecommpay.


![](images/ecommpay/dbl/en_dbl_balances.svg "The Finance section")

## Monitoring the information about currency conversion rates {#en_dbl_balances_currency_rates}

Dashboard supports the capability to obtain the information about currency conversion rates against the US dollar \(USD\) that are applied to operating and non-operating inflows and outflows. These rates are provided for each hour of the selected date.

To view the conversion rates of a required currency on a particular date, go to the **Currency Rates** tab in the **Finance** section and select a date and a currency.

![](images/ecommpay/dbl/en_dbl_balance_currency_rates.svg "The Finance section")

## Working with bank accounts {#en_dbl_bank_accounts}

### Overview {#section_yk3_vth_42c .section}

Dashboard allows users to create and manage records with the details of bank accounts that merchants can use for funds withdrawal from Ecommpay balances. In each case, the following requirements must be met:

-   Two-factor authentication is required for accessing Dashboard in order to work with bank accounts.
-   The user account must be granted the appropriate role and permissions for working with the bank accounts in the **Finance** section.To learn more about how to access this section in the Dashboard interface, see [Core capabilities and role-based access model](en_dbl_roles_overview.md).

In the **Finance** section, you can monitor all accounts added to the list in the **Bank Accounts** tab and access details of individual bank accounts in the dedicated tabs.Each bank account tab includes a control panel and a panel with the bank account and beneficiary details. In the list of bank accounts, you can also monitor records created by the Ecommpay specialists.

![](images/ecommpay/dbl/en_dbl_bank_account_registry.svg "List of all added bank accounts")

![](images/ecommpay/dbl/en_dbl_bank_account_card.svg "Tab with the bank account details")

A record with the bank account details can have the following statuses:

-   `Draft` is assigned to records saved as drafts; the record can be edited\(with no time limitations\).
-   `Waiting for approval` is assigned to created records that have been sent for approval by Ecommpay.
-   `Correction is needed` is assigned to records that have not been approved by Ecommpay and require the bank account details corrected\(according to the recommendations provided on the control panel of the tab\).
-   `Active` is assigned to records that have been approved by Ecommpay and can be used to perform financial operations.
-   `Blocked` is assigned to records that have not been approved by Ecommpay\(with no possibility to edit a created record or to add a new bank account using the same details\).
-   `Archived` is assigned to records that have been deactivated by a Dashboard user \(with no possibility to edit a created record or to add a new bank account using the same details\).

### Adding a bank account {#section_rvg_wth_42c .section}

To create a record with the bank account details, you should:

1.  Open the tab for adding a new bank account.

    To do so, go to the **Bank Accounts** tab of the **Finance** section and then click **Add bank account** in the top left corner of the tab. In the window that opens, select the merchant legal entity and confirm the action by clicking **Continue**.

2.  Specify the information necessary for performing funds transfers.

    To do so, provide the bank account and beneficiary details in the following fields \(some of them will be prefilled\):

    -   **Merchant legal entity**—the name of the merchant legal entity\(selected at step 1 and not editable at this step\).
    -   **Agreement number**—one or more agreement numbers that are associated with the specified merchant legal entity. Withdrawal of funds to the bank account you are adding will fall within the scope of these agreements.
    -   **Multicurrency**—an indicator showing that the multicurrency operations are supported \(by the bank\)for the bank account; possible values are `Yes` and `No`.

        Note that if the bank account you are adding does not support payments in one of the Ecommpay default currencies \(USD, GBP, or EUR depending on the utilised interaction flow with the platform\), then the transfer of funds to this account will include currency conversion. You also have an option to add an intermediary bank account on the **Intermediary bank** panel.

    -   **Desired settlement currency**—codes of the Ecommpay default currencies that are preferred for transfers to the multicurrency bank account.
    -   **Account currency**—a currency code for the single currency bank account.
    -   **Bank BIC/SWIFT**—an international identification code of the bank where the account is held. When you are filling in this field, you can use the dropdown list that becomes available if at least three characters have been entered.
    -   **Name of the financial institution**—the name of the bank where the account is held\(prefilled according to the specified SWIFT code, not editable at this step\).
    -   **Registration country of the financial institution**—the country where the bank is registered\(prefilled according to the specified SWIFT code, not editable at this step\).
    -   **IBAN \(Account number\)**—an international bank account number for funds withdrawal from the merchant's balances at Ecommpay.
    -   **Beneficiary type**—the type of the funds transfer recipient that owns the bank account in question; possible values are the merchant legal entity specified at step 1 \(`Merchant Company`\) or a third party \(`Other Company`\).
    -   **Beneficiary name**—name of the funds transfer recipient as specified in the bank account details\(if the beneficiary type is `Merchant Company`, this field is prefilled according to the merchant legal entity specified at step 1; if the beneficiary type is `Other Company`, you have to fill in the field manually.
    -   **Registered address of the beneficiary**—the funds transfer recipient's registered address \(if the beneficiary type is `Merchant Company`, this field is prefilled according to the merchant legal entity specified at step 1 and can be edited; if the beneficiary type is `Other Company`, you have to fill in the field manually.
    -   **Beneficiary registration number**—an identification number of the funds transfer recipient from the relevant national register of beneficial ownership\(if the beneficiary type is `Merchant Company`, this field is prefilled according to the merchant legal entity specified at step 1 and can be edited, albeit only for the bank account being added; if the beneficiary type is `Other Company`, you have to fill in the field manually
    -   **Additional information**—proof confirming that funds can be transferred to a third partyspecified as the `Other Company` beneficiary type \(for example, you can add digital files of contract documents between your company and the third party in question\).
    **Note:** If you save the record with the bank account details as a draft, you can continue working on it later. To edit the draft, open the bank account tab and click **Edit** on the control panel.

3.  Send the bank account information for approval to Ecommpay.

    To do so, click **Create bank account**. Once you click the button, the added bank account is marked as `Waiting for approval` in the list and can only be edited if its status changes to `Correction is needed`.

4.  Make sure that the added bank account has been approved by Ecommpay or, if necessary, return to step 2.

    To do so, monitor the its status in the bank accounts list: within five business days, the status should change from `Waiting for approval` to either `Active` \(if the bank account is approved by Ecommpay and the bank account can be used\) or `Correction is needed` \(if the bank account details require corrections and you need to return to step 2 to edit the account information according to the recommendations provided on the control panel of the tab\).


Below are the tabs for a multicurrency bank account that belongs to a third-party beneficiary and a single currency bank account that belongs to the merchant's legal entity.

![](images/ecommpay/dbl/en_dbl_bank_account_multycurrency.svg "Adding a multicurrency account")

![](images/ecommpay/dbl/en_dbl_bank_account_singlecurrency.svg "Adding a single currency account")

### Archiving a bank account {#section_s5f_5gn_42c .section}

In the list of bank accounts, you can archive those that are no longer used for performing financial operations. Note that an archived account cannot be reactivated. If you need to use the bank account details from an archived account, you should add a new bank account with the same details.

To archive a bank account, you should:

1.  Locate the account in the list of all bank accounts and open the corresponding tab.

    To find the account you need, go to the **Bank Accounts** tab and use the **Merchant Legal Entity** filter.

2.  Archive the account by clicking **Archive** on the control panel.
3.  Confirm the action in the pop-up window.
4.  Make sure that the account has been archived.

    To do so, check the status of the record with the bank account details in the list. The status should state `Archived`.




---

# Risk management {#en_dbl_risks}

An article about risk management in ecommerce and the capabilities of monitoring fraudulent operations and configuring blacklists via Dashboard.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Introduction {#en_risks_intro}

The development of commerce goes hand in hand with the development of financial fraud. E-commerce is not the exception. One of the most widely spread types of fraud in this sphere occurs when the payment card information gets compromised and the perpetrator poses as a cardholder. Other types of fraud are becoming more common as well—both for cards and other payment instruments.

To counteract fraud, payment systems and other parties instrumental in payment processing—issuers, providers, and merchants—employ a comprehensive set of measures. First and foremost, these measures are used to perform two types of checks:

-   Authentication of customers and their payment instruments which includes using the 3‑D Secure authentication protocols, Address Verification Service, and other similar tools.
-   Validation of payments based on their parameters which includes checking whether the parameters match the whitelists and blacklists and various rules as well as conducting different kinds of risk analysis and assessment.

With the Ecommpay payment platform, you have full access to these checks in order to reduce the risk of fraud. For fraud detection and prevention,

-   Make sure your web service is set up to work efficiently with the customer authentication solutions. For instance, in case of 3‑D Secure 2 the use of the challenge flow can be set as preferable for each processed payment while in case ofthe AVS check address information can be specified in the initial request which allows performing verification without the involvement of the customer.In addition, when 3‑D Secure protocols are used, the issuer bears financial responsibility for processing fraudulent payments \(while it is waived for other parties\).This also allows preventing chargebacks with the reason code fraud. Smart use of these capabilities ensures high level of both fraud protection and payment acceptance rates.
-   Make sure that the payment validation rules are set up and maintained. They should be used together with the rules of other parties \(Ecommpay, payment systems, and issuers\) and should ensure payments are screened efficiently. Together with the Ecommpay specialists, determine restrictions and rules specific to a given project which will be used in the payment platform and can be updated whenever necessary. In addition to such rules, you can compile your own whitelists and blacklists which will factor in the payment processing by the payment platform.
-   Monitor cases of detected fraud and declined payments. When necessary, be available to respond and take part in the review sessions of special cases with the Ecommpay specialists following which correct the settings already in use. This can be achieved both by using Dashboard capabilities and by contacting your account manager and technical support specialists.

The Dashboard interface allows you to compile your own whitelists and blacklists as well as monitor fraud cases detected by Ecommpay and payment systems. This section combines a brief overview of risk management in general with the description of procedures that can be performed using Dashboard.

## General process {#en_risks_process}

### Overview {#en_risks_process_overview}

The process of financial fraud prevention can be characterised as follows.

First of all, this process is multilayered. It involves different stakeholders—merchants, providers, payment systems, and issuers, and each of them is responsible for fraud prevention at their level in respect to the payments they handle. It also involves different tools some of which can be commonly used by several parties \(for example, 3‑D Secure authentication\) while others can be distinctly specific to each party \(for example, whitelists and blacklists\). Utilising these tools consistently ensures multiple-step filtering of operations and achieving efficiency of the overall performance.

Secondly, this process implies that two-way communication predicated on feedback is expected between all stakeholders. Thus, if a certain operation is established to be fraudulent after it has been processed and finalised, this information is brought to the attention of all parties involved and allows modifying the countermeasures intended to prevent similar operations at different levels.

Thirdly, at each of these levels the process can be presented as an iterative cycle with four steps—setup, monitoring, response, and analysis.

![](images/universal/dbl/en_dbl_risks_circle.svg)

Thus, financial fraud prevention can be presented a system of interlinked actions which repeat cyclically at different levels.

Main steps of this process—setup, monitoring, response, and analysis—are described in the sections that follow with the focus on the aspects that can be useful and relevant for merchants.

### Setup {#en_risks_process_setup}

#### Authentication {#section_tmd_gtd_rnb .section}

The payment platform supports a range of auxiliary procedures for customer authentication such as the 3‑D Secure authentication, and the authentication on merchant's request, and the Address Verification Service. Moreover, to ensure efficient authentication, certain additional capabilities can be useful—for instance, collecting and submitting additional customer data.

As a rule, if the interaction with the platform takes place through Gate, the integration with the web service may require additional changes and modifications, while if the Payment Page is used, everything is performed in the payment platform and does not involve the web service at all. To learn more about auxiliary procedures, go to [Gate](en_gate_procedures.md), about additional capabilities—go to sections [Gate](en_Gate_Additional_capabilities.md) and [Payment Page](en_PP_Additional.md).

In order to work efficiently with these tools, merchants should:

1.  Determine capabilities and procedures that need to be maintained for specific projects.
2.  If necessary, ensure that target capabilities and procedures are supported by the web service.

To learn more about combining procedures and capabilities as well as their implementation and setup, contact your account manager and technical support specialists.

#### Validation {#section_rcv_fvy_1tb .section}

When payments are validated, their parameters are checked in the platform against various rules which can be common for all payments or specific for payments of individual merchants and their projects. First and foremost, this applies to whitelists and blacklists—they can be used both by merchants and by Ecommpay.

In order to work efficiently with these tools, merchants should:

1.  Together with the Ecommpay specialists determine rules and restrictions applicable to specific projects.
2.  Compile their own whitelists and blacklists which can be viewed and edited in Dashboard and which are going to be used in the platform together with other rules.

To learn more about configuring validation rules and working with whitelists and blacklists, including transferring such lists from other systems, contact your account manager and risk management specialists.

### Monitoring {#en_risks_process_monitoring}

Before operations are processed in the Ecommpay payment platform, they need to be validated. During the validation process, the parameters of each operation are checked against the predefined rules, and the operation is automatically deemed one of the following:

-   Fraudulent—if any parameter of the operation is blacklisted or the risk of executing this operation \(based on all its parameters\) is considered high. In this case, the operation is declined, and the Ecommpay payment platform sends the web service a final callback with the operation status `decline` and the error code \(the comprehensive list of such error codes and their description is available in the section [RCS codes](en_platform_payment_info_codes.md)\).
-   Suspicious—if it is not possible to reach a definitive conclusion regarding the risks associated with the execution of the operation after the predefined algorithms were used, and additional evaluation is required. In this case, the operation is processed while the Ecommpay specialists additionally review the operation and decide whether it is trustworthy or fraudulent. Then, if necessary, they report their findings to the merchant's employees for further assessment. Following the review by the specialists, different measures can be taken which includes issuing a refund and updating the blacklist.
-   Trustworthy—if any parameter of the operation is whitelisted or the risk of executing this operation \(based on all its parameters\) is considered low. In this case, the operation is executed.

**Note:**

Keep in mind that such risk assessment includes prioritising list rules. In general, if at least one operation parameter is blacklisted, then the operation is deemed fraudulent because the blacklist takes precedence over the whitelist. However, there can be cases when the whitelist is prioritised and the operation is deemed trustworthy \([learn more](en_dbl_risks.md)\). Hence, whitelists and blacklists should be approached with maximum caution.



Risk monitoring does not stop after risks have been initially assessed by the merchant and Ecommpay: if Ecommpay approved an operation, it does not exclude the possibility this operation is going to be flagged by other parties involved in payment processing. Likewise, the approval of the operation by all parties involved does not exclude the possibility of detecting fraud retrospectively. In such cases, the information about the fraud attempts and cases detected by other parties is reported to Ecommpay, and then, by the Ecommpay specialists to the merchant's employees. In addition, the merchant can monitor the execution of operations and learn about declined or fraudulent operations using Dashboard or via email \(more details below\), and in any unusual situation should contact the Ecommpay risk management team.

### Response {#en_risks_process_response}

The merchant's response is based on the assessment of the risks associated with the operation execution and whether the operation is deemed fraudulent after it has been processed and finalised.If the response is efficient, it can significantly impact the success rates of fraud prevention and doing business as a whole.

Cases when the merchant's response is needed include the following:

-   *The operation is rejected as fraud by Ecommpay.* In this case, reviewing the reason of rejection \(by examining the callback or using Dashboard\) is recommended. If necessary, the following response is due:
    -   Update the blacklist—if the operation is definitely fraudulent and it is possible to identify a condition for blocking similar operations in the future \(for example, a phone number of the customer\).
    -   Update the whitelist—if it is certain that the operation is trustworthy, albeit characterised by the unusual behaviour of the customer, and it is possible to identify a condition for confirming reliability of similar operations in the future.
    -   Contact the Ecommpay specialists—if there are any questions regarding the operation processing.
    -   Initiate the operation again—if it is applicable to the given user scenario and \(following the update of the whitelist or the approval by the Ecommpay specialists\) it is clear that the rejection of the operation is not going to be repeated.
-   *The operation is flagged as suspicious by Ecommpay.* In this case, analysing the reason and the nature of suspicions is recommended. If necessary, contact the customer for clarification as well as the Ecommpay specialists—to coordinate the required course of action following which necessary measures should be taken. This may involve issuing refunds and updating whitelists and blacklists.
-   *The operation has been approved by Ecommpay, but is flagged as fraudulent by the other party.* In this case, reviewing the reason of rejection \(by using Dashboard or by contacting the Ecommpay specialists\) is recommended. If necessary, the following response is due:
    -   Update the blacklist—if the operation is definitely fraudulent and it is possible to identify a condition for blocking similar operations in the future.
    -   Initiate the operation again with the updated or expanded list of parameters—if the reason of rejection does not prevent a retry and it is certain that the operation is trustworthy, and it was declined due to incorrect or incomplete data.
-   *The operation has been processed and finalised, but is deemed fraudulent retrospectively.* In this case, revising criteria which were used to flag the operation \(by using Dashboard or by contacting Ecommpay support specialists\) is recommended. If necessary, the blacklist should be updated and the customer affected by fraud should be compensated.

In any unusual case, contact the Ecommpay risk management team.

### Analysis {#en_risks_process_analysis}

To ensure efficient payment processing—with high levels of conversion rates and fraud prevention, merchants should analyse the overall performance on a regular basis. It includes evaluating the ratio of correct and incorrect payment rejections, identifying additional criteria for whitelists and blacklists, determining whether Ecommpay should introduce changes to the procedures of customer authentication and operation validation rules, and so on. All aspects of fraud prevention require constant scrutiny, not in the least because fraud patterns in e-commerce continue to develop as perpetrators attempt to circumvent current countermeasures.

To learn more about analysing risk management efficiency, contact your account manager.

## Monitoring fraudulent operations {#en_dbl_fraud_operations_control}

### Overview {#en_dbl_fraud_operations_control_overview}

The payment platform allows you to monitor information about attempts and cases of fraud detected by Ecommpay and payment systems. You can use the tools of the Dashboard interface and the option of receiving automated emails.

### Using the Dashboard tools {#en_dbl_fraud_operations_control_dashboard}

Use the following tools to monitor fraudulent operations:

-   The payments list in the **Payments** section \(which contains information about all payments\).
-   The fraud register in the **Risks** section \(which contains information about operations flagged as fraud by payment systems\).
-   Fraud reports which are prepared in the **Reports** section.

When working with these registers, you can use standard filtering tools \([learn more](en_dbl_interfaces.md)\) as well as payment information tabs which specify details of individual payments and all operations initiated within them \(to open the payment information tab, click the row of the payment you need in the list\).

Access to fraud information in the **Risks** section and payment information tabs is limited by a separate permissions set and, by default, is granted to user accounts with the `Risks` and `Merchant Admin` roles. In addition, managing reports requires a separate permission that is available to all user accounts but not included in a basic permissions set.

![](images/ecommpay/dbl/en_dbl_risks_payment_registry.svg "Payments list")

![](images/ecommpay/dbl/en_dbl_risks_fraud_registry.svg "Fraud register in the Risks section")

When working with payments lists and fraud register, consider the following:

-   Information in registers and payment information tabs is shown with a time lag which can take up to several minutes. In addition, automatic data refresh is not supported.
-   Payment systems report detected fraud to the payment platform twice a day: before 7:00 and 15:00 UTC+0, which is why you are recommended to monitor this information after the indicated times.
-   The fraud register can contain several records about the same operation with different update dates when the information about this operation is included into several reports from the payment systems.
-   The number and the order of columns in the registers can be customised which means that with the appropriate set of permissions the registers can be arranged according to individual needs. For example, if you need to see the date when the fraudulent operation was performed, you can add the **Purchase date** column to the basic set of columns in the fraud register.

To monitor information about the relevant operations, you need:

1.  Go to the required section: **Payments** or **Risks**.
2.  Find the operation you need using filters if necessary \(![](images/universal/dbl/icon_filter.svg)\).
3.  In the Payments list, the operation declined by Ecommpay as high risk can be found by payment status `decline`and the service response status code \(such codes include `402` and codes from [RCS](en_platform_payment_info_codes.md)\). Operations flagged as fraudulent by other parties can be found by using the fraud indicator \(also with the filter\).
4.  Verify the information you need, directly in the list or in the payment information tabs.

    In the fraud register and the **Fraudulent payments information** located in the payment information tab, you can view the details of the fraud for a certain operation.

    ![](images/ecommpay/dbl/en_dbl_risks_payment_card.svg)


### Receiving automated emails {#en_dbl_fraud_operations_control_mail}

You can monitor information about operations flagged as fraudulent by payment systems not only with the use of different Dashboard tools but also by receiving automated emails sent to the email address associated with the Dashboard user account. Emails with notifications are sent out at 14:00and 17:00 UTC+0 if the platform receives any new information about detected fraud. By default, the option to receive these emails is enabled for all user accounts. You can disable this option on your own, or an employee with the `Merchant admin` role can do it for you.

To disable the option to receive automated emails on your own:

1.  Open the user profile.

    Click the user name or the user account icon in the top right corner and select **My profile** in the dropdown menu.

2.  Disable the **Receive emails about fraudulent transactions** option.

    Switch to the editing mode by clicking ![](images/universal/dbl/icon_pencil.svg) on the **User Profile** panel, turn off the toggle switch and save changes by clicking **Save** on the upper-right side of the **User Profile** panel.

3.  Make sure all changes have been saved.

    The option should be disabled.


## Using whitelists and blacklists {#en_dbl_risks_bwlist}

### Overview {#en_dbl_risks_bwlist_overview}

When operations are validated, their parameters are checked in the platform against various rules, including whitelists and blacklists. These lists can be common for all merchants or specific to an individual project of the merchant.

-   Whitelist is a list of criteria matching any of which indicates that an operation is trustworthy.
-   Blacklist is a list of criteria matching any of which flags an operation as fraudulent.

The following considerations are applied when assessing the risks of processing specific operations:

1.  If at least one of the operation parameters is blacklisted and the blacklist category is **Customer ID**, **Account number**, or **E-mail**, then the blacklist takes precedence over the whitelistand the operation is flagged as fraudulent.
2.  If the condition described above does not apply, but the operation has parameters that are found in the **IP** and **BIN** lists \(one parameter can be blacklisted, the other can be whitelisted, in either combination\), then the whitelist has higher priority and the operation is deemed trustworthy.
3.  If the operation is deemed untrustworthy following the AML\(Anti-Money Laundering; matching the person included in the sanctions list\) and Compliance\(matching the country in the prohibited country list\) checks, it is declined even if some of the operation parameters are whitelisted.

### Interface capabilities {#en_dbl_risks_bwlist_interface_capabilities}

Dashboard allows you to manage criteria of whitelists and blacklists applicable both to your specific projects and to all of your projects. The **Risks** section includes the **Black/White lists** subsection that allows you to do the following:

-   View the list of criteria, using filters, using search and filtering, if necessary.
-   Add new criteria, one by one or in bulk.
-   Delete criteria, one by one only.

You can search for criteria of whitelists and blacklists using filters on the upper panel, which includes the possibility to enter multiple values of one category \(for example, `customer_id`\) separating them by a comma or a space.

Adding risk assessment criteria to whitelists and blacklists is also possible using payment information tabs.This capability is supported for all operations: there are no restrictions on payment typesor payment methods, or whether the operation has to be flagged as fraudulent by a payment system or not.

The capability of managing risk assessment criteria can only be accessed with a separate permissions set. By default, user accounts with the `Risks` and `Merchant Admin` roles are allowed to view whitelists and blacklists and to add criteria to blacklists.In addition, you can request permissions to add criteria to whitelists for individual user accounts by contacting the technical support specialists. This approach to whitelists is determined by their priority, including the case of automated risk analysis, and helps diminish the risks of processing the fraudulent operations.

![](images/ecommpay/dbl/en_dbl_risks_bwlist_registry.svg "Whitelists and blacklists register")

### Adding criteria using payment information tabs {#en_dbl_risks_bwlist_payment_card}

In the payment information tabs, you can add criteria to blacklists \(and if the user account has the appropriate permissions—to whitelists\) for individual operationsinitiated within payments without any restrictions. This is convenient when individual cases of fraud are reviewed, and it allows you to respond quickly. To add criteria:

1.  Locate the payment within which the target operation was initiated. The target operation is the one whose parameter values should be whitelisted \(blacklisted\).

    Use Search \([learn more](en_dbl_interfaces.md#section_r4t_f5m_hlb)\) or filters in the registers in the **Payments** and **Risks** sections.

2.  Open the payment information tab by clicking the row in the register of the selected section.
3.  Add criteria to the whitelist \(blacklist\) by doing the following:
    1.  Click the **Add to list** button on the right of the **Manage operation** panel.
    2.  Select in the window that opens the type of the list \(whitelist or blacklist\), categories available for this operation \(for the criteria you need to whitelist or blacklist\) and identifiers of projects \(to which these changes will apply\). If necessary, you add a comment: it will be the same for all added criteria.

        **Note:** In certain cases, the **Add to list** window may display categories that were not used for performing the target operation. For example, the `email` category can be shown as available, even if the request to perform the operation in question did not contain such a parameter. If this is the case, then nothing is added to the whitelist or blacklist when you attempt whitelisting or blacklisting a criterion.

    3.  Confirm adding criteria to the whitelist \(blacklist\) by clicking **Apply**.

        ![](images/ecommpay/dbl/en_dbl_risks_bwlist_add_from_payment_card.svg)

4.  Make sure that the criteria have been added to the whitelist \(blacklist\).

    Check the register with the list of criteria in the **Black/White lists** subsection.


### Adding criteria using the form {#en_dbl_risks_bwlist_form}

In the **Risks** section, you can add various criteria to blacklists \(and if the user account has the appropriate permissions—to whitelists\) using the form in the **Black/White lists** subsection.This is convenient when different cases of fraud are reviewed and analysed for determining additional criteria of risk assessment, for example, when the need to update whitelists or blacklists does not stem from processing specific operations. To add criteria:

1.  Open the form.

    Go to the **Black/White lists** subsection of the Risks section, click the **Add item\(s\) to list** button on the left of the filter panel.

2.  Add the criteria.

    Select the list you need \(whitelist and blacklist\), specify the required criteria in the target fields, and click **Apply**.

    If any of the fields is filled incorrectly, the corresponding error message is shown. Correct the errors \(or do not complete these fields\) and click **Apply** again.

3.  Make sure that the criteria have been added.

    A notification that the adding request was sent successfully should be shown. You can also verify that the criteria have been added to the criteria list in the **Black/White lists** subsection.


![](images/ecommpay/dbl/en_dbl_risks_bwlist_add_from_form.svg "Adding criteria to the blacklist")

### Adding criteria using the file {#en_dbl_risks_bwlist_file}

#### How to add criteria {#section_e3p_gdr_qnb .section}

If you use additional sources of information about risks, you can add various criteria to blacklists \(and if the user account has the appropriate permissions—to whitelists\) by uploading a file. This is convenient when both whitelists and blacklists need to be updated without referencing specific operations and with no limitations on how many criteria should be added. To add criteria with the help of a file,

1.  Create and prepare the file with the information about criteria in the specified format.

    Note that you can specify criteria for both whitelists and blacklists in the same file. You are required to provide the merchant ID assigned by Ecommpay at the stage of integration for each operation \(if necessary, this identifier can be found in the Payments list—add the **Merchant** column using the register builder\).

    You can find the file requirements with the template and a file sample below.

2.  Open the form of adding criteria in bulk.
    1.  Go to the **Black/White lists** subsection of the **Risks** section.
    2.  Click the **Add item\(s\) to list** button on the left of the filter panel.
    3.  Go to the **Add multiple items** tab.
3.  Upload the file with the list of criteria to add.

    You can either drag the file or use the **Browse** button to upload. After the file has been uploaded, click **Apply** to add the criteria.

    If any of the fields is filled incorrectly, the corresponding error message is shown. Correct the errors in the file, reupload it, and click **Apply** again.

4.  Make sure that the criteria have been added.

    A notification that the adding request was sent successfully should be shown. Also you can verify that the criteria have been added to the criteria list in the **Black/White lists** subsection.


![](images/ecommpay/dbl/en_dbl_risks_bwlist_add_from_file.svg "Adding criteria using the file")

#### File upload requirements {#section_uhy_v3z_1tb .section}

To prepare the file, you can use the template available for download on Dashboard or [here](files_for_downloads/dashboard/TemplateRisks.csv).Having downloaded the template, you can fill it in any CSV file editor, for example, Microsoft Excel. Each file used for adding criteria in bulk must meet the following requirements:

-   The data files must be uploaded in CSV format and the character encoding must be UTF-8 without BOM \(Byte Order Mark string\).
-   The file size cannot exceed 128 MB.
-   The first row must contain the names of parameters. The order of parameters can be random.
-   The subsequent rows must contain values of target parameters. Specifying values for optional parameters is not required.
-   If operation parameters are specified in strings \(not in the table format\), parameter values in each row must be separated by a semicolon \(";"\). In addition, the fields without values are separated by semicolons in the same way as the fields with values, and two or more ";" characters can follow one another, for example:

    ![](images/universal/dbl/en_dbl_risks_bwlist_add_from_file_example.png)

    If you use Microsoft Excel to create and prepare the file, use a different editor, for example Notepad, to check it for errors.


#### Available parameters {#section_jpr_w3z_1tb .section}

When adding data to files, you can use the following parameters.

|merchant\_id  
 integer, required

|Merchant identifier assigned by Ecommpay at the stage of integration.  
 Example: `644`

|
|project\_id  
 integer, required

|Project identifier assigned by Ecommpay at the stage of integration. It identifies the project to which the added criterion applies. When the IP address of the customer is added, the ID of any merchant project can be specified.  
 Example: `1020`

|
|list\_type  
 string, required

|List type. The value can be `whitelist` or `blacklist`.  
 You can specify criteria for both whitelists and blacklists in the same file.   
 Example: `whitelist` for the whitelist

|
|category  
 string, required

|Category of the criterion:

 -   `email`—email address of the customer
-   `customer_id`—the customer ID
-   `pan`—card number of the customer
-   `bin`—bank identification number
-   `ip`—IP address of the customer

   
 When the `ip` category is used, the criterion is added to the lists applicable to all projects of the merchant, regardless of the specified project ID.  
 Example: `email`

|
|value  
 string, required

|Value of the criterion.  
 Example: `joe.doe12@sunmail.com` for email

|
|reason  
 string, optional

|The reason of adding a certain criterion.  
 Example: `The customer requests a refund for each purchase`

|

### Deleting criteria {#en_dbl_risks_bwlist_delete}

You can delete criteria included in the whitelists and blacklists in the **Risks** section. Keep in mind that they should be deleted one by one.

1.  To go to the Criteria subsection, click the **Black/White lists** button in the **Risks** section.
2.  Find the record you need using filters if necessary.
3.  To delete the record, click the ![](images/universal/dbl/icon_trashbin.svg) button in the corresponding line.
4.  Make sure that the record has been deleted from the list.



---

# Working with chargeback callbacks {#en_dbl_chargeback_callbacks}

An article about the capabilities of working with callbacks that communicate information about events occurring within the chargeback process.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_chargeback_callbacks_overview}

When working with the Ecommpay payment platform, you can enable and use the functionality of daily callbacks with information about events occurring within the chargeback process.It is relevant when Ecommpay acts an acquirerand interacts with issuers and card networksrepresenting the merchant's interests \([details](en_faq_chargebacks.md)\). You can use these callbacks along with other interfaces that provide information about chargebacks \(such as the Data API and Dashboard\).

Similar to standard callbacks sent from the Ecommpay payment platform, chargeback callbacks are HTTP POST requests that contain data in JSON format for processing by the merchant’s web service. However, keep the following special aspects in mind when working with chargeback callbacks:

-   Data is sent without any form of digital signature.
-   Callbacks are sent daily at 12:00 UTC. If for any reason delivery cannot be performed at this time, callbacks are sent at 15:00 UTC instead.
-   Callbacks are limited to one URL per merchant project.
-   Callbacks are sent only once. Resending callbacks is not supportedeven if the callback delivery is not acknowledged with the `200 OK` response code or if an error response is returned \(for example `400 Bad Request`\).
-   Callbacks are tied to specific stages within the chargeback process and fall into two types: summary and detailed callbacks \([details](en_dbl_chargeback_callbacks.md)\).
-   Callbacks are triggered only if there is updated data.If no changes are detected, no callback is sent.

Refer to your Ecommpay account manager to integrate chargeback callbacks.

## Callback types {#en_dbl_chargeback_callbacks_types}

### Summary callbacks {#section_yg2_qfq_tgc .section}

Summary callbacks communicate the number of chargebacks for which chargeback process-specific events were recorded in the platform during the reporting period. These events are categorised as follows:

-   `new_chargebacks_summary`—initiation of chargebacks
-   `new_pre_arbitration_summary`—advancement of chargebacks to the Pre-Arbitration stage
-   `new_arbitration_summary`—advancement of chargebacks to the Arbitration stage

For each of these categories, separate callbacks are generated and contain the following set of parameters:

-   `event`—a category of reportable events\(in accordance with the specified options\)
-   `event_date`—the datethe event-related data is sent\(formatted as `YYYY-MM-DD`\)
-   `project_id`—the project identifiercorresponding to the relevant events
-   `merchant_id`—the merchant identifiercorresponding to the relevant events
-   `chargeback_count`—the number of chargebackscorresponding to the relevant events

``` {#codeblock_pns_p3q_tgc .language-json}
{
  "event": "new_chargebacks_summary",
  "event_date": "2025-03-15",
  "project_id": "456",
  "merchant_id": "123",
  "chargeback_count": 5
}

```

Having recorded the information received in the summary callbacks, you can review the itemised chargeback data via detailed callbacks, requests to the Data API \(such as `/chargeback/list` and `/chargeback/get`; [details](en_dbl_api_protocol.md)\), or Dashboard \(using the **Chargebacks** section\).

### Detailed callbacks {#section_rzs_djq_tgc .section}

Detailed callbacks contain itemised information about chargebacks for which chargeback process-specific events were recorded in the platform during the reporting period. These events are categorised as follows:

-   `new_chargeback_details`—initiation of chargebacks
-   `new_pre_arbitration_details`—advancement of chargebacks to the Pre-Arbitration stage
-   `new_arbitration_details`—advancement of chargebacks to the Arbitration
-   `chargeback_cancelled_by_issuer`—withdrawal of the chargeback by the issuer, completion of the chargeback process in favour of the merchant
-   `chargeback_lost`—completion of the chargeback process in favour of the issuer
-   `chargeback_won`—completion of the chargeback process in favour of the merchant

For each of these categories, separate callbacks are generated and contain the following set of parameters:

-   `event`—the category of the reported event\(in accordance with the specified options\)
-   `event_date`—the date whenthe event-related data is sent\(in the `YYYY-MM-DD` format\)
-   `project_id`—the identifier of the projectfor which the reported event is relevant
-   `merchant_id`—the merchant identifierfor which the reported event is relevant
-   `total_chargebacks_count`—the number of chargebacksfor which the reported event is relevant
-   `chargebacks`—an array of objects containing detailed information about each chargebackfor which the reported event is relevant

**Note:** The parameters of the objects in the `chargebacks` array match those of the `Chargeback` object in the Data API \([details](https://api-data.ecommpay.com/)\) with the exception of two parameter names: `chargeback_finalization_date` instead of `chb_completed_at` and `chargeback_status` instead of `status`.

``` {#codeblock_i4p_mxn_lgc .language-json}
{
  "event": "chargeback_won",
  "event_date": "2025-03-13",
  "project_id": "12345",
  "merchant_id": "123",
  "total_chargebacks_count": 1,
  "chargebacks": [
    {
      "chargeback_id": "82256",
      "case_id": "11384",
      "operation_id": "5033683310337533",
      "arn": "1",
      "card_type": "MC",
      "chargeback_status": "WON",
      "reason_code": "13.1",
      "report_date": "2025-03-07",
      "pre_arbitration_report_date": null,
      "arbitration_report_date": "2025-03-10",
      "chargeback_finalization_date": "2025-03-13 00:00:00",
      "respond_by": "2025-03-10 23:59:59",
      "charged_amount": -1,
      "charged_currency": "EUR",
      "credited_amount": 1,
      "credited_currency": "EUR"
    }
  ]
}

```

Having recorded and reviewed the information received in these callbacks, you can proceed to taking subsequent steps of the chargeback process if necessary.

## Setup {#en_dbl_chargeback_callbacks_setup}

To enable chargeback callbacks:

1.  Agree with the Ecommpay account manager on adding this featurefor specific projects, decide on the callback types you need, and provide the destination URL for the web service. Keep in mind that only one URL can be used per merchant project.
2.  Receive a notification from the Ecommpay specialistsconfirming that the feature is enabled.
3.  If relevant chargeback events have occurred, make sure that you have received the corresponding callbacks.

## Use {#en_dbl_chargeback_callbacks_use}

The procedure of responding to each callback on the web service side consists of the following steps:

1.  Accept and confirm the callback receipt.

    For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes.If no errors have been detected upon the receipt, the response code should be `200 OK`. In other cases, the response code should reflect the error type: for example, `HTTP 500 Internal Server Error` if the callback has been received at an incorrect URL of the web service.

    Note that resending of callbacks is not supported.Regardless of the response, even if it indicates failure to receive the callback, the information sent in previous callbacks is not included in subsequent ones.

2.  Perform the required actions in accordance with the guidelines for handling chargebacks \([details](en_faq_chargebacks.md#section_ppz_lhs_q5b)\) and the specifics of the web service.

## Useful links {#en_dbl_chargeback_callbacks_useful_links}

The following sections can be useful for handling chargeback callbacks:

-   [Chargebacks](en_faq_chargebacks.md)—a section on handling chargebacks \(includes an overview, a description of chargeback process, and answers to frequently asked questions\).
-   [Using Data API](en_dbl_api_protocol.md)—a section on using the API that allows retrieving operation and balance data \(includes an overview, a description of interaction with the interface, and detailed information about each endpoints\).



---

# Using Data API {#en_dbl_api_protocol}

Articles about the capabilities and technical specifics of the Data API that allows retrieving information about operations, chargebacks, and balances.

This section covers using the Data API—an API of the Ecommpay payment platform which allows retrieving information about operations, chargebacks, and balances of your projects.

This section includes the following articles:

-   [Overview](en_dbl_api_overview.md)introduces the Data API interface, its features, and how to use it.
-   [Interaction concepts](en_dbl_api_interaction.md)describes main principles of the interaction between the payment platform and the Data API and the workflow of obtaining the data you need.
-   [Retrieving data](en_dbl_using_api.md)focuses on working with individual endpoints in the Data API, with the description of data structures and examples.

Interface specification is available at [https://api-data.ecommpay.com](https://api-data.ecommpay.com/).

-   **[Overview](en_dbl_api_overview.md)**  
An article with the introductory information about the Data API and its capabilities.
-   **[Interaction concepts](en_dbl_api_interaction.md)**  
An article about main principles of the interaction between the payment platform and the Data API and the workflow of obtaining required data.
-   **[Retrieving data](en_dbl_using_api.md)**  
An article about working with individual endpoints in the Data API, with the description of data structures and examples of requests and responses.

**Parent topic:**[Dashboard](en_dbl_about.md)



---

# Overview {#en_dbl_api_overview}

An article with the introductory information about the Data API and its capabilities.

The Data API is an API of the Ecommpay payment platform which allows retrieving balance information, chargeback data, operation data and fraudulent operation data with regard to the access rights to certain projects of the merchant and the specified conditions \(such as the type of the operation and the time when it was performed\). Access rights are determined via the specialized tokens of the Dashboard user accounts while the conditions of data retrieval are specified directly in the API requests.

The Data API is available at `https://data.ecommpay.com/v1` and allows accepting requests at specified endpoints with the use of HTTP, version 1.1 or higher, and the TLS protocol, version 1.2 or higher. Interface specification is available at [https://api-data.ecommpay.com](https://api-data.ecommpay.com/).

To work with the Ecommpay payment platform using the Data API, the merchant needs to:

1.  Make sure the requests can be sent and the responses can be received according to the Data API specification.
2.  Authorize users who require access to the Data API to generate API tokens and secret keys in the Dashboard interface.
3.  Test and deploy the developed solutions into production.

**Parent topic:**[Using Data API](en_dbl_api_protocol.md)



---

# Interaction concepts {#en_dbl_api_interaction}

An article about main principles of the interaction between the payment platform and the Data API and the workflow of obtaining required data.

**Parent topic:**[Using Data API](en_dbl_api_protocol.md)

## Interaction model {#en_dbl_api_info}

When the Data API is used, the Ecommpay payment platform and the merchant's web service interact by exchanging request and response messages in the HTTP format: the web service issues requests and the payment platform responds to those requests. The interaction model is synchronous as the request gets fully processed within one HTTP session and the one-time response is returned as a result, either with the requested information or the information about the error that occurred.

![](images/universal/dbl/en_dbl_uml.svg)

This interaction model implies that all Data API requests \(for instance, for balance information on the merchant's projects\) are processed using only the resources of the payment platform, without resorting to other services and systems. At the same time, depending on the complexity of the request and the volume of the compiled data, the time to process an individual request in the payment platform can significantly vary: from several milliseconds to several minutes \(as a rule, it does not exceed five minutes\).

## Data access model {#en_dbl_api_token}

### Overview {#section_nlt_2nb_tmb .section}

When the Data API is used, access rights are managed with the help of API tokens.

Each of these tokens is generated in the Dashboard interface and is associated with a specific user account and its permissions which regulate access to the merchant's projects. Alongside the token, a secret key is generated to be used for signing requests together with this token and for verifying responses to these requests \(to learn more, see [Signature generation and verification](en_platform_signature.md)\).

![](images/ecommpay/dbl/en_dbl_api_token.svg "Generated token and secret key")

In the payment platform, managing tokens of the Dashboard user accounts is carried out in compliance with the following requirements:

-   Each token is a string, 30 characters long, encoded in UTF-8.
-   Each token is valid from the moment of its generation and till the moment when the new token has been generated or when this token has been deactivated. Keep in mind that a deactivated token cannot be reactivated.
-   Any number of tokens can be generated for one user account; however, the only vaild token is the one which has been generated last.
-   A valid token can be used any number of times without any restrictions imposed on its lifetime.
-   In the payment platform, the token inherits the permissions of the user account it is associated with, thanks to which if the permissions granted to a certain user account are modified, generating a new token is not necessary.
-   Users authorized to manage tokens can generate and deactivate tokens for their user accounts without any specific constrains.
-   If the user account is deleted, the token is not deactivated automatically. However, the data access rights this token has inherited are revoked; hence, if the request is sent with this token, the platform returns the response stating that the access has been denied \(`401 Authorization Required`\).

In the merchant's web service, managing tokens and keys may require additional regulations, in compliance with the company's security policies.

### Granting permissions to manage tokens {#section_xp4_y5l_5mb .section}

Similarly to other cases of granting permissions to work with Dashboard, only the user whose user account has been assigned the **Merchant admin** role can grant and withdraw permissions to manage tokens.

To grant the right to manage tokens, the user with the Merchant admin role should:

1.  Go to the **My team** section.
2.  Open the tab of the target user account by clicking the ![](images/universal/dbl/icon_pencil.svg) button in the corresponding row of the registry.
3.  Check the box **Manage API tokens** and click the **Save changes** buttonthereby confirming the changes that were made.

    ![](images/ecommpay/dbl/en_dbl_user_api.svg)

4.  Make sure that the appropriate permissions were granted: the user account tab should now have the box **Manage API tokens** checked.

To withdraw the right to manage tokens, the user should go to **My team** section, open the tab of the target user account, uncheck the box **Manage API tokens**, save changes and make sure that they have been applied. In this case, the permission to generate a new token and to deactivate the token which is currently valid is no longer available for this user account; however, the permission to use the valid one remains available.

### Generating and deactivating tokens {#section_r3q_gnb_tmb .section}

Generating and deactivating tokens is available only for the user accounts authorized to manage tokens.

To generate a token and a secret key, the user whose user account has the appropriate permissions should:

1.  Go to the **My profile** sectionby clicking the user account name on the right in the main menu of the interface and selecting **My profile**.
2.  Click the **New token** button on the **API Tokens** panel.

    If the **New token** button is absent, it means that this user account was not granted the permission to manage tokens.

3.  Copy and save the value of the token and the secret key in accordance with the internal informational security guidelines of the merchant.

    **Note:** The secret key is displayed explicitly only until the page is updated following which it gets hidden and is no longer available. If necessary, when the secret key was lost or compromised, for example, a new token-key pair should be generated.


To deactivate a token, in the user account profile the user should click the **Delete** button on the **API Tokens** panel. Afterwards, the token is no longer valid and cannot be used to access the Data API.

## Request format {#en_dbl_request_format}

### Overview {#section_tw5_bf1_xmb .section}

To interact with the payment platform via the Data API, all data from the merchant's web service must be passed in *requests*—HTTP messages in a specific format—using the POST method. This section covers the general structure of such requests; for the information about the data structure of the specific requests, see the [Data API Specification](https://api-data.ecommpay.com/).

### Structure {#section_oyr_nmh_smb .section}

Each HTTP request to the payment platform must include the following elements in the specified order:

-   The start line which indicates the HTTP method of the request \(`POST)`, the endpoint in the Data API \(for example, `v1/operations/get` \), the protocol and its version \(`HTTP/1.1`\).
-   The header with the `Host` field which contains the domain name of the Data API \(`data.ecommpay.com/v1`\).
-   An empty line which serves as a separator between the message header and the body.
-   The message body which contains the JSON string encoded in UTF-8 with request data including the signature.

In addition to the mandatory `Host` field, the header may include any other fields supported by [HTTP version 1.1](https://tools.ietf.org/html/rfc2616#page-31). Below you will find a sample HTTP request with the recommended header fields and required parameters. The JSON string is formatted for better readability.

```
POST v1/balance/get HTTP/1.1
User-Agent: curl/7.29.0
Host: data.ecommpay.com/v1
Accept: */*
Content-Length: 179
Content-Type: application/x-www-form-urlencoded
                    
{
    "token":"ZOyTL5shY8...dQyplRPJYmGV7Kv",
    "signature":"...dQcIbv94Z0nPTYX9s2XqYrY9bzkfcBGQ==..."
}                
```

### Addressing parameters {#section_b3q_bsx_thb .section}

The generated requests must include the base and the relative URLs. The base URL for the Data API requests is the domain name `data.ecommpay.com/v1`, and the relative URL is the path to the target endpoint in the interface according to the specification.

**Note:** The absolute URL in this case takes the following format `https://{domain name for the Data API requests}/{target endpoint path}`. For example, the absolute URL for the request to retrieve balance information on merchant's projects is `https://data.ecommpay.com/v1/v1/balance/get`. However, absolute URLs are not used for generating POST requests.

### Message body {#section_kdx_ptx_thb .section}

The message body must contain the request data in the JSON format. The JSON string follows the format `"<parameter name>": <parameter value>`.To prevent data loss as a result of spillage or spoofing when data is transferred to the payment platform, the JSON string must include the token and the signature with the request data, and the TLS 1.2 encryption protocol must be used to secure the data transfer. For more information about generating tokens, see [Data access model](en_dbl_api_interaction.md), and to learn more about generating a signature, see [Signature generation and verification](en_platform_signature.md).

## Response format {#en_dbl_response_format}

### Overview {#section_e4m_cg1_xmb .section}

The Ecommpay payment platform responds with an HTTP *response* message to each request within one HTTP session. The requested data of the response body includes:

-   The requested information, if the the request was accepted and executed.
-   The information about the error that occurred, if the request cannot be handled.

This section covers the general structure of such responses as well as codes used for communicating the request status. For the information about the data structure of responses to specific requests, see the [Data API specification](https://api-data.ecommpay.com/).

### Structure {#section_c2t_tbm_xhb .section}

Each HTTP response includes the following elements listed in the order they appear:

-   The status line which indicates the protocol and its version \(`HTTP/1.1`\), the response status code and the reason phrase \(for example, `200 OK`\).
-   Header fields.
-   An empty line which serves as a separator between the message header and the body.
-   The message body which contains the JSON string encoded in UTF-8 with the response data.

### Status codes {#section_aj3_knq_13b .section}

HTTP status codes are used in the status line of each response to state the result of the request acceptance and execution or the cause of the error that occurred. In case of the Data API, the following status codes and reason phrases are used.

|Status code with the reason phrase|Description|
|----------------------------------|-----------|
|200 OK|The request has been successfully executed. The response body contains the requested data.|
|400 Bad Request|The request cannot be accepted due to invalid syntax or the absence of the mandatory parameter in the JSON string \(except for the token and signature\).|
|401 Authorization Required|The request cannot be accepted due to failed authentication, for example, if the token or signature was incorrect in the request, or the request included the project ID which cannot be accessed via the token currently in use.|
|429 Too Many Requests|The request cannot be accepted due to exceeding the rate limit for requests sent from a single Dashboard user account. In this case, you should wait for at least three seconds before resending the request. To prevent such situations, make sure not to exceed the recommended limit of 60 requests per minute for a single Dashboard user account.|
|500 Internal Error|The request cannot be processed due to the payment platform error.|

### Error description {#section_gxv_5mh_smb .section}

If the request contained an error, then the status line indicates the response status code with the cause of the error \(in the example below it is `401 Authorization Required`\), while the message body contains the extended description of this error:

-   An explanatory phrase for the response header in the `name` parameter \(in the example—`Authorization Required`\).
-   Description of the error in the `message` parameter \(if the error has been processed in the plaform; in the example—`You have no access to project_id = 22`\).
-   The service code in the `code` parameter with the fixed value of `0`.
-   The code from the response header in the `status` parameter \(in the example, `401`\).

```
POST /v1/balance/get HTTP/1.1         // Request from the web service to retrieve balances
                    
HTTP/1.1 400 Bad Request                 //  Response from the payment platform
Server: nginx/1.14.2
Date: Thu, 17 August 2020 10:21:45 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 17 August 2020 10:21:45 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,
User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"name":"Bad Request",
	"message":"You have no access to project_id = 22",
	"code":"0",
	"status":"400"
}
```



---

# Retrieving data {#en_dbl_using_api}

An article about working with individual endpoints in the Data API, with the description of data structures and examples of requests and responses.

**Parent topic:**[Using Data API](en_dbl_api_protocol.md)

## Overview {#en_dbl_using_api_overview}

The following endpoints in the Data API are used to retrieve data:

-   `[/balance/get](en_dbl_using_api.md)`—to retrieve balance information \(currently available only for OUT balances\)
-   `[/chargeback/list](en_dbl_using_api.md)`—to retrieve chargeback information filtered by specified conditions
-   `[/chargeback/get](en_dbl_using_api.md)`—to retrieve information about a single chargeback
-   `[/fraud/list](en_dbl_using_api.md)`—to retrieve information about operations flagged as fraudulent
-   `[/financial-reporting/operations](en_dbl_using_api.md)`—to retrieve itemised operation data for financial reporting \(including charged fees\) for a specified time period
-   `[/operations/get](en_dbl_using_api.md)`—to retrieve itemised operation data for a specified time period
-   `[/operations/get-by-payment](en_dbl_using_api.md)`—to retrieve information about operations initiated within a specific payment

The general procedure of sending requests to any of these endpoints is the same as described in previous articles of this section. This article covers special aspects of using these requests and complements the description of data structures in the interface specification.

## Retrieving balance data {#en_dbl_using_api_balances}

Requests to retrieve balance information on the merchant's projects should be sent to the [/balance/get](https://api-data.ecommpay.com/balance/post-balance-get) endpoint.

These requests must contain parameters `token` \(a token associated with the specific Dashboard user account\) and `signature` \([details](en_platform_signature.md)\). Responses to such requests contain information about the current state of OUT balances.

Information about each balance includes the balance type and the available total sum in this balance's currency. The currency is specified in the name of the parameter and the sum is passed as its value \(`"<currency>": "<sum>"`\).

```language-json
// Request body
{
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ=="
}

// Response body
{
    "balance": [
        {
            "name": "Project_Cosmo1_balance_AUD",
            "AUD": "1010750"
        },
        {
            "name": "Project_Cosmo1_balance_USD",
            "USD": "310099"
        },
        {
            "name": "Project_Cosmo1_balance_EUR",
            "EUR": "113128"
        }
    ],
    "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w=="
}
```

## Retrieving chargeback data {#en_dbl_using_api_chargeback_list}

Requests to retrieve chargeback information filtered by specified conditions should be sent to the [/chargeback/list](https://api-data.ecommpay.com/chargeback/post-chargeback-list) endpoint.

When sending such requests, consider the following:

1.  These requests must contain parameters `token` \(a token associated with the specific Dashboard user account with the `Risks` or `Merchant Admin` role and with the access rights to certain projects of the merchant\) and `signature` \([details](en_platform_signature.md)\).
2.  To filter information about chargebacks by different parameters, use the `filter` object.

    In the `filter` object, any date range must be an object defined by `from`and `to`string parameters. The rest of parameters can be an array of one or more values or a string of values separated with a comma and a space \(`provider_id` can be only an array\). Parameters in the `filter`object can be listed in an arbitrary order. By default, if the request does not contain these parameters, the payment platform returns chargeback information on all of the projects that can be accessed with the use of the token.

    The filter object can include the following objects and parameters:

    -   `report_date—`a date range with date values in the format "YYYY-MM-DD"; refers to the time when the information about the chargeback was received in the payment platform
    -   `respond_by`—the deadline for submitting a response to the chargeback \(must be specified as a date range with date values in the format "YYYY-MM-DD HH-MM-SS" where time can be skipped\)
    -   `chb_completed_at`—the date when the chargeback received one of the final statuses \(must be specified as a date range with date values in the format "YYYY-MM-DD HH-MM-SS" where time can be skipped\)
    -   `project_id`—project ID provided by Ecommpay
    -   `chargeback_id`—chargeback ID provided by Ecommpay
    -   `chargeback_stage`—chargeback stage \(`Chargeback`, `Representment`, `Pre-Arbitration attempt`, `Pre-Arbitration response`, or `Arbitration`; [details](en_faq_chargebacks.md#section_ppz_lhs_q5b)\)
    -   `arn`—acquirer reference number used for clearing
    -   `card`—card number used by the customer to make the disputed payment
    -   `card_type`—the code of the payment system \(`visa` for Visa and `mc` for Mastercard\);
    -   `reason_code`—numerical chargeback reason code provided by the payment system
    -   `operation_id`—ID of the disputed operation provided by Ecommpay
    -   `status`—current status of the chargeback
3.  To restrict the number of chargebacks the information about which is returned in a single response, use the `pagination` object with two parameters: `limit` and `offset`. The `limit` parameter is used to set the number of the returned operations in the response \(more than 1\). The `offset parameter` is used to retrieve the subset of chargebacks beginning with the number that follows the `offset` value \(counting starts from 0\). For example, if you need to retrieve information about chargebacks 21-25, you should set `"limit": 5` and `"offset": 20` in the request. If these parameters are absent, the default values are 20 for `limit` and 0 for `offset.`

Responses to such requests contain chargeback data with the consideration of the conditions determined in the request.

```language-json
// Body of the request:
{
    "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
    "filter": {
        "report_date": {
            "from": "2024-01-01",
            "to": "2024-02-01"
        },
        "status": [
            "WON",
            "PARTIALLY WON"
        ]
    },
    "signature": "DNqOZOCxNlXu3bENrDPuEE8fSJLWDNM/CE8Xjj9...VcNFw=="
}

// Body of the response:{
  "operations": [
    {
      "chargeback_id": "11201",
      "charged_amount": "5000",
      "channel_amount": "5000",
      "case_id": "142",
      "project_id": "1234",
      "operation_id": "12330123485431",
      "report_date": "2024-01-31",
      "respond_by": "2024-02-04 23:59:59",
      "rev_date": null,
      "tr_date_time": "2024-01-13 17:00:56",
      "chb_completed_at": "2024-02-21 00:00:00",
      "chb_amount": "50.00",
      "chb_settlement_amount": "50.00",
      "rev_indicator": null,
      "chb_ccy": "USD",
      "chb_settlement_ccy": "USD",
      "charged_currency": "USD",
      "channel_currency": "USD",
      "eci_sli": "7",
      "reason_code": "10.4",
      "card_type": "VISA",
      "merchant_id": "10000123",
      "card": "431422******0056",
      "arn": "74312342013012340041234",
      "status": "WON",
      "chb_amount_in_usd": "50.0000",
      "merchant_name": "Cosmoshop_on_Mars",
      "order_id": "1234123412345",
      "operation_type": "sale",
      "auth_code": "061230",
      "card_holder": "JANE DOE",
      "issuer_country": "UK",
      "chargeback_stage": "Arbitration",
      "pre_arbitration_report_date": "2024-02-06",
      "pre_arbitration_amount": "50.00",
      "pre_arbitration_ccy": "USD",
      "arbitration_report_date": "2024-03-06",
      "arbitration_amount": "50.00",
      "arbitration_ccy": "USD",
      "representment_amount": "50.00",
      "representment_ccy": "USD"
    },
    ...
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}
```

## Retrieving single chargeback data {#en_dbl_using_api_chargeback_get}

A request to retrieve single chargeback information should be sent to the [/chargeback/get](https://api-data.ecommpay.com/chargeback/post-chargeback-get) endpoint.

When sending such requests, consider the following:

1.  The request must contain parameters `token` \(a token associated with the specific Dashboard user account with the `Risks` or `Merchant Admin` role and with the access rights to certain projects of the merchant\) and `signature` \([details](en_platform_signature.md)\).
2.  The request must contain one of the following identifiers in the `filter` object:
    -   `chargeback_id`—chargeback ID provided by Ecommpay
    -   `arn`—acquirer reference number used for clearing
    -   `operation_id`—operation ID provided by Ecommpay

The response to such request contains information about the required chargeback.

```language-json
// Body of the request:
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "filter": {
        "operation_id": 87980010093051
    },
  "signature": "VoOJxpMge0uBN22gZxf3BhE+5wlCaU...y+KM1lQ=="
}

// Body of the response:

{
  "chargeback": {
    "chargeback_id": "11201",
    "charged_amount": "5000",
    "channel_amount": "5000",
    "case_id": "142",
    "project_id": "1234",
    "operation_id": "12330123485431",
    "report_date": "2024-01-31",
    "respond_by": "2024-02-04 23:59:59",
    "rev_date": null,
    "tr_date_time": "2024-01-13 17:00:56",
    "chb_completed_at": "2024-02-21 00:00:00",
    "chb_amount": "50.00",
    "chb_settlement_amount": "50.00",
    "rev_indicator": null,
    "chb_ccy": "USD",
    "chb_settlement_ccy": "USD",
    "charged_currency": "USD",
    "channel_currency": "USD",
    "eci_sli": "7",
    "reason_code": "10.4",
    "card_type": "VISA",
    "merchant_id": "10000123",
    "card": "431422******0056",
    "arn": "74312342013012340041234",
    "status": "WON",
    "chb_amount_in_usd": "50.00",
    "merchant_name": "Cosmoshop_on_Mars",
    "order_id": "1234123412345",
    "operation_type": "sale",
    "auth_code": "061230",
    "card_holder": "JANE DOE",
    "issuer_country": "UK",
    "chargeback_stage": "Arbitration",
    "pre_arbitration_report_date": "2024-02-06",
    "pre_arbitration_amount": "50.00",
    "pre_arbitration_ccy": "USD",
    "arbitration_report_date": "2024-03-06",
    "arbitration_amount": "50.00",
    "arbitration_ccy": "USD",
    "representment_amount": "50.00",
    "representment_ccy": "USD"
  },
  "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhDr...gtmmKfB2g=="
}
```

## Retrieving fraudulent operations data {#en_dbl_using_api_fraud}

A request to retrieve information about operations flagged as fraudulent by payment systems should be sent to the [/fraud/list](https://api-data.ecommpay.com/fraud/post-fraud-list) endpoint \(information about operations flagged as fraudulent by Ecommpay is not provided in the response to this request\).

When sending such requests, consider the following:

1.  The request must contain parameters `token` \(a token associated with the specific Dashboard user account with the `Risks` or `Merchant Admin` role and with the access rights to certain projects of the merchant\) and `signature` \([details](en_platform_signature.md)\).
2.  The request may contain the `filter` object with any of the following parameters:

    -   `received_on`—timeframe within which the payment platform registered the information that the card network reported the operation as fraudulent
    -   `purchase_date`—timeframe within which the operation was completed
    -   `fraud_report_date`—timeframe within which the operation was reported as fraudulent to the issuer
    -   `issuer_country`—country code of the card issuer \(an array of one or more codes specified in the ISO 3166-1 alpha-2 format\)
    -   `has_chargebacks`—indicator that specifies if at least one chargeback was registered in the payment platform for the operation deemed fraudulent
    -   `customer_id`—identifier of the customer in the merchant’s project
    -   `card_type`—code identifying the card network \(`mc` for Mastercard and `visa` for Visa\)
    The date range in this `filter` object must contain start and end dates and must be specified as a string array, for example, `"purchase_date": ["2025-12-31 00:00:00", "2026-01-07 23:59:59"]`.

3.  To restrict the number of operations the information about which is returned in a single response, use the `pagination` object with two parameters: `limit` and `offset`. The `limit` parameter is used to set the number of the returned operations in the response \(more than 1\). The `offset parameter`is used to retrieve the subset of operations beginning with the number that follows the `offset` value \(counting starts from 0\). For example, if you need to retrieve information about fraudulent operations 21-25, you should set `"limit": 5` and `"offset": 20` in the request. If these parameters are absent, the default values are 20 for `limit` and 0 for `offset`.

Responses to such requests contain operation data filtered by the conditions determined in the request.

```language-json
// Body of the request:
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "signature": "dfsder34fuk7sJ...grdfht5gJg==",
  "filter": {
    "received_on": [
      "2026-01-01 00:00:00",
      "2026-02-01 23:59:59"
    ],
    "issuer_country": [
      "GB"
    ]
  },
  "pagination": {
    "limit": 5,
    "offset": 20
  }
}

// Body of the response:{
  "operations": [
    {
      "payment_id": "cosmopayment78",
      "operation_id": 6435212169999,
      "tr_amount": "580.00",
      "tr_ccy": "USD",
      "account_number": "431422******0056",
      "payment_method_type": "visa",
      "row_updated_at": "2024-01-01 05:30:30",
      "customer_id": "earthling1232400",
      "project_name": "cosmoshop.earth",
      "project_id": "123",
      "arn": "40216364365007272011473",
      "fraud_type": "6",
      "fraud_report_date": "2024-02-10",
      "issuer_country": "GB",
      "received_on": "2024-02-11",
      "purchase_date": "2024-02-01",
      "channel_amount_in_usd": "580.00",
      "issuer_bank_name": "Intergalactic Bank",
      "bin": "123456",
      "country_by_ip": "GB",
      "customer_email": "earthling@earth.earth",
      "report_and_purchase_date_difference": 9
    }
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}
```

## Retrieving itemised operation data for financial reporting {#en_dbl_using_api_financial-statements}

Requests to retrieve itemised operation data for financial reporting \(including charged fees\) for a specified time period should be sent to the [/financial-reporting/operations](https://api-data.ecommpay.com/operations/post-financial-reporting-operations) endpoint.This information can complement the operation data retrieved for general purposes \([details](en_dbl_using_api.md)\) and used for final analysis and reconciliation.

When sending a request to retrieve itemised operation data for financial reporting, consider the following:

1.  The request must contain the following objects and parameters:
    -   `token`—a token associated with the specific Dashboard user account
    -   `signature`—a request signature generated after all required parameters have been specified \([details](en_platform_signature.md)\)
    -   `operation_completed_at`—an object that defines the time period over which the required operations were finalised \(with the most recent actions and updates taken into consideration\):

        -   `from`—start date and time of the interval, in the `YYYY-MM-DD hh:mm:ss` format
        -   `to`—end date and time of the interval, in the `YYYY-MM-DD hh:mm:ss` format
        **Note:** You can only request data about operations completed in the payment platform within the last 30 days.

    -   `tz`—time zonespecified in the UTC offsets format \(for example, `+10:30`\) or in the IANA Time Zone Database format \(for example, `Asia/Singapore`\).
2.  To filter operations by projects and/or providers, use the `project_id` and `provider_id` arrays.Keep in mind that the access rights associated with the token passed in the request also factor in what data is going to be returned. By default, if the request does not contain these arrays, the payment platform returns operation information on all of the projects \(which can be accessed with the use of the token\) and on all of the providers involved in performing these operations. If you need operation data for specific projects and providers, specify their identifiers in the `project_id` and `provider_id` arrays \(separated with a comma and a space: for example, `4, 12`\).
3.  To filter operation data by operation identifiers, use the `operation_id` array.By default, if the request does not contain this array, the payment platform returns itemised data for all operations that otherwise meet the query criteria. If you need operation data for specific operations, pass their identifiers in the `operation_id` array \(separated with a comma and a space: for example, `6435212162442, 6435212162443`\).
4.  To restrict the number of operations information about which is returned in a single response, use the `limit` parameter. This parameter can take a value between `0` and `1000`. By default, it is set to `1000`, while the number of the returned operations in the response can be lower than the specified value.

    If you need information about more than one thousand operations, send multiple requests with the `offset` parameter specified in each. This parameter determines the offset value for selecting operations. When both the `limit` and `offset` parameters are passed in the request, then the number of the operations that equals the value of the `offset` parameter is skipped, and the remaining number of operations returned in the response does not exceed the value of the `limit` parameter.

    For example, if you need to retrieve operation data on `1125` operations, then you can specify the following values for the `limit` and `offset` parameters in the requests: `"limit": 1000` and `"offset": 0` in the first one, `"limit": 125` and `"offset": 1000` in the second one.


Responses to such requests contain operation data for a specified time period, retrieved according to the request criteria.

```language-json
// Body of the request to retrieve data on 1000 operations (starting from 0)  
{
  "project_id": [11],
  "operation_completed_at": {
    "from": "2024-09-01 00:00:00",
    "to": "2024-09-30 23:59:59"
  },
  "tz": "Indian/Mauritius",
  "limit": 1000,
  "offset": 0,
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "YsrkgdBr5peXJgJ...glVmsd0f=="
}

// Body of the response 
 
{
  "data": [
    {
      "operation_completed_at": "2024-09-29T22:08:19+0000",
      "transaction_id": "81194009089601",
      "operation_id": "81194009122865",
      "provider_payment_id": "0040000028207224",
      "payment_id": "1994-1312",
      "arn": "70114165164100000032105",
      "rrn": "451912040334",
      "auth_appr_code": "611887",
      "operation_type": "sale",
      "operation_status": "success",
      "tran_region": "domestic",
      "tariff_region": "EU",
      "proc_region": "Visa Europe",
      "security_level": "SEC",
      "operation_amount": 2098.00,
      "operation_currency": "GBP",
      "billing_conversion_rate": 0.00,
      "billing_amount": 2098.00,
      "billing_currency": "GBP",
      "total_interchange_fee": -4.20,
      "total_scheme_fee": -0.64,
      "auth_msc_fee": 0.000000,
      "clearing_msc_fee": -3.785649,
      "total_msc_fee": -3.78,
      "hold_amount": 0.00,
      "project_id": 11,
      "project_url": "https://www.company.com",
      "merchant_name": "COMPANY NAME",
      "mid": "70000000",
      "terminal_id": "70000000",
      "mcc_code": "4722",
      "legal_country": "GB",
      "payment_method_name": "visa",
      "product_type": "Consumer",
      "account_funding_source": "debit",
      "account_number": "475144******1111",
      "card_product": "Visa classic",
      "issuer_country": "GB",
      "customer_id": "1436462",
      "card_holder": "CARD HOLDER"
    },
    // information about other operations...
  ],  
  "signature": "sncpEB75H...3jTS=="
}
```

## Retrieving itemised operation data for general purposes {#en_dbl_using_api_operations}

Requests to retrieve itemised operation data for a specified time period should be sent to the [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get) endpoint.You can use this information for monitoring your operations and their technical analysis. To obtain accurate financial information that can be used for final analysis and reconciliation, retrieve itemised operation data for financial reporting \(including charged fees; [details](en_dbl_using_api.md)\).

When sending a request to retrieve operation data for general purposes, consider the following:

1.  The request must contain the following objects and parameters:
    -   `token`—a token associated with the specific Dashboard user account
    -   `signature`—a request signature generated after all required parameters have been specified \([details](en_platform_signature.md)\)
    -   `interval`—an object that defines the time period over which the required operations were finalised \(with the most recent actions and updates taken into consideration\):

        -   `from`—start date and time of the interval, in the `YYYY-MM-DD hh:mm:ss` format
        -   `to`—end date and time of the interval, in the `YYYY-MM-DD hh:mm:ss` format
        **Note:** If more than one request is received in the platform from a single Dashboard user account within 10 seconds, and the value of the `interval` parameter specified in the requests exceeds 180 days, these requests are processed one by one, with 10 second delay.

2.  To filter operations by project, use the `project_id` array.Keep in mind that the access rights associated with the token passed in the request also factor in what data is going to be returned. By default, if the request does not contain this array, the payment platform returns operation information on all of the projects which can be accessed with the use of the token. If you need operation data for specific projects, specify the identifiers of these projects in the `project_id` array \(separated with a comma and a space if more than one identifier needed: for example, `4, 12`\).
3.  To specify a time zone different from the default time zone, use the `tz` parameter.If the request does not contain this parameter, the default is the time zone of the Dashboard user account associated with the token from the `token` parameter. The time zone specified with the help of this parameter affects what operations will be selected for the time period specified in the `interval` object and the format of the date and time parameters in the response—for example, `operation_created_at` and `operation_completed_at`. In the `tz` parameter, the time zone is specified in the UTC offsets format \(for example, `+10:30`\) or in the IANA Time Zone Database format \(for example, `Asia/Singapore`\).
4.  To restrict the number of operations information about which is returned in a single response, use the `limit` parameter. This parameter can take a value between `0` and `1000`. By default, it is set to `1000`, while the number of the returned operations in the response can be lower than the specified value.

    If you need information about more than one thousand operations, send multiple requests with the `offset` parameter specified in each. This parameter determines the offset value for selecting operations. When both the `limit` and `offset` parameters are passed in the request, then the number of the operations that equals the value of the `offset` parameter is skipped, and the remaining number of operations returned in the response does not exceed the value of the `limit` parameter.

    For example, if you need to retrieve operation data on `1125` operations, then you can specify the following values for the `limit` and `offset` parameters in the requests: `"limit": 1000` and `"offset": 0` in the first one, `"limit": 125` and `"offset": 1000` in the second one.

5.  If you need to retrieve specific operation data parameters, use the `fields` array. If the request does not contain this array, the payment platform returns the default set of data for each operation. For a customised set of data, pass the names of parameters you need in the `fields` array.

    The names of parameters in the array are separated with a comma and a space \(if you need more than one\) and can be listed in an arbitrary order. However, the order in which the data are listed in responses is fixed. The full list of parameters can be found in the specification: see the list of parameters in the `operations` object included in the format description of the response to the request sent to the [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get) endpoint. In this description, the parameters are listed in the fixed order that cannot be customised in responses. The parameters included in the default set of data are marked as required.

6.  To retrieve operation data by certain operation types and/or statuses, use the `operation_type` and `operation_status` parameters.By default, if the request does not contain these parameters, the payment platform returns operation data for all operation types and statuses. If you use these parameters, specify operation types and statuses that you need and separate multiple values within the arrays by a comma with a space if necessary. The comprehensive list of operation types and statuses can be found in [Payment processing](en_platform_payment_model.md).

    The `operation_type` and `operation_status` parameters can be passed as strings \(if you need to pass a single value\) and as arrays \(if you need to pass one or more values\).

7.  To filter operation data by customer identifiers and/or customer emails, use the `customer_id` and `customer_email` parameters.By default, if the request does not contain these parameters, the payment platform returns itemised data for all operations that otherwise meet the query criteria. The `customer_id` parameter can be passed as a string \(if you need to pass a single value\) and as an array \(if you need to pass one or more values\), and the `customer_email` parameter can only be passed as a string.


Responses to such requests contain operation data for a specified time period, retrieved according to the request criteria.

If the default set of parameters returned in responses is enough, there is no need to pass the `fields` array in the requests.

```language-json
// Body of the request to retrieve data on 1000 operations (starting from 0) 
{
  "project_id":[
    0,
    1
  ],
  "interval": {
    "from":"2024-04-04 00:00:00",
    "to":"2024-04-28 23:59:59"
  },
  "limit": 1000,
  "offset": 0,
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"yPu0wYr2BoV5...MzQtRkvdC0y=="
}

// Body of the request to retrieve data on subsequent 125 operations (starting from 1000)
{
  "project_id":[
    0,
    12
  ],
  "interval": {
    "from":"2024-04-04 00:00:00",
    "to":"2024-04-28 23:59:59"
  },
  "limit": 125,
  "offset": 1000,
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"sd0fr5YsdBVmJ...grkglpeXJg=="
}

// Body of the response to the first request
{
    "operations": [
        // information about an operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "192.0.2.255",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",            
            "provider_date": "2024-04-04 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "12304191169003210000234",
            "rrn": "001045563840",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },

        // information about another operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "198.51.100.0",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",
            "provider_date": "2024-04-04 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "30407191169003210010678",
            "rrn": "128905563823",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },
        // information about the rest of the operations
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}
```

If you need to customise the default set of data retrieved for each operation, you can specify the required parameters in the `fields` array. If, in addition, you need to filter operation data, specify filtering criteria by using such parameters as `operation_type`, `operation_status`, and `customer_email`.

```language-json
// Body of the request:
{
    "project_id":[
        0,
        11
    ],
    "interval": {
        "from":"2024-04-04 00:00:00",
        "to":"2024-04-19 23:59:59"
    },
    "operation_type": [
        "sale",
        "refund"
    ],
    "operation_status": [
        "success",
        "decline"
    ],
    "customer_email": "astronaut@earth.station",
    "token":"qOnHY86dfhpxdghEBb7HSLbe",
    "fields": [
        "operation_id",
        "operation_type",    
        "operation_status",
        "sum_initial.amount",
        "sum_initial.currency",
        "customer_email"
    ],
    "signature":"vtv5TN6aWQV...5QBjpe8Dsv=="
}

// Body of the response:

{
    "operations": [
    // information about an operation
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "astronaut@earth.station"
    },
    // information about other operations ...
    ],
    "signature": "sdf45rt73jncpEB75HTS=="
}

```

## Retrieving data on operations initiated within a specific payment {#en_dbl_using_api_operations_by_payment}

Requests to retrieve information about all operations initiated within a specific payment should be sent to the [/operations/get-by-payment](https://api-data.ecommpay.com/operations/post-operations-get-by-payment) endpoint.

These requests must contain parameters `payment_id` \(ID of the target payment\), `token` \(a token associated with the specific Dashboard user account\), and `signature` \([details](en_platform_signature.md)\). Responses to such requests contain information about the operations initiated within the target payment.

```language-json
// Request body
{
  "payment_id":"PID_25467851461-2147",
  "token":"VmJQhaXILAnZWTKmqwSd3j",
  signature":"JM+YWmTL7uGn26IgZWT...yaq030+eNXVtJjjtgrkglpeXJg=="
}

// Response body
{
  "operations": [
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:13:04+00:00",
      "operation_type": "refund",
      "operation_id": "2747253065470",
      "amount": 221,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:13:04+00:00",
      "rrn": "803817399309",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "201924-11-22T13:09:03+00:00",
      "operation_type": "capture",
      "operation_id": "2747253065469",
      "amount": 1621,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:09:03+00:00",
      "rrn": "000000248370",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:06:40+00:00",
      "operation_type": "auth",
      "operation_id": "2747253065468",
      "amount": 200,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:06:38+00:00",
      "rrn": "000047769105",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7b...y1WihDJ4ljz/Hv7NkQFujSnvw=="
}
```



---

# Data API {#data_api}
**Up one level:**[Using Data API](en_dbl_api_protocol.md)

{
    "swagger": "2.0",
    "info": {
        "version": "2.1.1",
        "title": "Data API",
        "description": "Ecommpay Data API is an interface for retrieving information about merchant operations in the payment platform."
    },
    "host": "data.ecommpay.com",
    "basePath": "/v1",
    "schemes": [
        "https"
    ],
    "paths": {
        "/balance/get": {
            "post": {
                "operationId": "POST_balance-get",
                "summary": "/balance/get",
                "tags": [
                    "Balance"
                ],
                "description": "Request to retrieve merchant contracts balances.",
                "consumes": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "Token generated by Ecommpay Dashboard for user account."
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                }
                            },
                            "required": [
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "application/json": {
                                "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
                                "signature": "dQcIbv94Z0nPTYX9glSCi...jqInXYrY9zkfcBGQ=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/ApiBalanceList"
                        },
                        "examples": {
                            "application/json": {
                                "balance": [
                                    {
                                        "name": "Project_Cosmo1_balance_USD",
                                        "USD": "1010750"
                                    },
                                    {
                                        "name": "Project_Cosmo1_balance_SGD",
                                        "SGD": "310099"
                                    },
                                    {
                                        "name": "Project_Cosmo1_balance_EUR",
                                        "EUR": "113128"
                                    }
                                ],
                                "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w=="
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        },
        "/chargeback/get": {
            "post": {
                "operationId": "POST_chargeback_get",
                "summary": "/chargeback/get",
                "tags": [
                    "Chargeback"
                ],
                "description": "Request to retrieve a single chargeback data.",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "Token generated in the Ecommpay Dashboard for the user account."
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                },
                                "filter": {
                                    "type": "object",
                                    "description": "Object used for finding a chargeback by various identifiers. The request must contain one of the following identifiers.",
                                    "properties": {
                                        "chargeback_id": {
                                            "type": "integer",
                                            "description": "Chargeback ID provided by Ecommpay."
                                        },
                                        "arn": {
                                            "type": "string",
                                            "description": "Acquirer reference number used for clearing."
                                        },
                                        "operation_id": {
                                            "type": "integer",
                                            "description": "Operation ID provided by Ecommpay."
                                        }
                                    }
                                }
                            },
                            "required": [
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "example-1": {
                                "token": "r8u26__LapNUP5rPIiOuVaMFiwPWI3",
                                "chargeback_id": 11201,
                                "arn": "74312342013012340041234",
                                "operation_id": 1234123412345,
                                "signature": "DNqOZOCxNlXu3bENrDPuEE8...fSJLWDNM/CE8=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "signature": {
                                    "type": "string"
                                },
                                "chargeback": {
                                    "$ref": "#/definitions/Chargeback"
                                }
                            }
                        },
                        "examples": {
                            "example-1": {
                                "chargeback": {
                                    "chargeback_id": "11201",
                                    "charged_amount": "50.00",
                                    "channel_amount": "50.00",
                                    "case_id": "142",
                                    "project_id": "1234",
                                    "operation_id": "12330123485431",
                                    "report_date": "2024-01-31",
                                    "respond_by": "2024-02-04 23:59:59",
                                    "rev_date": "null",
                                    "tr_date_time": "2024-01-13 17:00:56",
                                    "chb_completed_at": "2024-02-21 00:00:00",
                                    "chb_amount": "50.00",
                                    "chb_settlement_amount": "50.00",
                                    "rev_indicator": "null",
                                    "chb_ccy": "USD",
                                    "chb_settlement_ccy": "USD",
                                    "charged_currency": "USD",
                                    "channel_currency": "USD",
                                    "eci_sli": "7",
                                    "reason_code": "10.4",
                                    "card_type": "VISA",
                                    "merchant_id": "10000123",
                                    "card": "431422******0056",
                                    "arn": "74312342013012340041234",
                                    "status": "string",
                                    "chb_amount_in_usd": "WON",
                                    "merchant_name": "Cosmoshop_on_Mars",
                                    "order_id": "1234123412345",
                                    "operation_type": "sale",
                                    "auth_code": "061230",
                                    "card_holder": "JANE DOE",
                                    "issuer_country": "UK",
                                    "chargeback_stage": "Arbitration",
                                    "pre_arbitration_report_date": "2024-02-06",
                                    "pre_arbitration_amount": "50.00",
                                    "pre_arbitration_ccy": "USD",
                                    "arbitration_report_date": "2024-03-06",
                                    "arbitration_amount": "50.00",
                                    "arbitration_ccy": "USD",
                                    "representment_amount": "50.00",
                                    "representment_ccy": "USD"
                                },
                                "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhdDrzx10vzg/gtmmKfB2g=="
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        },
        "/chargeback/list": {
            "post": {
                "operationId": "POST_chargeback_list",
                "summary": "/chargeback/list",
                "tags": [
                    "Chargeback"
                ],
                "description": "Request to retrieve the list of chargebacks.",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "Token generated in the Ecommpay Dashboard for the user account.\t"
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                },
                                "filter": {
                                    "type": "object",
                                    "description": "Object used for filtering chargeback data by various parameters.\n\nThe first three parameters are specified as time intervals and refer to different dates. The report_date parameter specifies the date when the chargeback was registered in the payment platform (format: \"YYYY-MM-DD\"). The respond_by parameter specifies the deadline for submitting a response to the chargeback (format: \"YYYY-MM-DD HH-MM-SS\"). The chb_completed_at parameter specifies the date when the chargeback received one of the final statuses (format: \"YYYY-MM-DD HH-MM-SS\").\n\nThe rest of the parameters can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value). If the array is omitted, the payment platform returns information for all available values.",
                                    "properties": {
                                        "report_date": {
                                            "$ref": "#/definitions/DateRange"
                                        },
                                        "respond_by": {
                                            "$ref": "#/definitions/DateRange"
                                        },
                                        "chb_completed_at": {
                                            "$ref": "#/definitions/DateRange"
                                        },
                                        "project_id": {
                                            "type": "array",
                                            "description": "One or more project IDs provided by Ecommpay.",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "chargeback_id": {
                                            "description": "Chargeback ID (as a string) or an array of one or more chargeback IDs.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "chargeback_stage": {
                                            "description": "Chargeback stage (as a string) or an array of one or more chargeback stages.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "arn": {
                                            "description": "ARN (as a string) or an array of one or more ARNs. Acquirer reference number used for clearing.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "card": {
                                            "description": "Card number (as a string) or an array of one or more card numbers used by the customers.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "card_type": {
                                            "description": "Bank card type (as a string) or an array of one or more bank card types.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "reason_code": {
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "description": "Numerical chargeback reason code (as a string) or an array of one or more reason codes.",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "operation_id": {
                                            "description": "Disputed operation ID provided by Ecommpay or an array of one or more IDs.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "status": {
                                            "description": "Current status of the chargeback (as a string) or an array of one or more statuses.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "pagination": {
                                    "type": "object",
                                    "description": "Object used to restrict the number of chargebacks which are returned in a single response.",
                                    "properties": {
                                        "limit": {
                                            "type": "integer",
                                            "description": "Number of entries to return per request. Default value is 20. Maximum value is not set."
                                        },
                                        "offset": {
                                            "type": "integer",
                                            "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0."
                                        }
                                    }
                                }
                            },
                            "required": [
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "example-1": {
                                "token": "r8u26__LapNUPhbhc000VaMFiwPWI3",
                                "filter": {
                                    "chargeback_id": [
                                        44661,
                                        93028
                                    ]
                                },
                                "signature": "cNIomz5eEZglWmGOQhcpV...vtWQQglfaDhJsUVujIA=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/ChargebackList"
                        },
                        "examples": {
                            "example-1": {
                                "chargebacks": [
                                    {
                                        "chargeback_id": "44661",
                                        "charged_amount": "5000",
                                        "channel_amount": "5000",
                                        "case_id": "10002",
                                        "project_id": "900",
                                        "operation_id": "50000010000001",
                                        "report_date": "2024-01-31",
                                        "respond_by": "2024-02-04 23:59:59",
                                        "rev_date": null,
                                        "tr_date_time": "2024-01-13 17:39:56",
                                        "chb_completed_at": "2024-02-21 00:00:00",
                                        "chb_amount": "50.00",
                                        "chb_settlement_amount": "50.00",
                                        "rev_indicator": null,
                                        "chb_ccy": "USD",
                                        "chb_settlement_ccy": "USD",
                                        "charged_currency": "USD",
                                        "channel_currency": "USD",
                                        "eci_sli": "7",
                                        "reason_code": "10.4",
                                        "card_type": "VISA",
                                        "merchant_id": "70000004",
                                        "card": "400000******0119",
                                        "arn": "70000022010000100000003",
                                        "status": "WON",
                                        "chb_amount_in_usd": "50.0000",
                                        "merchant_name": "COSMOSHOP",
                                        "order_id": "3245678KSDFVGK",
                                        "operation_type": "sale",
                                        "auth_code": "000010",
                                        "card_holder": "COSMO USER",
                                        "issuer_country": "GB",
                                        "chargeback_stage": "Arbitration",
                                        "pre_arbitration_report_date": "2024-02-06",
                                        "pre_arbitration_amount": "50.00",
                                        "pre_arbitration_ccy": "USD",
                                        "arbitration_report_date": "2024-03-06",
                                        "arbitration_amount": "50.00",
                                        "arbitration_ccy": "USD",
                                        "representment_amount": "50.00",
                                        "representment_ccy": "USD"
                                    },
                                    {
                                        "chargeback_id": "93028",
                                        "charged_amount": "5000",
                                        "channel_amount": "5000",
                                        "case_id": "14000",
                                        "project_id": "900",
                                        "operation_id": "67000010000001",
                                        "report_date": "2024-01-31",
                                        "respond_by": "2024-02-04 23:59:59",
                                        "rev_date": null,
                                        "tr_date_time": "2024-01-12 12:22:07",
                                        "chb_completed_at": "2024-02-21 00:00:00",
                                        "chb_amount": "50.00",
                                        "chb_settlement_amount": "50.00",
                                        "rev_indicator": null,
                                        "chb_ccy": "USD",
                                        "chb_settlement_ccy": "USD",
                                        "charged_currency": "USD",
                                        "channel_currency": "USD",
                                        "eci_sli": "7",
                                        "reason_code": "10.4",
                                        "card_type": "VISA",
                                        "merchant_id": "70000001",
                                        "card": "431422******0056",
                                        "arn": "70000022010000100000006",
                                        "status": "WON",
                                        "chb_amount_in_usd": "50.0000",
                                        "merchant_name": "COSMOSHOP",
                                        "order_id": "8327588FDJNFIH",
                                        "operation_type": "sale",
                                        "auth_code": "000005",
                                        "card_holder": "COSMO USER",
                                        "issuer_country": "GB",
                                        "chargeback_stage": "Arbitration",
                                        "pre_arbitration_report_date": "2024-02-06",
                                        "pre_arbitration_amount": "50.00",
                                        "pre_arbitration_ccy": "USD",
                                        "arbitration_report_date": "2024-03-06",
                                        "arbitration_amount": "50.00",
                                        "arbitration_ccy": "USD",
                                        "representment_amount": "50.00",
                                        "representment_ccy": "USD"
                                    }
                                ],
                                "hasMoreRows": false,
                                "signature": "t5BfDi85Hos2/sWjWOZocZhdDrzx10vzg/gtmmKfB2g=="
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        },
        "/fraud/list": {
            "post": {
                "operationId": "POST_fraud_list",
                "summary": "/fraud/list",
                "tags": [
                    "Fraud"
                ],
                "description": "Request to retrieve the list of operations deemed as fraudulent by external payment providers.",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "Token generated in the Ecommpay Dashboard for the user account."
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                },
                                "filter": {
                                    "type": "object",
                                    "description": "Object used for filtering chargeback data by various parameters. \n",
                                    "properties": {
                                        "received_on": {
                                            "type": "array",
                                            "description": "Timeframe within which the payment platform registered the information that the card network reported the operation as fraudulent. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "purchase_date": {
                                            "type": "array",
                                            "description": "Timeframe within which the operation was completed. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. By default, the response returns 20 most recently completed operations that are deemed fraudulent. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "fraud_report_date": {
                                            "type": "array",
                                            "description": "Timeframe within which the operation was reported as fraudulent to the issuer. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. By default, the response returns 20 operations most recently reported as fraudulent. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "issuer_country": {
                                            "type": "array",
                                            "description": "Country code of the card issuer. An array of one or more codes specified in the ISO 3166-1 alpha-2 format ([Country codes](https://developers.ecommpay.com/en/en_country_codes.html)).",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "has_chargebacks": {
                                            "type": "integer",
                                            "description": "Indicator that specifies if at least one chargeback was registered in the payment platform for the operation that is deemed fraudulent. Possible values: 0—none registered, 1—one or more registered."
                                        },
                                        "customer_id": {
                                            "description": "Identifier of the customer in the merchant's project (as a string) or an array of one or more customer identifiers.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "card_type": {
                                            "description": "Code identifying the card network. Possible values: mc—Mastercard, visa—Visa. Can also be passed as an array with one or both supported values.",
                                            "type": [
                                                "string",
                                                "array"
                                            ],
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                "pagination": {
                                    "type": "object",
                                    "description": "Pagination is used to restrict the number of fraud operations information about which is returned in a single response.",
                                    "properties": {
                                        "limit": {
                                            "type": "integer",
                                            "description": "Number of entries to return per request. Default value is 20. Maximum value is not set."
                                        },
                                        "offset": {
                                            "type": "integer",
                                            "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0."
                                        }
                                    }
                                }
                            },
                            "required": [
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "example-1": {
                                "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
                                "signature": "sd0fr5YxcVmJ...grkglpeXJg==",
                                "filter": {
                                    "purchase_date": [
                                        "2025-12-31 00:00:00",
                                        "2026-01-07 23:59:59"
                                    ],
                                    "fraud_report_date": [
                                        "2026-01-01 00:00:00",
                                        "2026-01-01 23:59:59"
                                    ],
                                    "issuer_country": [
                                        "GB",
                                        "FR"
                                    ]
                                },
                                "pagination": {
                                    "limit": 1000
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/FraudApiOperationsList"
                        },
                        "examples": {
                            "example-1": {
                                "operations": [
                                    {
                                        "payment_id": "cosmopayment15_rogd",
                                        "operation_id": 6435212162442,
                                        "tr_amount": "180.00",
                                        "tr_ccy": "GBP",
                                        "account_number": "424242******4242",
                                        "payment_method_type": "visa",
                                        "row_updated_at": "2026-01-01 05:30:30",
                                        "customer_id": "earthling1232442",
                                        "project_name": "cosmoshop.earth",
                                        "project_id": "123",
                                        "arn": "14736364365402210100727",
                                        "fraud_type": "6",
                                        "fraud_report_date": "2026-01-01",
                                        "issuer_country": "GB",
                                        "received_on": "2026-01-01",
                                        "purchase_date": "2025-12-31",
                                        "channel_amount_in_usd": "234.58",
                                        "issuer_bank_name": "Intergalactic Bank",
                                        "bin": "123456",
                                        "country_by_ip": "GB",
                                        "customer_email": "earthling@earth.earth",
                                        "report_and_purchase_date_difference": 2
                                    }
                                ],
                                "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        },
        "/financial-reporting/operations": {
            "post": {
                "operationId": "POST_financial-reporting-operations",
                "summary": "/financial-reporting/operations",
                "description": "Request to retrieve itemised operation data for financial reporting (including charged fees) for a specified time period. These data are accurate and can be used for reconciliation.",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "required": [
                                "token",
                                "signature",
                                "operation_completed_at",
                                "tz"
                            ],
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "Token generated in the Ecommpay Dashboard for the user account."
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using a secret key associated with the token specified in the token parameter."
                                },
                                "operation_completed_at": {
                                    "type": "object",
                                    "description": "Time period with the start and end times for which to retrieve data. Only data about operations completed in the payment platform within the last 30 days can be requested.",
                                    "required": [
                                        "from",
                                        "to"
                                    ],
                                    "properties": {
                                        "from": {
                                            "type": "string",
                                            "description": "Start time in the YYYY-MM-DD hh:mm:ss format."
                                        },
                                        "to": {
                                            "type": "string",
                                            "description": "End time in the YYYY-MM-DD hh:mm:ss format."
                                        }
                                    }
                                },
                                "tz": {
                                    "type": "string",
                                    "description": "Identifier of the time zone for the time period. The time zone affects what operations will be selected for the time period specified in the operation_completed_at object. Can be one of the names in the IANA time zone database (for example, Indian/Mauritius) or the UTC offset (for example, +10:30)."
                                },
                                "project_id": {
                                    "type": "array",
                                    "description": "Array of one or more project identifiers. If the array is omitted, the response will contain information for all projects accessible for the user account which is associated with the token specified in the token parameter.",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "provider_id": {
                                    "type": "array",
                                    "description": "Array of one or more provider identifiers. If the array is omitted, the response will contain information for all providers available for the user account which is associated with the token specified in the token parameter.",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "operation_id": {
                                    "type": "array",
                                    "description": "Array of one or more payment operation identifiers provided by Ecommpay. If the array is omitted, the response will contain information for all projects accessible for the user account which is associated with the token specified in the token parameter.",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "limit": {
                                    "type": "integer",
                                    "description": "Number of entries to return per request. The default value, which is also the maximum, is 1000."
                                },
                                "offset": {
                                    "type": "integer",
                                    "description": "Pagination start offset. Specifies the number of entries to skip before starting to return entries. Default value is 0."
                                }
                            }
                        },
                        "x-examples": {
                            "application/json": {
                                "project_id": [
                                    11
                                ],
                                "operation_completed_at": {
                                    "from": "2024-01-01 00:00:00",
                                    "to": "2024-01-31 23:59:59"
                                },
                                "tz": "Indian/Mauritius",
                                "limit": 1000,
                                "offset": 0,
                                "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
                                "signature": "YsrkgdBr5peXJgJ...glVmsd0f=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/ApiFinancialOperationsList"
                        },
                        "examples": {
                            "application/json": {
                                "data": [
                                    {
                                        "operation_completed_at": "2024-01-29T22:08:19+0000",
                                        "transaction_id": "81194009089601",
                                        "operation_id": "81194009122865",
                                        "provider_payment_id": "0040000028207224",
                                        "payment_id": "1994-1312",
                                        "arn": "70114165164100000032195",
                                        "rrn": "451912040334",
                                        "auth_appr_code": "611887",
                                        "provider_id": "120461",
                                        "provider_name": "Provider name",
                                        "payment_description": "purchase",
                                        "operation_type": "sale",
                                        "operation_status": "success",
                                        "tran_region": "domestic",
                                        "tariff_region": "EU",
                                        "proc_region": "Visa Europe",
                                        "security_level": "SEC",
                                        "operation_amount": 2098,
                                        "operation_currency": "GBP",
                                        "billing_conversion_rate": 0,
                                        "billing_amount": 2098,
                                        "billing_currency": "GBP",
                                        "total_interchange_fee": -4.2,
                                        "total_scheme_fee": -0.64,
                                        "auth_msc_fee": 0,
                                        "clearing_msc_fee": -3.785649,
                                        "total_msc_fee": -3.78,
                                        "hold_amount": 0,
                                        "project_id": 11,
                                        "project_url": "https://www.company.com",
                                        "merchant_name": "COMPANY NAME",
                                        "mid": "70000000",
                                        "terminal_id": "70000000",
                                        "mcc_code": "4722",
                                        "legal_country": "GB",
                                        "payment_method_name": "visa",
                                        "product_type": "Consumer",
                                        "account_funding_source": "debit",
                                        "account_number": "475144******1111",
                                        "card_product": "Visa classic",
                                        "issuer_country": "GB",
                                        "customer_id": "1436462",
                                        "card_holder": "CARD HOLDER"
                                    }
                                ],
                                "signature": "fdsfdsf985np=..."
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                },
                "tags": [
                    "Operations"
                ]
            }
        },
        "/operations/get": {
            "post": {
                "operationId": "POST_operations-get",
                "summary": "/operations/get",
                "tags": [
                    "Operations"
                ],
                "description": "Request to retrieve itemised operation data for a specified time period. These data can be used for general purposes of monitoring and anaysis.",
                "consumes": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "project_id": {
                                    "type": "array",
                                    "description": "Array of one or more project IDs. If array is omitted, the payment platform returns information for all projects accessible for the user account which is associated with the token specified in the token parameter.",
                                    "items": {
                                        "type": "integer"
                                    }
                                },
                                "interval": {
                                    "type": "object",
                                    "description": "Time period with start and end times for which to retrieve data. By default, the response returns operations most recently completed.\r\nIf more than one request is received in the platform from a single Dashboard user account within 10 seconds and the time period for which the information is requested exceeds 180 days, these requests are processed one by one, with 10 seconds timeouts.",
                                    "properties": {
                                        "from": {
                                            "type": "string",
                                            "description": "Start time in the YYYY-MM-DD hh:mm:ss format.\r\n"
                                        },
                                        "to": {
                                            "type": "string",
                                            "description": "End time in the YYYY-MM-DD hh:mm:ss format."
                                        }
                                    },
                                    "required": [
                                        "from",
                                        "to"
                                    ]
                                },
                                "tz": {
                                    "type": "string",
                                    "description": "Identifier of the time zone for the time period. If the request does not contain this parameter, the default is the time zone of the Dashboard user account associated with the token from the token parameter. The time zone affects what operations will be selected for the time period specified in the interval object and the format of time parameters in the response—operation_created_at and operation_completed_at. Can be one of the names in the IANA time zone database (for example, Indian/Mauritius) or the UTC offset (for example, +10:30)."
                                },
                                "limit": {
                                    "type": "integer",
                                    "description": "Number of entries to return per request. Maximum and default value is 1000."
                                },
                                "offset": {
                                    "type": "integer",
                                    "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0."
                                },
                                "operation_type": {
                                    "type": [
                                        "array",
                                        "string"
                                    ],
                                    "description": "Operation type[s]. One or more operation types supported by the Ecommpay payment platform. The operation_type variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "operation_status": {
                                    "type": [
                                        "array",
                                        "string"
                                    ],
                                    "description": "Operation status[es]. One or more operation statuses supported by the Ecommpay payment platform. The operation_status variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "customer_id": {
                                    "type": [
                                        "array",
                                        "string"
                                    ],
                                    "description": "Unique customer identifier[s]. One or more unique identifiers of customers in your project. The customer_id variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "customer_email": {
                                    "type": "string",
                                    "description": "Customer email."
                                },
                                "token": {
                                    "type": "string",
                                    "description": "Token generated in Ecommpay Dashboard for user account."
                                },
                                "fields": {
                                    "type": "array",
                                    "description": "An array of one or more parameter names the values of which are needed to be returned for each operation in the response. In the array, the parameter names must be enclosed in matching quotation marks and separated by commas and can be specified in an arbitrary order (for example, operation_id, payment_id, project_id). However, in the response the parameter values are returned in the fixed order which, together with the list of parameters, is defined in the response specification.  If the array is omitted, then the response contains the values of the required parameters for each operation.",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                }
                            },
                            "required": [
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "application/json": {
                                "project_id": [
                                    0,
                                    11
                                ],
                                "interval": {
                                    "from": "2024-08-01 00:00:00",
                                    "to": "2024-08-28 23:59:59"
                                },
                                "limit": 2,
                                "offset": 1000,
                                "operation_type": [
                                    "sale",
                                    "refund"
                                ],
                                "operation_status": [
                                    "success",
                                    "decline"
                                ],
                                "customer_email": "astronaut@earth.station",
                                "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
                                "fields": [
                                    "operation_id",
                                    "operation_type",
                                    "operation_status",
                                    "sum_initial.amount",
                                    "sum_initial.currency",
                                    "customer_email"
                                ],
                                "signature": "sd0fr5YsdBVmJ...grkglpeXJg=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/ApiOperationsList"
                        },
                        "examples": {
                            "application/json": {
                                "operations": [
                                    {
                                        "operation_id": "6435212162442",
                                        "operation_type": "sale",
                                        "operation_status": "success",
                                        "sum_initial": {
                                            "amount": 1200,
                                            "currency": "USD"
                                        },
                                        "customer_email": "astronaut@earth.station"
                                    },
                                    {
                                        "operation_id": "1232452442",
                                        "operation_type": "refund",
                                        "operation_status": "success",
                                        "sum_initial": {
                                            "amount": 5800,
                                            "currency": "EUR"
                                        },
                                        "customer_email": "astronaut@earth.station"
                                    }
                                ],
                                "signature": "k4iXC845FvT+...dS0AH5BGIw=="
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "Authentication error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "Request rate error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        },
        "/operations/get-by-payment": {
            "post": {
                "operationId": "POST_operations-get-by-payment",
                "summary": "/operations/get-by-payment",
                "tags": [
                    "Operations"
                ],
                "description": "Request to retrieve all the operations performed in the payment platform for specific payment.",
                "consumes": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "payment_id": {
                                    "type": "string",
                                    "description": "Payment ID in the project."
                                },
                                "token": {
                                    "type": "string",
                                    "description": "Token generated by Ecommpay Dashboard for user account."
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key associated with the token specified in the token parameter."
                                }
                            },
                            "required": [
                                "payment_id",
                                "token",
                                "signature"
                            ]
                        },
                        "x-examples": {
                            "application/json": {
                                "payment_id": "PID_25467851461-2147",
                                "token": "VmJQhaXILAnZWTKmqwSd3j",
                                "signature": "JM+YWmTL7uGn26IgZWTKmqwSd...tRkvdC0yaq030+eNXVtJjjtgrkglpeXJg=="
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "schema": {
                            "type": "object",
                            "description": "List of operations with operation details.",
                            "properties": {
                                "operations": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "description": "Operation details.",
                                        "properties": {
                                            "operation_id": {
                                                "type": "string",
                                                "description": "Payment operation ID provided by Ecommpay."
                                            },
                                            "operation_type": {
                                                "type": "string",
                                                "description": "Operation type. One of operation types supported by the Ecommpay payment platform."
                                            },
                                            "operation_created_at": {
                                                "type": "string",
                                                "description": "Date and time when the operation was created. Format: YYYY-MM-DD hh:mm:ss."
                                            },
                                            "operation_completed_at": {
                                                "type": "string",
                                                "description": "Date and time when the operation was completed in the payment platform. Format: YYYY-MM-DD hh:mm:ss."
                                            },
                                            "amount": {
                                                "type": "number",
                                                "description": "Operation amount in minor currency units."
                                            },
                                            "currency": {
                                                "type": "string",
                                                "description": "Operation currency code. Currency code must comply with ISO 4217 alpha-3."
                                            },
                                            "arn": {
                                                "type": "string",
                                                "description": "Acquirer Reference Number - 23 digits of the unique operation identifier in clearing exchange between banks or processing centers."
                                            },
                                            "rrn": {
                                                "type": "string",
                                                "description": "Reference Retrieval Number - 12 digits of the unique operation identifier, which is assigned by the Acquirer Bank when the payment is initialized."
                                            }
                                        },
                                        "required": [
                                            "operation_id",
                                            "operation_type",
                                            "operation_created_at",
                                            "operation_completed_at",
                                            "amount",
                                            "currency",
                                            "arn",
                                            "rrn"
                                        ]
                                    }
                                },
                                "signature": {
                                    "type": "string",
                                    "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                                }
                            }
                        },
                        "examples": {
                            "application/json": {
                                "operations": [
                                    {
                                        "arn": "",
                                        "operation_completed_at": "2024-11-22T13:13:04+00:00",
                                        "operation_type": "refund",
                                        "operation_id": "2747253065470",
                                        "amount": 221,
                                        "currency": "USD",
                                        "operation_created_at": "2024-11-22T13:13:04+00:00",
                                        "rrn": "803817399309"
                                    },
                                    {
                                        "arn": "",
                                        "operation_completed_at": "2024-11-22T13:09:03+00:00",
                                        "operation_type": "capture",
                                        "operation_id": "2747253065469",
                                        "amount": 1621,
                                        "currency": "USD",
                                        "operation_created_at": "2024-11-22T13:09:03+00:00",
                                        "rrn": "000000248370"
                                    },
                                    {
                                        "arn": "",
                                        "operation_completed_at": "2024-11-22T13:06:40+00:00",
                                        "operation_type": "auth",
                                        "operation_id": "2747253065468",
                                        "amount": 2000,
                                        "currency": "USD",
                                        "operation_created_at": "2024-11-22T13:06:38+00:00",
                                        "rrn": "000047769105"
                                    }
                                ],
                                "signature": "hsUpqn7QPDxNLNH/ZulaK...z/Hv7NkQFujSnvw=="
                            }
                        }
                    },
                    "400": {
                        "description": "",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "401": {
                        "description": "",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "429": {
                        "description": "",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    },
                    "500": {
                        "description": "",
                        "schema": {
                            "$ref": "#/definitions/ApiErrorResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "ApiBalanceList": {
            "title": "ApiBalanceList",
            "type": "object",
            "description": "List of balances with balance details.",
            "properties": {
                "balance": {
                    "type": "array",
                    "description": "Array of balances.",
                    "items": {
                        "$ref": "#/definitions/BalanceTransactionItem"
                    }
                },
                "signature": {
                    "type": "string",
                    "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                }
            }
        },
        "ApiErrorResponse": {
            "type": "object",
            "description": "Error details.",
            "required": [
                "status"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Error name."
                },
                "message": {
                    "type": "string",
                    "description": "Description of error cause."
                },
                "code": {
                    "type": "integer",
                    "description": "HTTP error code."
                },
                "status": {
                    "type": "integer",
                    "description": "HTTP response code, for example 400 or 401."
                }
            }
        },
        "ApiFinancialOperationsList": {
            "title": "ApiOperationsList",
            "type": "object",
            "description": "List of operations with extended data (including charged fees).",
            "required": [
                "data",
                "signature"
            ],
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/FinancialOperationItem"
                    }
                },
                "signature": {
                    "type": "string",
                    "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                }
            }
        },
        "ApiOperationsList": {
            "type": "object",
            "description": "List of operations with operation details.",
            "properties": {
                "operations": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/OperationItem"
                    }
                },
                "signature": {
                    "type": "string",
                    "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                }
            }
        },
        "BalanceTransactionItem": {
            "title": "BalanceTransactionItem",
            "type": "object",
            "description": "Balance details.",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Balance name within the contract."
                },
                "{additionalProperties}": {
                    "type": "string",
                    "description": "Currency code and balance amount in minor currency units presented as parameter-value pair, for example: EUR: 5000. Currency code is specified as the parameter name. Balance amount is specified as parameter value."
                }
            }
        },
        "Chargeback": {
            "type": "object",
            "properties": {
                "chargeback_id": {
                    "type": "string",
                    "description": "Chargeback ID."
                },
                "charged_amount": {
                    "type": "string",
                    "description": "Amount that has been debited (as shown in the Operational Statement). Specified as an integer in minor currency units."
                },
                "channel_amount": {
                    "type": "string",
                    "description": "Amount of the disputed operation (as originally processed by the merchant). Specified as an integer in minor currency units."
                },
                "case_id": {
                    "type": "string",
                    "description": "Identification number of the chargeback case (the case may include multiple chargebacks)."
                },
                "project_id": {
                    "type": "string",
                    "description": "Merchant project ID assigned by Ecommpay."
                },
                "operation_id": {
                    "type": "string",
                    "description": "Operation ID provided by Ecommpay."
                },
                "report_date": {
                    "type": "string",
                    "description": "Date when the chargeback was registered in the payment platform."
                },
                "respond_by": {
                    "type": "string",
                    "description": "Deadline for submitting a response to the chargeback."
                },
                "rev_date": {
                    "type": "string",
                    "description": "Date when the chargeback reversal was performed, otherwise null.",
                    "x-nullable": true
                },
                "tr_date_time": {
                    "type": "string",
                    "description": "Date and time when the disputed operation occurred."
                },
                "chb_completed_at": {
                    "type": "string",
                    "description": "Date when the chargeback received one of the final statuses: won, lost, returned, accepted by merchant."
                },
                "chb_amount": {
                    "type": "string",
                    "description": "Amount for which the issuer initiated a chargeback. Specified as a decimal number with two decimal places."
                },
                "chb_settlement_amount": {
                    "type": "string",
                    "description": "Chargeback amount in the settlement currency of the acquiring bank. Specified as a decimal number with two decimal places."
                },
                "rev_indicator": {
                    "type": "string",
                    "description": "‘R’ if there was a chargeback reversal received, otherwise null.",
                    "x-nullable": true
                },
                "chb_ccy": {
                    "type": "string",
                    "description": "Currency of the chargeback initiated by the issuer."
                },
                "chb_settlement_ccy": {
                    "type": "string",
                    "description": "Settlement currency of the acquiring bank."
                },
                "charged_currency": {
                    "type": "string",
                    "description": "Currency in which the amount has been debited (as shown in the Operational Statement)."
                },
                "channel_currency": {
                    "type": "string",
                    "description": "Operation amount currency code."
                },
                "eci_sli": {
                    "type": "string",
                    "description": "Electronic Commerce Indicator (for Visa) and Security Level Indicator (for Mastercard)."
                },
                "reason_code": {
                    "type": "string",
                    "description": "Numerical chargeback reason code."
                },
                "card_type": {
                    "type": "string",
                    "description": "Card payments processing organisation, for example, Visa or Mastercard."
                },
                "merchant_id": {
                    "type": "string",
                    "description": "Merchant identifier assigned by Ecommpay at the stage of integration. "
                },
                "card": {
                    "type": "string",
                    "description": "Number of the card used by the customer."
                },
                "arn": {
                    "type": "string",
                    "description": "Acquirer reference number used for clearing. "
                },
                "status": {
                    "type": "string",
                    "description": "Current status of the chargeback."
                },
                "chb_amount_in_usd": {
                    "type": "string",
                    "description": "Chargeback amount in USD. Specified as a decimal number with four decimal places."
                },
                "merchant_name": {
                    "type": "string",
                    "description": "Merchant name passed in the merchant.descriptor parameter."
                },
                "order_id": {
                    "type": "string",
                    "description": "Operation ID provided by Ecommpay."
                },
                "operation_type": {
                    "type": "string",
                    "description": "Operation type. One of the operation types supported by the Ecommpay payment platform."
                },
                "auth_code": {
                    "type": "string",
                    "description": "Operation authorization code. Alphanumeric code which confirms that the card issuer or payment system approved processing of the payment. Authorization codes are not assigned to declined payments."
                },
                "card_holder": {
                    "type": "string",
                    "description": "Name of the cardholder (as specified on the card)."
                },
                "issuer_country": {
                    "type": "string",
                    "description": "Country of the issuer determined according to the BIN of the card. Array of one or more country codes in ISO 3166-1 alpha-2 format ([Country codes](https://developers.ecommpay.com/en/en_country_codes.html))."
                },
                "chargeback_stage": {
                    "type": "string",
                    "description": "Stage at which the work with the chargeback is currently carried out."
                },
                "pre_arbitration_report_date": {
                    "type": "string",
                    "description": "Date when Ecommpay was informed that the issuer initiated the Pre-Arbitration stage."
                },
                "pre_arbitration_amount": {
                    "type": "string",
                    "description": "Amount of the disputed operation at the Pre-Arbitration stage. May differ from the initial disputed amount."
                },
                "pre_arbitration_ccy": {
                    "type": "string",
                    "description": "Currency of the amount at the Pre-Arbitration stage."
                },
                "arbitration_report_date": {
                    "type": "string",
                    "description": "Date when Ecommpay was informed that the issuer initiated the Arbitration stage."
                },
                "arbitration_amount": {
                    "type": "string",
                    "description": "Amount of the disputed operation at the Arbitration stage."
                },
                "arbitration_ccy": {
                    "type": "string",
                    "description": "Currency of the amount at the Arbitration stage."
                },
                "representment_amount": {
                    "type": "string",
                    "description": "The amount that is returned to the merchant if the merchant wins the chargeback at the Representment stage."
                },
                "representment_ccy": {
                    "type": "string",
                    "description": "Currency in which the chargeback amount is returned to the merchant if the merchant wins the chargeback at the Representment stage."
                }
            }
        },
        "ChargebackList": {
            "type": "object",
            "description": "List of chargebacks.",
            "title": "",
            "properties": {
                "chargebacks": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Chargeback"
                    }
                },
                "hasMoreRows": {
                    "description": "True if the number of rows is more than 20. Please use pagination.",
                    "type": "boolean"
                },
                "signature": {
                    "type": "string",
                    "description": "Digital signature generated by using secret key of the Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                }
            }
        },
        "DateRange": {
            "type": "object",
            "description": "The object must contain start and end dates of the time period for which the data is retrieved.",
            "properties": {
                "from": {
                    "type": "string",
                    "description": "Start date of the required time period. "
                },
                "to": {
                    "type": "string",
                    "description": "End date of the required time period."
                }
            }
        },
        "FinancialOperationItem": {
            "title": "OperationItem",
            "type": "object",
            "description": " Extended operation data (including charged fees).",
            "required": [
                "operation_completed_at",
                "transaction_id",
                "operation_id",
                "provider_payment_id",
                "payment_id",
                "arn",
                "rrn",
                "auth_appr_code",
                "provider_id",
                "provider_name",
                "payment_description",
                "operation_type",
                "operation_status",
                "tran_region",
                "proc_region",
                "security_level",
                "operation_amount",
                "operation_currency",
                "billing_conversion_rate",
                "billing_amount",
                "billing_currency",
                "total_interchange_fee",
                "total_scheme_fee",
                "total_msc_fee",
                "auth_msc_fee",
                "clearing_msc_fee",
                "hold_amount",
                "project_id",
                "project_url",
                "merchant_name",
                "terminal_id",
                "mcc_code",
                "legal_country",
                "payment_method_name",
                "product_type",
                "account_number",
                "card_product",
                "issuer_country",
                "customer_id",
                "card_holder"
            ],
            "properties": {
                "operation_completed_at": {
                    "type": "string",
                    "description": "Time when the operation was completed in the payment platform, specified according to the time zone passed in the request. Format: YYYY-MM-DD hh:mm:ss."
                },
                "transaction_id": {
                    "type": "string",
                    "description": "Identifier used for referencing a payment transaction in the Ecommpay payment platform. In the payment platform, the payment identifier is unique only within the merchant's project while the transaction identifier is unique within the entirety of the payment platform."
                },
                "operation_id": {
                    "type": "string",
                    "description": "Operation identifier assigned by Ecommpay."
                },
                "provider_payment_id": {
                    "type": "string",
                    "description": "Operation identifier assigned by the external payment system or provider."
                },
                "payment_id": {
                    "type": "string",
                    "description": "Payment identifier within the project assigned by the merchant."
                },
                "arn": {
                    "type": "string",
                    "description": "Acquirer Reference Number: an operation identifier used for clearing. This identifier is assigned by the acquirer and is used for tracking operations."
                },
                "rrn": {
                    "type": "string",
                    "description": "Reference Retrieval Number: an operation number assigned by the acquirer which is used for associating the operation with the payment details for easier retrieval and reconciliation."
                },
                "auth_appr_code": {
                    "type": "string",
                    "description": "Alphanumeric code which confirms that the card issuer or the payment system approved processing of the payment. Authorisation codes are not assigned to declined payments."
                },
                "provider_id": {
                    "type": "string",
                    "description": "Identifier of an external payment system or a provider in the payment platform."
                },
                "provider_name": {
                    "type": "string",
                    "description": "Name of an external payment system or a provider in the payment platform."
                },
                "payment_description": {
                    "type": "string",
                    "description": "Description of the payment as specified in the initial request."
                },
                "operation_type": {
                    "type": "string",
                    "description": "One of the operation types supported by the Ecommpay payment platform."
                },
                "operation_status": {
                    "type": "string",
                    "description": "One of the operation statuses supported by the Ecommpay payment platform."
                },
                "tran_region": {
                    "type": "string",
                    "description": "Region code for the operation ([Region codes](https://developers.ecommpay.com/en/en_region_codes.html))."
                },
                "tariff_region": {
                    "type": "string",
                    "description": "Reference to the region that determines the processing fee rate."
                },
                "proc_region": {
                    "type": "string",
                    "description": "Reference to the region that determines what processing rules are applied to the operation."
                },
                "security_level": {
                    "type": "string",
                    "description": "Reference to the result of the cardholder 3‑D Secure authentication, determined on the basis of the Electronic Commerce Indicator parameter. Can be populated with one of the following values: sec, attempt, non-sec."
                },
                "operation_amount": {
                    "type": "number",
                    "description": "Amount of the initial operation; can be a decimal number."
                },
                "operation_currency": {
                    "type": "string",
                    "description": "Initial operation currency code in the ISO 4217 alpha-3 format."
                },
                "billing_conversion_rate": {
                    "type": "number",
                    "description": "Exchange rate used for the conversion of the operation amount to the billing currency; can be a decimal number and, depending on the pricing model, can also be sent empty."
                },
                "billing_amount": {
                    "type": "number",
                    "description": "Operation amount in the billing currency; can be a decimal number and, depending on the pricing model, can also be sent empty."
                },
                "billing_currency": {
                    "type": "string",
                    "description": "Billing currency code in the ISO 4217 alpha-3 format. Depending on the pricing model, can be sent empty."
                },
                "total_interchange_fee": {
                    "type": "number",
                    "description": "Interchange fee amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty."
                },
                "total_scheme_fee": {
                    "type": "number",
                    "description": "Scheme fee amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty."
                },
                "total_msc_fee": {
                    "type": "number",
                    "description": "Merchant service charge total amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty."
                },
                "auth_msc_fee": {
                    "type": "number",
                    "description": "The portion of the Merchant service charge amount charged for authorisation; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty."
                },
                "clearing_msc_fee": {
                    "type": "number",
                    "description": "The portion of the Merchant service charge amount charged for clearing; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty."
                },
                "hold_amount": {
                    "type": "number",
                    "description": "Amount of funds held for the operation; can be a decimal number."
                },
                "project_id": {
                    "type": "integer",
                    "description": "Project identifier provided by Ecommpay."
                },
                "project_url": {
                    "type": "string",
                    "description": "Base URL of the merchant's web service associated with the specific project."
                },
                "merchant_name": {
                    "type": "string",
                    "description": "Name of the merchant within the payment platform."
                },
                "mid": {
                    "type": "string",
                    "description": "Identifier of the merchant assigned by the provider (which includes Ecommpay) or by the acquirer and used for processing card payments."
                },
                "terminal_id": {
                    "type": "string",
                    "description": "Identifier of a logical node in the payment platform that determines the configuration of payment processing properties for a certain MID in specific cases. Assigned within MID."
                },
                "mcc_code": {
                    "type": "string",
                    "description": "Merchant category code. A 4-digit number that classifies the type of the merchant's business activity."
                },
                "legal_country": {
                    "type": "string",
                    "description": "Code of the merchant's country of registration in the ISO 3166-1 alpha-2 format."
                },
                "payment_method_name": {
                    "type": "string",
                    "description": "Identifier of the payment system. For card payments, it is the identifier of the card processing network, for example, Visa or Mastercard. For some payment methods, can be sent empty."
                },
                "product_type": {
                    "type": "string",
                    "description": "Reference to the class of the card product offered by a card processing network, for example, consumer or commercial."
                },
                "account_funding_source": {
                    "type": "string",
                    "description": "Type of the payment card funding, for example, debit, credit, or prepaid."
                },
                "account_number": {
                    "type": "string",
                    "description": "Identifier of the payment instrument used by the customer, for example, a card or a wallet number."
                },
                "card_product": {
                    "type": "string",
                    "description": "Card category offered by the issuing bank, for example, Visa Classic or World Elite Mastercard."
                },
                "issuer_country": {
                    "type": "string",
                    "description": "Country code of the issuer determined according to the BIN of the card in the ISO 3166-1 alpha-2 format."
                },
                "customer_id": {
                    "type": "string",
                    "description": "Identifier of the customer in the merchant's project."
                },
                "card_holder": {
                    "type": "string",
                    "description": "Name of the cardholder as specified in the initial request."
                }
            }
        },
        "FraudApiOperationsList": {
            "title": "FraudApiOperationsList",
            "type": "object",
            "description": "List of fraudulent operations.",
            "properties": {
                "operations": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "payment_id": {
                                "type": "string",
                                "description": "Payment ID in the project."
                            },
                            "operation_id": {
                                "type": "integer",
                                "description": "Operation ID provided by Ecommpay."
                            },
                            "tr_amount": {
                                "type": "string",
                                "description": "Fraudulent operation amount (full operation amount)."
                            },
                            "tr_ccy": {
                                "type": "string",
                                "description": "Fraudulent operation currency code in ISO 4217 alpha-3 format ([Currency codes](https://developers.ecommpay.com/en/en_currency_codes.html))."
                            },
                            "account_number": {
                                "type": "string",
                                "description": "Number of the card used by the customer."
                            },
                            "payment_method_type": {
                                "type": "string",
                                "description": "Type of the payment method used for payment processing."
                            },
                            "row_updated_at": {
                                "type": "string",
                                "description": "The date and time of the most recent update of the fraudulent operation record in the payment platform."
                            },
                            "customer_id": {
                                "type": "string",
                                "description": "Identifier of the customer in the merchant's project."
                            },
                            "project_name": {
                                "type": "string",
                                "description": "Name of the merchant's website (project)."
                            },
                            "project_id": {
                                "type": "string",
                                "description": "Project ID provided by Ecommpay."
                            },
                            "arn": {
                                "type": "string",
                                "description": "Acquirer Reference Number: a unique operation identifier in clearing exchange between banks or processing centers."
                            },
                            "fraud_type": {
                                "type": "string",
                                "description": "Type of fraud declared by the issuer when submitting information about fraudulent operations to payment systems."
                            },
                            "fraud_report_date": {
                                "type": "string",
                                "description": "Date when the operation was reported as fraudulent to the issuer. Format: [YYYY-MM-DD]."
                            },
                            "issuer_country": {
                                "type": "string",
                                "description": "Country code of the card issuer determined according to the BIN of the card (two-letter ISO code)."
                            },
                            "received_on": {
                                "type": "string",
                                "description": "Date when the payment platform registered the information that the card network reported the operation as fraudulent"
                            },
                            "purchase_date": {
                                "type": "string",
                                "description": "Date when the operation was completed. Format: [YYYY-MM-DD,YYYY-MM-DD]."
                            },
                            "channel_amount_in_usd": {
                                "type": "string",
                                "description": "Fraudulent operation amount in USD."
                            },
                            "issuer_bank_name": {
                                "type": "string",
                                "description": "Name of the issuer determined according to the BIN of the card."
                            },
                            "bin": {
                                "type": "string",
                                "description": "Bank Identification Number that refers to the first six to eight digits of PAN, also known as IIN (Issuer Identification Number)."
                            },
                            "country_by_ip": {
                                "type": "string",
                                "description": "Country determined according to the IP address of the customer (two-letter ISO country code)."
                            },
                            "customer_email": {
                                "type": "string",
                                "description": "Customer email address."
                            },
                            "report_and_purchase_date_difference": {
                                "type": "integer",
                                "description": "The number of full days between fraud report and purchase dates."
                            },
                            "has_chargebacks": {
                                "type": "integer",
                                "description": "Indicator that specifies if at least one chargeback was registered in the payment platform for the operation that is deemed fraudulent. Possible values: 0—none registered, 1—one or more registered."
                            },
                            "card_type": {
                                "type": "string",
                                "description": "Code identifying the card network. Possible values: mc—Mastercard, visa—Visa."
                            }
                        }
                    }
                },
                "signature": {
                    "type": "string",
                    "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request."
                }
            }
        },
        "OperationItem": {
            "title": "OperationItem",
            "type": "object",
            "description": "Operation details.",
            "properties": {
                "project_id": {
                    "type": "string",
                    "description": "Project ID provided by Ecommpay."
                },
                "operation_id": {
                    "type": "string",
                    "description": "Payment operation ID provided by Ecommpay."
                },
                "payment_id": {
                    "type": "string",
                    "description": "Payment ID in the project."
                },
                "operation_type": {
                    "type": "string",
                    "description": "Operation type. One of the operation types supported by the Ecommpay payment platform."
                },
                "operation_status": {
                    "type": "string",
                    "description": "Operation status. One of the operation statuses supported by the Ecommpay payment platform."
                },
                "account_number": {
                    "type": "string",
                    "description": "ID of the payment instrument used by customer, for example, card number or wallet ID."
                },
                "customer_ip": {
                    "type": "string",
                    "description": "Customer IP address."
                },
                "payment_method_name": {
                    "type": "string",
                    "description": "Name of the payment method used for payment processing."
                },
                "payment_method_type": {
                    "type": "string",
                    "description": "Type of the payment method used for payment processing."
                },
                "payment_description": {
                    "type": "string",
                    "description": "Description of the payment as specified in the initial request."
                },
                "operation_created_at": {
                    "type": "string",
                    "description": "Date and time when the operation was created. Format: YYYY-MM-DD hh:mm:ss."
                },
                "operation_completed_at": {
                    "type": "string",
                    "description": "Date and time when the operation was completed in the payment platform. Format: YYYY-MM-DD hh:mm:ss."
                },
                "provider_date": {
                    "type": "string",
                    "description": "Date and time when the operation was completed on the payment provider side. Format: YYYY-MM-DD hh:mm:ss."
                },
                "shipment_date": {
                    "type": "string",
                    "description": "Date and time when the payment provider posted the operation for clearing. Format: YYYY-MM-DD hh:mm:ss."
                },
                "sum_initial": {
                    "type": "object",
                    "description": "Amount and currency code of the operation as specified in the initial request.",
                    "required": [
                        "amount",
                        "currency"
                    ],
                    "properties": {
                        "amount": {
                            "type": "string",
                            "description": "Operation amount in minor currency units as specified in the initial request."
                        },
                        "currency": {
                            "type": "string",
                            "description": "Operation currency code as specified in the initial request. Must be the ISO 4217 alpha-3 currency code."
                        }
                    }
                },
                "sum_converted": {
                    "type": "object",
                    "description": "Code of the currency that the payment provider used for performing the operation and the initial amount converted to this currency.",
                    "required": [
                        "amount",
                        "currency"
                    ],
                    "properties": {
                        "amount": {
                            "type": "string",
                            "description": "Operation amount in minor units of the payment provider currency."
                        },
                        "currency": {
                            "type": "string",
                            "description": "Code of the currency that the payment provider used for performing the operation. Must be the ISO 4217 alpha-3 currency code."
                        }
                    }
                },
                "arn": {
                    "type": "string",
                    "description": "Acquirer Reference Number: a unique operation identifier in clearing exchange between banks or processing centers."
                },
                "rrn": {
                    "type": "string",
                    "description": "Reference Retrieval Number: a unique operation identifier assigned by the acquirer bank when the payment is initialized."
                },
                "payment_provider_code": {
                    "type": "string",
                    "description": "Numeric code of payment result from the card issuer or payment provider."
                },
                "payment_provider_message": {
                    "type": "string",
                    "description": "Message of payment result from the card issuer or payment provider."
                },
                "acquirer_bank_name": {
                    "type": "string",
                    "description": "Name of the acquirer bank."
                },
                "auth_code": {
                    "type": "string",
                    "description": "Alphanumeric code which confirms that the card issuer / payment system approved processing of the payment. Authorization codes are not assigned to declined payments."
                },
                "avs_post_code": {
                    "type": "string",
                    "description": "Customer postal code for verification with the Address Verification Service. AVS applies to cardholders from the UK, USA, and Canada."
                },
                "avs_result": {
                    "type": "string",
                    "description": "A single-letter Address Verification Service response code sent by the issuer following the address verification. AVS applies to cardholders from the UK, USA, and Canada."
                },
                "avs_street_address": {
                    "type": "string",
                    "description": "Customer postal address for verification with the Address Verification Service. AVS applies to cardholders from the UK, USA, and Canada."
                },
                "balance_id": {
                    "type": "string",
                    "description": "ID of the merchant's balance aggregation in the Ecommpay payment platform under which all merchant accounts are aggregated. This ID is masked by adding id_mask to the initial identifier."
                },
                "bank_name": {
                    "type": "string",
                    "description": "Name of the issuer determined according to the BIN of the card."
                },
                "bin": {
                    "type": "string",
                    "description": "Bank Identification Number (first six to eight digits of PAN). Numeric identifier of the card organization member. Assigned separately to each card level (for example, Classic, Standard, Gold, Maestro, Visa Electron, etc.) offered by the issuing bank—a card organization member. Also referred to as IIN (Issuer Identification Number)."
                },
                "card_enroll_check": {
                    "type": "string",
                    "description": "Specifies if the card supports 3-D Secure. Possible values are: E—Enrolled (the card supports 3DS), N—Not enrolled, U—Undefined (was unable to determine)."
                },
                "card_holder": {
                    "type": "string",
                    "description": "The name of the cardholder (as specified on the card)."
                },
                "card_product_name": {
                    "type": "string",
                    "description": "Name of the bank product determined according to the BIN of the card."
                },
                "card_token": {
                    "type": "string",
                    "description": "Token of the customer bank card in the Ecommpay payment platform."
                },
                "completed_refund": {
                    "type": "string",
                    "description": "Amount of the issued refund in minor units of currency."
                },
                "country_by_ip": {
                    "type": "string",
                    "description": "Country determined according to the IP address of the customer (two-letter ISO country code)."
                },
                "country_by_bin": {
                    "type": "string",
                    "description": "Country determined according to the BIN of the card, country of the card's issuer (two-letter ISO code)."
                },
                "currency_rate": {
                    "type": "string",
                    "description": "Currency exchange rate used for conversion of the payment amount from the source currency to the default currency."
                },
                "customer_email": {
                    "type": "string",
                    "description": "Customer email address."
                },
                "customer_id": {
                    "type": "string",
                    "description": "Identifier of the customer in the merchant's project."
                },
                "eci": {
                    "type": "string",
                    "description": "Electronic commerce indicator. For possible values and more information, see [ECI codes](https://developers.ecommpay.com/en/en_ECI_codes.html)."
                },
                "expiration_date": {
                    "type": "string",
                    "description": "Date indicating the validity period of the payment card."
                },
                "legal_entity_name": {
                    "type": "string",
                    "description": "Name of the merchant's legal entity."
                },
                "merchant_id": {
                    "type": "string",
                    "description": "Identifier of the merchant within the payment platform."
                },
                "payment_currency": {
                    "type": "string",
                    "description": "Currency of the payment (currency in which payment_amount is specified). Must be the ISO 4217 alpha-3 currency code."
                },
                "payment_type": {
                    "type": "string",
                    "description": "ID of the payment type. Possible values are: 3—Sale, 31—Purchase_dms, 6—Recurring, 24—Transfer, 11—Payout."
                },
                "project_name": {
                    "type": "string",
                    "description": "Name of the merchant's website (project)."
                },
                "project_url": {
                    "type": "string",
                    "description": "URL of the merchant's website (project)."
                },
                "provider_payment_id": {
                    "type": "string",
                    "description": "Identifier of the operation assigned by the external payment system / provider."
                },
                "recurring_id": {
                    "type": "string",
                    "description": "ID of debiting series received in the callback with the COF purchase registration data. This ID is used for all debits performed as part of the COF purchase."
                },
                "recurring_register": {
                    "type": "string",
                    "description": "Specifies whether the recurring purchase was registered. Possible values are: 0—No. 1—Yes."
                },
                "recurring_valid_thru": {
                    "type": "string",
                    "description": "Specifies the date until which the COF purchase is valid."
                },
                "remaining_refund": {
                    "type": "string",
                    "description": "Reflects the remaining balance, only available for the operations which at certain point had success status."
                },
                "secure_3ds_check": {
                    "type": "string",
                    "description": "Specifies whether the customer was redirected to the ACS (Access Control Service) page where the password from the text message is entered. Possible values are: 0—Was not redirected. 1—Was redirected."
                },
                "transaction_completed_at": {
                    "type": "string",
                    "description": "Time of the payment completion."
                },
                "transaction_created_at": {
                    "type": "string",
                    "description": "Time of the payment creation."
                },
                "transaction_status": {
                    "type": "string",
                    "description": "Payment status."
                }
            },
            "required": [
                "project_id",
                "operation_id",
                "payment_id",
                "operation_type",
                "operation_status",
                "account_number",
                "customer_ip",
                "payment_method_name",
                "payment_method_type",
                "payment_description",
                "operation_created_at",
                "provider_date",
                "shipment_date",
                "sum_initial",
                "sum_converted",
                "arn",
                "rrn",
                "payment_provider_code",
                "payment_provider_message"
            ]
        }
    },
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ]
}

---

# Payment methods {#en_pm_about}

A section with information about supported payment methods and the specifics of their work, including the overview with the classification of methods, method catalogue, and the description of each method.

## Overview {#section_cdx_r1q_yvb .section}

The Ecommpay payment platform allows processing payments made with a variety of payment methods.Each payment method supports specific processing scenarios and operations in different regions. Thus, as a whole, combining a number of payment methods allows you to reach a diverse customer base all over the globe.

Ecommpay is constantly expanding the range of supported payment methods and increasing the availability of payments made with the ever growing number of payment instruments and currencies in different regions.This section describesthe types of the supported payment methods, the individual methods, and the specifics of their use.It also covers [the testing options](en_pm_testing.md) for different operations performed with the use of various payment methods.

If you have questions regarding the terms and conditions as well as the procedure of adding any of the supported payment methods, or if you would like to suggest a payment method \(or several\) for us to offer in the future, contact your Ecommpay account manager. If you have questions regarding the technical aspects of integrating, testing, or working with different methods, refer to the technical support specialists.

-   *Card payments or Cards*—payments that involve the transfer of funds between the accounts of the customer and the merchant with the use of the customer's payment card details.These payments can be processed via the Ecommpay processing centre \(in which case Ecommpay acts as an acquirer, thereby providing the services of *direct acquiring*\) and the systems of the partner-acquirers. The payment instrument in this case is always the payment card of the customer while the payment processing scenarios may differand may involve using specific services and performing various procedures.Payment methods of this type include standard card payments\(performed with the direct use of payment cards, without participation of additional services\) and such methods as Apple Pay, Click to Pay, and Google Pay that involve participation of eponymous servicesaimed at improving customer experience during card payments.

    **Note:** Within this documentation, the expression *card payments* refers to *standard card payments* unless otherwise noted.

-   *Bank payments or Banking*—payments that are carried out with the use of the specialised online services of different bankswhich allow transferring funds between the customer and the merchant \(directly or via the account of the provider\). The payment instrument in this case is the customer's bank account, while the payment processing scenarios may involve the online banking technologies, bank transfers, and other bank services.Payment methods of this type include the group of the European Open banking payment methods, online banking in South-East Asia \(for example, the Banks of Indonesia payment method\), and many others.
-   *Digital wallet payments or Wallets*—payments that involve the customer's digital walletprovided by a certain operator. The payment instruments in this case can vary: it can be the wallet itself \(for example, in case of such payment methods as PayPal andNeteller\) or the customer's payment card\(for example, in case of Apple Pay orGoogle Pay\), while the payment processing scenarios differ greatly depending on the intended use the wallet.
-   *QR code payments or QR codes*—payments that require the customer to scan a special QR codeand in certain cases perform other actions afterwards. The payment instrument in this case can be a bank account or a digital wallet.Payment methods of this type include Promptpay, QRIS and others.

## List of methods {#section_rsf_bbq_yvb .section}

To find payment methods that fit your needs, use the following table with all supported methods. The data in the table can be sorted and filtered by various conditions.

You can also use [Ecommpay shop](https://ecommpay.com/shop/) to find suitable methods by the type of your business and other criteria.

| |Method|Type|Purchases|Payouts|
|--|------|----|:-------:|:-----:|
|![](images/pm/methods_icon/pm_card_payments.svg)|[Standard card payments](en_pm_card_payments.md)|card payments|+|+|
|![](images/pm/methods_icon/pm_alipay.svg)|[Alipay](pm_alipay.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_applepay.svg)|[Apple Pay](pm_applepay.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_astropay.svg)|[AstroPay](pm_astropay.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_bancontact.svg)|[Bancontact](pm_bancontact.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_bancomatpay.svg)|[Bancomat Pay](pm_bancomatpay.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_hk_banks.svg)|[Banks of Hong Kong](pm_hk_banks.md)|bank payments|–|+|
|![](images/pm/methods_icon/pm_philippines.svg)|[Banks of the Philippines](pm_philippines.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_blik.svg)|[Blik](pm_blik.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_bnpl.svg)|[Buy Now Pay Later](pm_bnpl.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_boost.svg)|[Boost Wallet](pm_boost.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_brazil_ob.svg)|[Brazil Online Banking](pm_brazil_ob.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_bnpl.svg)|[Buy Now Pay Later](pm_bnpl.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_chile_ob.svg)|[Chile Online Banking](pm_chile_ob.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_unionpay.svg)|[China UnionPay](pm_unionpay.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_clicktopay.svg)|[Click to Pay](pm_clicktopay.md)|card payments|+|–|
|![](images/pm/methods_icon/pm_coinsph.svg)|[Coins.ph](pm_coinsph.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_dd_bacs.svg)|[Direct Debit BACS](pm_dd_bacs.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_dd_sepa.svg)|[Direct Debit SEPA](pm_dd_sepa.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_doku.svg)|[DOKU Wallet](pm_doku.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_ecuador_ob.svg)|[Ecuador Online Banking](pm_ecuador_ob.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_eps.svg)|[EPS](pm_eps.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_gcash.svg)|[GCash](pm_gcash.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_googlepay.svg)|[Google Pay](pm_googlepay.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_grabpay.svg)|[GrabPay](pm_grabpay.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_hk_qr.svg)|[Hong Kong FPS QR](pm_hk_qr.md)|QR code payments|+|–|
|![](images/pm/methods_icon/pm_ideal_wero.svg)|[iDEAL \| Wero](pm_ideal.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_indonesia.svg)|[Indonesian Online Banking](pm_indonesia.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_indonesia_va.svg)|[Indonesian Virtual Accounts](pm_indonesia_va.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_bankpayout_uk.svg)|[Local payouts to bank accounts in the UK](pm_bankpayout_uk.md)|bank payments|–|+|
|![](images/pm/methods_icon/pm_malaysia.svg)|[Malaysian Online Banking](pm_malaysia.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_maya.svg)|[Maya](pm_maya.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_mbway.svg)|[MBWay](pm_mbway.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_mexico_ob.svg)|[Mexico Online Banking](pm_mexico_ob.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_momoqr.svg)|[MoMo Wallet](pm_momoqr.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_multibanco.svg)|[Multibanco](pm_multibanco.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_mybank.svg)|[MyBank](pm_mybank.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_neteller.svg)|[Neteller](pm_neteller.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_austria.svg)|[Open Banking in Austria](pm_austria.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_belgium.svg)|[Open Banking in Belgium](pm_belgium.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_denmark.svg)|[Open Banking in Denmark](pm_denmark.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_estonia.svg)|[Open Banking in Estonia](pm_estonia.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_finland.svg)|[Open Banking in Finland](pm_finland.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_france.svg)|[Open Banking in France](pm_france.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_germany.svg)|[Open Banking in Germany](pm_germany.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_hungary.svg)|[Open Banking in Hungary](pm_hungary.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_italy.svg)|[Open Banking in Italy](pm_italy.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_ireland.svg)|[Open Banking in Ireland](pm_ireland.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_latvia.svg)|[Open Banking in Latvia](pm_latvia.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_lithuania.svg)|[Open Banking in Lithuania](pm_lithuania.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_luxembourg.svg)|[Open Banking in Luxembourg](pm_luxembourg.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_norway.svg)|[Open Banking in Norway](pm_norway.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_poland.svg)|[Open Banking in Poland](pm_poland.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_portugal.svg)|[Open Banking in Portugal](pm_portugal.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_romania.svg)|[Open Banking in Romania](pm_romania.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_spain.svg)|[Open Banking in Spain](pm_spain.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_sweden.svg)|[Open Banking in Sweden](pm_sweden.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_netherlands.svg)|[Open Banking in the Netherlands](pm_netherlands.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_uk.svg)|[Open Banking in the UK](pm_uk.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_ovo.svg)|[OVO Wallet](pm_ovo.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_bankpayout_sepa.svg)|[Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)|bank payments|–|+|
|![](images/pm/methods_icon/pm_paypal.svg)|[PayPal](pm_paypal.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_paypal_pay_later.svg)|[PayPal Pay Later](pm_paypal_pay_later.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_peru_ob.svg)|[Peru Online Banking](pm_peru_ob.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_philippines_atm.svg)|[Philippines Over the Counter & ATM](pm_philippines_atm.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_pix.svg)|[PIX](pm_pix.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_promptpay.svg)|[Promptpay](pm_promptpay.md)|QR code payments|+|–|
|![](images/pm/methods_icon/pm_przelewy.svg)|[Przelewy24](pm_przelewy.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_satispay.svg)|[Satispay](pm_satispay.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_qris.svg)|[QRIS](pm_qris.md)|QR code payments|+|–|
|![](images/pm/methods_icon/pm_qrph.svg)|[QR Ph](pm_qrph.md)|QR code payments|+|–|
|![](images/pm/methods_icon/pm_shopee.svg)|[Shopee](pm_shopee.md)|digital wallet payments|+|−|
|![](images/pm/methods_icon/pm_skrill.svg)|[Skrill Wallet](pm_skrill.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_swish.svg)|[Swish](pm_swish.md)|bank payments|+|–|
|![](images/pm/methods_icon/pm_thailand.svg)|[Thai Online Banking](pm_thailand.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_touchngo.svg)|[Touch&Go](pm_touchngo.md)|digital wallet payments|+|+|
|![](images/pm/methods_icon/pm_truemoney.svg)|[TrueMoney](pm_truemoney.md)|QR code payments|+|–|
|![](images/pm/methods_icon/pm_twint.svg)|[TWINT](pm_twint.md)|digital wallet payments|+|–|
|![](images/pm/methods_icon/pm_vietnam.svg)|[Vietnamese Online Banking](pm_vietnam.md)|bank payments|+|+|
|![](images/pm/methods_icon/pm_instalments.svg)|[Visa Instalments](pm_instalments.md)|card payments|+|–|
|![](images/pm/methods_icon/pm_wechat.svg)|[WeChat](pm_wechat.md)|digital wallet payments|+|–|

-   **[Card payments](en_pm_cardpayments.md)**  
Articles about card payments that involve the transfer of funds with the use of the customer's payment card details.
-   **[Bank payments](en_pm_bankpayments.md)**  
Articles about bank payments that involve the transfer of funds with the use of the specialised online services of different banks.
-   **[Digital wallet payments](en_pm_ewallet.md)**  
Articles about digital wallets that involve the transfer of funds with the use of the customer's digital wallet provided by a specific operator.
-   **[QR code payments](en_pm_qr.md)**  
Articles about QR code payments that require the customer to scan a special QR code in order to transfer the funds.
-   **[Testing](en_pm_testing.md)**  
An article about the capability of testing different types of payments and operations for different payment methods.



---

# Card payments {#en_pm_cardpayments}

Articles about card payments that involve the transfer of funds with the use of the customer's payment card details.

*Card payments or Cards*—payments that involve the transfer of funds between the accounts of the customer and the merchant with the use of the customer's payment card details.These payments can be processed via the Ecommpay processing centre \(in which case Ecommpay acts as an acquirer, thereby providing the services of *direct acquiring*\) and the systems of the partner-acquirers. The payment instrument in this case is always the payment card of the customer while the payment processing scenarios may differand may involve using specific services and performing various procedures.

Payment methods of this type include [standard card payments](en_pm_card_payments.md), as well as the functionality of paying in [instalments enabled by Visa](pm_instalments.md),and such methods as [Apple Pay](pm_applepay.md), [Click to Pay](pm_clicktopay.md), and [Google Pay](pm_googlepay.md).

-   **[Standard card payments](en_pm_card_payments.md)**  
An article about the payment method which allows you to process payments made with the direct use of payment cards in most regions and supports purchases \(as well as instalments\), refunds, and payouts.
-   **[Click to Pay](pm_clicktopay.md)**  
An article about the payment method which allows you to process payments with the use of cards stored in the Click to Pay service in most countries and supports one-time one-step and two-step purchases and refunds.
-   **[Visa Instalments](pm_instalments.md)**  
An article about the payment method that extends the functionality of standard card payments with the implementation of the Buy Now, Pay Later \(BNPL\) approach.

**Parent topic:**[Payment methods](en_pm_about.md)



---

# Standard card payments {#en_pm_card_payments}

An article about the payment method which allows you to process payments made with the direct use of payment cards in most regions and supports purchases \(as well as instalments\), refunds, and payouts.

*Card payments* is a payment method which allows to process payments made with the direct use of payment cards in most regions.This method supports purchases\(as well as [instalments](pm_instalments.md)\), refunds and payouts.

This payment method supports the following:

|Payment method type|card payments|
|Payment instruments|payments cards|
|Countries and regions|most countries in the world|
|Payment currencies|most currencies in the world|
|Currency conversion|+|
|Purchases|+|
|Payouts|+|
|Stored credentials payments|+|
|Full refunds|+|
|Partial refunds|+|
|Chargebacks|+|
|Notes|+|
|Onboarding and access fee|refer to your Ecommpay account manager|

Information about the actions required to process payments by using different interfaces is presented in the sections [Gate](en_Gate_Integration_About.md#section_y53_dsc_stb), [Payment Page](en_PP_about.md#section_ywk_z5g_btb), and [Dashboard](en_dbl_payments.md).

**Parent topic:**[Card payments](en_pm_cardpayments.md)



---

# Click to Pay {#pm_clicktopay}

An article about the payment method which allows you to process payments with the use of cards stored in the Click to Pay service in most countries and supports one-time one-step and two-step purchases and refunds.

**Parent topic:**[Card payments](en_pm_cardpayments.md)

## Overview {#en_pm_clicktopay_overview}

An article about the payment method which allows you to process payments with the use of cards stored in the Click to Pay service in most countries and supports one-time one-step and two-step purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Click to Pay is a payment method which allows you to process payments with the use of American Express, Maestro, Mastercard, and Visa in most countries of the world and in different currencies.Using this method ensures that the payment card data is securely stored in the Click to Pay service and this data can be accessed via various desktop and mobile devices, including Android and iOS ones. Click to Pay supports processing payments in the USA and Canada, the countries of the EEA and most countries in Asia, Africa, and South America. The Ecommpay payment platform supports one-time one-step and two-step purchases and refunds using the Click to Pay method.

This article provides information about working with the Click to Pay method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|card payments|
|Payment instruments|payments cards|
|Countries and regions|most countries in the world|
|Payment currencies|most currencies in the world|
|Currency conversion|+|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|+|
|Notes|-   Global card networks support Click to Pay in a wide range of countries, and this range is constantly growing \(for more information, refer to your Ecommpay account manager\).
-   Whether Click to Pay is supported for customers in specific countries also depends on the card issuers in these countries \(for more information, refer to your Ecommpay account manager\).
-   In the Payment Page user interface, Click to Pay is offered as one of the ways to make a card payment \(alongside standard card payments; more information can be found [below](pm_clicktopay.md#section_by2_glq_wcc) in the description of processing scenarios\).
-   If the payment made with Click to Pay is declined, the customer can make another attempt to pay using standard card payments and, in case of subsequent declines, can be offered to pay with the use of other available payment methods \(more information about payment retries can be found [in this article](en_PP_Try_Again.md)\).

|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Click to Pay method involves the merchant's web service, the Payment Page interface, the Ecommpay payment platform, and technical facilities of the Click to Pay service.

![](images/pm/en_click_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Processing Click to Pay payments in the payment platform involves the following interfaces: purchases can be processed by using Payment Page, refunds—by using Gate and Dashboard. Depending on the specifics of the card processing networks and issuers, various amount and time limitations can also apply.

### Processing scenarios {#en_pm_clicktopay_processing_scenarios}

#### General information {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Click to Pay method, you need to register the customer and their payment cards in the Click to Pay service and then execute the required steps, while to issue a refund, you need to receive a request from the customer and notify them about the result of the refund via the web service. In addition, the customers can be registered in the service not only during checkout but also beforehand via global card networks and issuers \(learn more [below](pm_clicktopay.md#section_aq1_4pd_bdc)\).

In general, scenarios of purchases and refunds can be represented as follows.

![](images/pm/en_clicktopay_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_clicktopay_interfaces_gate_refund.svg "Refund by using Gate")

Specific scenarios for performing a purchase with the Click to Pay method can vary depending on what customer, with what device and what browser and with the use of which payment card intends to make a payment. There are four main user scenarios:

-   *Returning user checkout* \(or *basic purchase*\)—the payment is made by the customer already registered in the service. The customer utilises a previously used device, browser, and card, and the identification and authentication of the customer involve the use of their email and phone number.
-   *Returning user checkout, unrecognised device* \(or *purchase with a new device*\)—the payment is made by the customer already registered in the service. The customer utilises a device or a browser that has not been used to make a payment before.
-   *Returning user checkout with a new card* \(or *purchase with a new card*\)—the payment is made by the customer already registered in the service. The customer utilises a card that has not been used to make a payment before.
-   *First time user enrolment* \(or *purchase by a new customer*\)—the payment is made by the new customer following their registration in the Click to Pay service.

**Note:** Specifying the customer's phone number and email \(in some cases—just one of these parameters\) in the initial request allows you to streamline user scenarios. Depending on the particular workflow, either the customer will be logged in the Click to Pay service and authenticated automatically, or the corresponding fields in the payment form will be shown prefilled.Therefore, it is recommended that you have your customers registered in the web service beforehand, so that you can pass their phone numbers and emails in the requests to improve user experience and payment form conversion.

One of the special aspects of processing Click to Pay purchases is the use of specialised pages that are shown in the payment form and the data for which is received directly from the Digital Card Facilitators \(DCF\). Digital card facilitators are global card networks that participate in the Click to Pay service and provide customers with access to digital cards.

#### Returning user checkout {#section_by2_glq_wcc .section}

Below is a user scenario of the basic purchase made via Payment Page.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_3.svg "Identification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_4.svg "Click to Pay authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_3.svg "Selecting the card")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_4.svg "Payment in progress notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_5.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_6.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_7.svg "Redirecting to the web service")

If the initial request contains the customer's phone number and email \(in some cases—just one of these parameters\), the step with the customer's identification and authentication in the service is skipped.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_3.svg "Selecting the card")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_4.svg "Payment in progress notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_5.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_6.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_common_7.svg "Redirecting to the web service")

#### Returning user checkout, unrecognised device {#section_jyp_glq_wcc .section}

Below is a user scenario of the purchase made with a new device via Payment Page.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_3.svg "Identification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_4.svg "Click to Pay authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_5.svg "Selecting the card")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_6.svg "Payment in progress notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_7.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_8.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_9.svg "Redirecting to the web service")

If the initial request contains the customer's phone number and email \(in some cases—just one of these parameters\), the step with the customer's identification in the service is skipped.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_4.svg "Click to Pay authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_5.svg "Selecting the card")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_6.svg "Payment in progress notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_7.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_8.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_otpcode_9.svg "Redirecting to the web service")

#### Returning user checkout with a new card {#section_d3c_hlq_wcc .section}

Below is a user scenario of the purchase made with a new card via Payment Page. Keep in mind that if the initial request contains the customer's phone number and email, the corresponding fields in the payment form are shown prefilled.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_3.svg "Proceeding to add the card")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_4.svg "Entering data")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_5.svg "Card added notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_6.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_addcard_8.svg "Redirecting to the web service")

#### First time user enrolment {#section_r1q_hlq_wcc .section}

Below is a user scenario of the purchase made via Payment Page by the new customer. Keep in mind that if the initial request contains the customer's phone number and email, the corresponding fields in the payment form are shown prefilled.

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_2.svg "Opening the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_3.svg "Identification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_4.svg "Entering data")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_5.svg "Registration complete notification")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_6.svg "3‑D Secure authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_click_registration_8.svg "Redirecting to the web service")

#### Provisional enrolment {#section_aq1_4pd_bdc .section}

First time customers can be enrolled in the Click to Pay service not only during checkout\(as in scenarios described above\), but also beforehand:

-   Via global card networks.
    -   An American Express cardholder can access their Click to Pay profile with the email that was used for creating their user account on the American Express website or in the Amex mobile application.
    -   A Mastercard cardholder can enrol [on the Mastercard website](https://src.mastercard.com/profile/card/add).
    -   A Visa cardholder can enrol [on the Visa website](https://secure.checkout.visa.com/).
-   Via payment card issuers: an issuer can enrol customers by bulk pre-provisioning or can prompt customers to create a Click to Pay profile in their mobile banking application and on the website.

## Purchases by using Payment Page {#en_pm_clicktopay_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Click to Pay method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result. In case of a two-step purchase, it might be required, at a later point, to confirm the capture of the held funds.The full sequence and special aspects of one-step purchase processing are provided below.

![](images/pm/en_clicktopay_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  The payment platform requests the Click to Pay service to identify the customer.
6.  The Click to Pay service processes the request.
7.  The Click to Pay service informs the payment platform that the customer has been identified.
8.  The payment platform sends a request to Click to Pay to obtain information about the customer's cards associated with the Click to Pay account.
9.  The Click to Pay service processes the request.
10. The Click to Pay service sends the list of available cards to the payment platform.
11. Payment Page is generated based on the project and request parameters.
12. The customer is shown the payment form with the list of cards associated with the customer's Click to Pay account.
13. The customer selects the card from the list and confirms the payment.
14. The request for processing a payment with the selected card is passed to the Click to Pay service.
15. The Click to Pay service processes the request.
16. Payment Page receives the data from the Click to Pay service for displaying the preloader page to the customer.
17. The service preloader page is displayed to the customer.
18. The Click to Pay service sends a confirmation to the payment platform that the purchase with the selected card can be processed.
19. Payment Page receives the payment confirmation data from the payment platform.
20. The Payment Page preloader is displayed to the customer.
21. The payment platform processes the request and sends it to the card organisation service.
22. The purchase is processed in the card organisation service.
23. The card organisation service sends a notification about the result to the payment platform.
24. The payment platform sends the payment result callback to the web service.
25. The payment platform sends the result information to Payment Page.
26. The result information is displayed to the customer on Payment Page.

In case of a two-step purchase, the process of placing the authorisation hold via Payment Page using the Click to Pay method is identical to the workflow sequence of a one-step purchase, with the exception that instead of an immediate debiting of funds an authorisation hold is initiated and executed.

In other user scenarios, the interaction between the customer and the Payment Page interface is the same as described [above](pm_clicktopay.md) while the web service executes the same actions. In addition, if the capability of payment retries is enabled and one of the Click to Pay purchase scenarios is declined, the customer can retry the payment while using their card \(standard card payments\), and in case of subsequent declines, can be offered to pay with the use of other available payment methods \(more information about payment retries can be found [in this article](en_PP_Try_Again.md)\).

Information about the formats of requests and callbacks used for processing payments by using the Click to Pay method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Click to Pay method:

1.  The following parameters required for any payment must be specified:

    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
    **Warning:** In order to enhance the quality of payment processing and ensure compliance with industry standards, starting from January 15, 2026, merchants in certain business categories must specify the `booking_info` parameter containing information about the start and end dates of the booked service \([details](en_pp_additional_data.md)\), for each initiated [card purchase](en_pm_cardpayments.md). This requirement applies to merchants with [Merchant Category Codes \(MCC\)](en_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519, and 7922.

2.  To specify the type of purchase that is different from the default one set for the specific project, pass `sale` \(for immediate withdrawal of funds during one-step purchase processing\) or `auth`\(to place an authorisation hold during two-step purchase processing\) in the `operation_type` parameter.
3.  Additionally, it is recommended that you specify the customer's country calling code, phone number, and email in parameters `customer_phone_country`, `customer_phone`, and `customer_email`.

    Specifying these parameters in the request makes it possible to authenticate the customer in the Click to Pay service seamlessly, without asking the customer to enter this information into custom fields of the payment form, even if the customer uses the device or the browser that has not been used previously.

    If these parameters have not been passed in the request while the customer uses a new device or a browser, then the payment form will show the corresponding custom fields to collect required information, and the authentication of the user in the service will include the step of entering the OTP code that is sent to the provided phone number or email of the customer.

    ```language-json
    "customer_phone_country": "44",
    "customer_phone": "1172345678",
    "customer_email": "test@test.com"
    ```

4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Click to Pay method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, the recommended data to be included in the request for opening Payment Page should be as follows.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_phone_country": "44", 
   "customer_phone": "1172345678",
   "customer_email": "test@test.com",
   "signature": "oMg2x9dgASNAFUldOcZzUCwX6R\/ekpsdfkIFf=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Click to Pay method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 USD` purchase made by the `cust123` customer in the `1204` project.

```language-json
{
        "project_id": 1204,
        "payment": {
            "id": "Payment_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2024-08-30T13:58:12+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "Purchase"
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2024-08-30T13:58:12+0000",
            "created_date": "2024-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "provider": {
                "id": 120461,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2024-08-30T13:58:09+0000",
                "auth_code": "591748"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67Mb9siv7+WD1u7AyIYdQ=="
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "account": {
            "number": "518600******8785"
        },
        "customer": {
            "id": "cust123"
        },
        "payment": {
            "date": "2024-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken-click2pay",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "GB",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2024-08-06T12:57:03+0000",
            "created_date": "2024-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "provider": {
                "id": 120461,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVSRo8YNjIxHPjEEQSmLAtClQ=="
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_clicktopay_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Click to Pay method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_clicktopay_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the card organisation service.
7.  The refund is processed on the side of the card organisation service.
8.  The card organisation service sends the result notification to the payment platform.
9.  The payment platform processes the result notification and informs the Click to Pay service about the result, following which the payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Click to Pay method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Click to Pay method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Click to Pay method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Click to Pay method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 USD` refund made for the `cust123` customer in the `424242` project.

```language-json
{
        "project_id": 424242,
        "payment": {
            "id": "payment_15792507735",
            "type": "purchase",
            "status": "refunded",
            "date": "2024-01-20T08:31:36+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "purchase"
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "id": 69512000019571,
            "type": "refund",
            "status": "success",
            "date": "2024-01-20T08:31:36+0000",
            "created_date": "2024-01-20T08:31:35+0000",
            "request_id": "e0069513",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 120461,
                "payment_id": "0000438583",
                "auth_code": ""
                }
            },
        "signature": "beJ1deUiEDd+7zuo6YrfSRzgEQj34sKAStuW8Fg=="
    }
```

The following is the example of a callback with information about a declined refund.

```language-json
{
        "project_id": 424242,
        "payment": {
            "id": "Payment_1579250773501",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-20T08:31:36+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 100,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "sum": {
                "amount": 100000,
                "currency": "USD"
            },
            "code": "3283",
            "message": "Refund amount more than init amount",
            "provider": {
                "id": 120461,
                "payment_id": "0000438582",
                "auth_code": ""
            },
            "id": 69512000019571,
            "type": "refund",
            "status": "decline",
            "date": "2024-01-20T08:31:36+0000",
            "created_date": "2024-01-20T08:31:35+0000",
            "request_id": "e0069142"
        },
        "signature": "beJ1deUiEDd+7zuooJzgEQj34sKAStuW8Fg=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Click to Pay method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_clicktopay.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_clicktopay_dash_analysis}

To analyse information about payments made with the Click to Pay method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Visa Instalments {#pm_instalments}

An article about the payment method that extends the functionality of standard card payments with the implementation of the Buy Now, Pay Later \(BNPL\) approach.

**Parent topic:**[Card payments](en_pm_cardpayments.md)

## Overview {#en_pm_instalments_overview}

An article about the payment method that extends the functionality of standard card payments with the implementation of the Buy Now, Pay Later \(BNPL\) approach.

### Introduction {#section_t5z_rlg_ytb .section}

Visa Instalments extends the functionality of [standard card payments](en_pm_card_payments.md) with the implementation of Buy Now, Pay Later \(BNPL\) approach. This approach can be used in various business industries and comes in handy when it is more convenient for customers to pay in fixed, equal parts over a defined period of time instead of a full amount outright.In particular, it is a useful option in tourist industry and luxury retail as it helps merchants to attract and retain new clients while building an efficient and profitable business.

Paying in instalments enabled by Visa is available for eligible Visa credit cards from participating card issuing banks that are signed up for VIS—Visa Instalments Solution. The Ecommpay payment platform supports processing Visa Instalments using Payment Page, with the full payment amount credited to the merchant’s balance in one or two steps \(i.e. with the authorisation hold as the first step\).This functionality is available only to UK-based merchants.

This article provides information about working with the Visa Instalments functionality: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|card payments|
|Payment instruments|payments cards|
|Countries and regions|[GB](references/en/countries/GB.md)|
|Payment currencies|[GBP](references/en/currencies/GBP.md)|
|Currency conversion|+|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|+|
|Notes|refer to the [section](pm_instalments.md#section_i25_xt1_1gc)|
|Onboarding and access fee|refer to your Ecommpay account manager, additional information available in the [Ecommpay shop](https://ecommpay.com/payment-methods/payment-method-finder/)|

### Special aspects and limitations {#section_i25_xt1_1gc .section}

When working with the Visa Instalments functionality, consider the following special aspects and limitations:

-   This functionality is available only to UK-based merchants.
-   Only Visa credit cards from participating card issuers based in the United Kingdom and supporting Visa Instalments Solution are eligible.
-   Customers paying for their purchases in instalments enabled by Visa must be notified that this is a type of credit with the purchase amount deducted from the existing available credit limit on the card and with the responsibility to repay the debt \(according to the instalments plan selected\). If the cardholder delays or misses a payment, the issuer can charge additional fees.
-   Eligibility for instalments enabled by Visa is determined in each individual case by the card issuer.
-   The functionality is supported for the 5th generation Payment Page and can be used for one-time one-step and two-step purchases, with the card details specified as is or in the form of saved data and tokens.
-   When Visa Instalments purchase has been processed in the payment platform, together with the regular fee for processing a payment the merchant is charged an additional fee payable to Visa and Ecommpay. To learn more about this or any other fees, refer to your Ecommpay account manager.

If you have questions about limitations, conditions, and possible availability of this functionality in other geographic regions, contact your Ecommpay account manager. If you have any technical questions, refer to the Ecommpay support specialists.

### Interaction diagram {#section_tsp_gzk_ggb .section}

Processing a payment using the Visa Instalments functionality involves the merchant's web service, the Payment Page interface, the Ecommpay payment platform, and the technical facilities of the Visa Instalments Solution service and the issuing bank of the customer's card.

![](images/ecommpay/en_instalments_functional.svg)

With Visa Instalments, the customer selects the instalments plan and agrees to pay fixed payments to the issuer according to the specified schedule. Note that the full purchase amount is held against the cardholder’s available credit limit at the time of purchase—on the terms of the instalments plan defined by the issuer. After the initial purchase is processed, the customer settles directly with the issuer.

![](images/ecommpay/en_pp_visa_instalments_plan_selection.svg "Purchase in instalments enabled by Visa")

In turn, themerchant is paid the full amount \(minus any applicable fees as in the case with other types of purchases\) because this amount is paid by the issuer of the card used at the time of purchase.

### Processing scenario {#section_fgt_sdl_ggb .section}

Below is a user scenario of the basic purchase made with the Visa Instalments functionality.

![](images/ecommpay/en_pp_visa_instalments_1.svg "Proceeding to payment")

![](images/ecommpay/en_pp_visa_instalments_2.svg "Entering the card number")

![](images/ecommpay/en_pp_visa_instalments_3.svg "Notification about determining eligibility for Visa Instalments")

![](images/ecommpay/en_pp_visa_instalments_4.svg "Visa Instalments eligibility determined")

![](images/ecommpay/en_pp_visa_instalments_5.svg "Available instalments plans")

![](images/ecommpay/en_pp_visa_instalments_6.svg "Selecting an instalments plan")

![](images/ecommpay/en_pp_visa_instalments_7.svg "Confirming the payment")

![](images/ecommpay/en_pp_visa_instalments_8.svg "Payment complete")

The scenario has the following steps:

1.  A customer initiates a purchase in the web service.
2.  The customer selects the payment method in the payment form and enters the card number.
3.  The customer is shown **Checking instalment eligibility**—a notification that their eligibility for paying in instalments is being determined \(because for the project in use the Visa Instalments capability is supported\).
4.  Once the eligibility has been determined, the customer is shown a corresponding notification. Then the customer enters the rest of the card details if necessary and proceeds to the next step.
5.  The customer is shown available instalments plans, together with the option to pay for the purchase in full amount at once \(without splitting it into parts\).
6.  The customer selects an instalments plan most fitting to their needs and proceeds to the next step. If at this step the customer requires additional information about Visa Instalments, they can use the **Learn more** link \(clicking which opens a pop-up window with the option overview\).
7.  The customer reviews the instalments plan terms and conditions and accepts them by confirming the payment.
8.  The customer is shown the preloader page and then the payment complete page.

When the payment has been processed, the information about the terms of the instalments plan is provided to the customer in the receipt \(sent to the email or the phone\).In addition to the data contained in a standard receipt, this receipt will contain:

-   Number of instalments
-   Total purchase amount with fees
-   Total fees amount
-   Applied annual percentage rate \(APR\)
-   Monthly payment amount

![](images/ecommpay/en_pp_visa_instalments_receipt.svg "Receipt with instalments plan information")

## Purchases by using Payment Page {#en_pm_instalments_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pagewith the Visa Instalments functionality, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.In case of a two-step purchase, it can be required, at a later point, to send the request for capturing the held funds. The full sequence and special aspects of one-step purchase processing are provided below.

![](images/ecommpay/en_instalments_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for purchase processing to the specified Ecommpay URL via Payment Page.
3.  The request for purchase processing is received by the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects payment method and enters the card details.
8.  The request for checking instalment eligibility is sent to the payment platform.
9.  The payment platform processes the request and sends it to the payment environment.
10. The request is processed on the payment environment side.
11. The information about available instalments plans is sent to the payment platform from the payment environment.
12. The payment platform sends the information about available instalments plans to Payment Page.
13. The information about available instalments plans is displayed to the customer on Payment Page.
14. The customer selects the instalments plan and proceeds with payment.
15. The payment platform receives the request for processing a Visa Instalments payment.
16. The payment platform processes the request and sends it to the payment environment.
17. The purchase is processed on the payment environment side.
18. The notification about the purchase result is sent to the payment platform from the payment environment.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

In case of a two-step purchase, the process of placing the authorisation hold via Payment Page is identical to the workflow sequence of a one-step purchase, with the exception that instead of an immediate debiting of funds an authorisation hold is initiated and executed.

Information about the formats of requests and callbacks used for processing payments in instalments enabled by Visa via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

Since payments in instalments enabled by Visa essentially extend the functionality of standard card payments, the request format for such payments corresponds to the format used for standard card payments and follows the requirements and recommendations for parameters listed in the [Purchase processing](en_pp_purchase.md) and [Authorisation hold](en_pp_purchase_auth.md) articles.

There are several things you need to consider when sending requests for opening Payment Page:

1.  The following parameters required for any payment must be specified:

-   `project_id`—project identifier obtained from Ecommpay during integration
-   `payment_id`—payment identifier unique within the project
-   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
-   `payment_amount`—payment amount in the smallest currency unit
-   `customer_id`—customer identifier unique within the project
2.  To specify the type of purchase that is different from the default one set for the specific project, pass `sale` \(for immediate withdrawal of funds during one-step purchase processing\) or `auth` \(to place an authorisation hold during two-step purchase processing\) in the `operation_type` parameter.
3.  Additionally, it is recommended that you specify the postal code and customer's address in the `avs_post_code` and `avs_street_address` parameters. If either of these parameters is missing, the payment form may display input fields for entering the missing values \(learn more in [Checking with Address Verification Service](en_PP_avs.md) and [Submission of additional payment information](en_pp_clarification.md)\).
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all necessary parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using Visa Instalments must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier, and signature, and can include other additional parameters if needed.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 60000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 60000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The standard format of callbacks is used for delivering the result of processing the Visa Instalments purchase. For more information, see [Handling callbacks](en_platform_callbacks.md).

Information about the instalments plan selected by the customer is specified in the `installment_plan` object passed in the final callback. Including this object in the callback payload is set up with the Ecommpay support specialists.

``` {#codeblock_ahj_qql_rgc .language-json}
{
    "installment_plan": {
        "payment_frequency": "M",
        "payment_count": 9,
        "cost": {
            "currency": "GBP",
            "total_cost": 60000,
            "total_fee_amount": 3825,
            "regular_payment": {
                "total_amount": 7092
            },
            "first_payment": {
                "total_amount": 7092
            },
            "last_payment": {
                "total_amount": 7089
            },
            "annual_percentage_rate": 8.5
        },
        "reference": "Y38135539",
        "terms_and_conditions": {
            "text": "text_eng",
            "url": "https://www.fornaxbank.co.uk"
        }
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase processing](en_pp_purchase.md)—about processing one-time one-step purchases with immediate debiting of funds via Payment Page.
-   [Authorisation hold](en_pp_purchase_auth.md)—about processing one-time two-step purchases with debiting of funds after placing an authorisation hold via Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_instalments_dash_analysis}

To analyse information about Visa Instalments purchases, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Bank payments {#en_pm_bankpayments}

Articles about bank payments that involve the transfer of funds with the use of the specialised online services of different banks.

*Bank payments or Banking*—payments that are carried out with the use of the specialised online services of different bankswhich allow transferring funds between the customer and the merchant \(directly or via the account of the provider\). The payment instrument in this case is the customer's bank account, while the payment processing scenarios may involve the online banking technologies, bank transfers, and other bank services.

Payment methods of this type include:

-   [Bancontact](pm_bancontact.md)
-   Banks of South-East Asia:
    -   [Banks of Hong Kong](pm_hk_banks.md)
    -   [Banks of the Philippines](pm_philippines.md)
    -   [Indonesian Online Banking](pm_indonesia.md)
    -   [Malaysian Online Banking](pm_malaysia.md)
    -   [Thai Online Banking](pm_thailand.md)
    -   [Vietnamese Online Banking](pm_vietnam.md)
-   [Blik](pm_blik.md)
-   [Brazil Online Banking](pm_brazil_ob.md)
-   [Buy Now Pay Later](pm_bnpl.md)
-   [Chile Online Banking](pm_chile_ob.md)
-   [China UnionPay](pm_unionpay.md)
-   [Direct Debit BACS](pm_dd_bacs.md)
-   [Direct Debit SEPA](pm_dd_sepa.md)
-   [Ecuador Online Banking](pm_ecuador_ob.md)
-   [EPS](pm_eps.md)
-   European Open Banking\([methods group](pm_openbanking.md)\):

    |    -   [Austria](pm_austria.md)
    -   [Belgium](pm_belgium.md)
    -   [Estonia](pm_estonia.md)
    -   [Finland](pm_finland.md)
    -   [France](pm_france.md)
    -   [Germany](pm_germany.md)
    -   [Hungary](pm_hungary.md)
    -   [Italy](pm_italy.md)
    -   [Ireland](pm_ireland.md)
    -   [Latvia](pm_latvia.md)
|    -   [Lithuania](pm_lithuania.md)
    -   [Netherlands](pm_netherlands.md)
    -   [Norway](pm_norway.md)
    -   [Poland](pm_poland.md)
    -   [Portugal](pm_portugal.md)
    -   [Romania](pm_romania.md)
    -   [Spain](pm_spain.md)
    -   [Sweden](pm_sweden.md)
    -   [United Kingdom](pm_uk.md)
| | |

-   [iDEAL \| Wero](pm_ideal.md)
-   [Indonesian Virtual Accounts](pm_indonesia_va.md)
-   [Local payouts to bank accounts in the UK](pm_bankpayout_uk.md)
-   [Mexico Online Banking](pm_mexico_ob.md)
-   [Multibanco](pm_multibanco.md)
-   [MyBank](pm_mybank.md)
-   [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)
-   [Peru Online Banking](pm_peru_ob.md)
-   [Philippines Over the Counter & ATM](pm_philippines_atm.md)
-   [PIX](pm_pix.md)
-   [Przelewy24](pm_przelewy.md)
-   [Swish](pm_swish.md)

-   **[Bancontact](pm_bancontact.md)**  
An article about the payment method which allows you to process payments in euros by using payment cards in Belgium and supports purchases and refunds.
-   **[Banks of Hong Kong](pm_hk_banks.md)**  
An article about the payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong and supports payouts.
-   **[Banks of the Philippines](pm_philippines.md)**  
An article about the payment method which allows you to process payments in Philippine pesos by using bank accounts in the Philippines and supports purchases and payouts.
-   **[Blik](pm_blik.md)**  
An article about the payment method which allows you to process payments in zloty by using bank accounts in Poland and supports purchases and refunds.
-   **[Brazil Online Banking](pm_brazil_ob.md)**  
An article about the payment method which allows you to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and refunds.
-   **[Buy Now Pay Later](pm_bnpl.md)**  
An article about the payment method which allows you to process installment payments in pounds sterling in the United Kingdom and supports purchases.
-   **[Chile Online Banking](pm_chile_ob.md)**  
An article about the payment method which allows you to process payments in Chilean pesos and US dollars by using bank accounts in Chile and supports purchases and refunds.
-   **[China UnionPay](pm_unionpay.md)**  
An article about the payment method which allows you to process payments in different currencies by using payment cards in different countries and supports purchases and refunds.
-   **[Direct Debit BACS](pm_dd_bacs.md)**  
An article about the payment method which allows you to process payments in pounds by using bank accounts in the United Kingdom and supports COF purchases and refunds.
-   **[Direct Debit SEPA](pm_dd_sepa.md)**  
An article about the payment method which allows you to process payments in euros by using bank accounts in the SEPA countries and supports COF purchases and refunds.
-   **[Ecuador Online Banking](pm_ecuador_ob.md)**  
An article about the payment method which allows you to process payments in US dollars by using bank accounts in Ecuador and supports purchases and refunds.
-   **[EPS](pm_eps.md)**  
An article about the payment method which allows you to process payments in euros by using bank accounts in Austria and supports purchases.
-   **[iDEAL \| Wero](pm_ideal.md)**  
An article about the payment method which allows to process payments in euros by using bank accounts in the Netherlands and supports purchases and refunds.
-   **[Indonesian Online Banking](pm_indonesia.md)**  
An article about the payment method which allows to process payments in Indonesian rupiahs by using bank accounts in Indonesia and supports purchases and payouts.
-   **[Indonesian Virtual Accounts](pm_indonesia_va.md)**  
An article about the payment method which allows to process payments in Indonesian rupiahs by using cash, bank accounts, and payment cards in Indonesia and supports purchases.
-   **[Local payouts to bank accounts in the UK](pm_bankpayout_uk.md)**  
An article about the payment method which allows you to process payments in pounds sterling by using bank accounts in the UK and supports payouts.
-   **[Malaysian Online Banking](pm_malaysia.md)**  
An article about the payment method which allows to process payments in Malaysian ringgits by using bank accounts in Malaysia and supports purchases and payouts.
-   **[Mexico Online Banking](pm_mexico_ob.md)**  
An article about the payment method which allows you to process payments in Mexican pesos and US dollars by using bank accounts in Mexico and supports purchases and refunds.
-   **[Multibanco](pm_multibanco.md)**  
An article about the payment method which allows you to process payments in euros by using bank accounts in Portugal and supports purchases.
-   **[MyBank](pm_mybank.md)**  
An article about the payment method which allows you to process payments in euros by using bank accounts in different European countries and supports purchases and refunds.
-   **[Open Banking](pm_openbanking.md)**  
An article about the group of internet banking methods which are based on the use of open banking protocols and allow processing payments in euros and a number of other European currencies through various banks in Europe by using bank accounts.
-   **[Open Banking in Austria](pm_austria.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Austria.
-   **[Open Banking in Belgium](pm_belgium.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Belgium.
-   **[Open Banking in Denmark](pm_denmark.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Denmark.
-   **[Open Banking in Estonia](pm_estonia.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Estonia.
-   **[Open Banking in Finland](pm_finland.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Finland.
-   **[Open Banking in France](pm_france.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of France.
-   **[Open Banking in Germany](pm_germany.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Germany.
-   **[Open Banking in Hungary](pm_hungary.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in forints via the banks of Hungary.
-   **[Open Banking in Italy](pm_italy.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Italy.
-   **[Open Banking in Ireland](pm_ireland.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Ireland.
-   **[Open Banking in Latvia](pm_latvia.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Latvia.
-   **[Open Banking in Lithuania](pm_lithuania.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Lithuania.
-   **[Open Banking in Luxembourg](pm_luxembourg.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Luxembourg.
-   **[Open Banking in the Netherlands](pm_netherlands.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of the Netherlands.
-   **[Open Banking in Norway](pm_norway.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Norwegian kroner via the banks of Norway.
-   **[Open Banking in Poland](pm_poland.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in zloty via the banks of Poland.
-   **[Open Banking in Portugal](pm_portugal.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Portugal.
-   **[Open Banking in Romania](pm_romania.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in lei via the banks of Romania.
-   **[Open Banking in Spain](pm_spain.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Spain.
-   **[Open Banking in Sweden](pm_sweden.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Swedish kronor via the banks of Sweden.
-   **[Open Banking in the UK](pm_uk.md)**  
An article about the internet banking method which belongs to the Open Banking group and allows processing payments in pounds sterling via the banks of the United Kingdom.
-   **[Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)**  
An article about the payment method which allows you to process payments in euros by using bank accounts in SEPA countries and supports payouts.
-   **[Peru Online Banking](pm_peru_ob.md)**  
An article about the payment method which allows you to process payments in Peruvian sols and US dollars by using bank accounts in Peru and supports purchases and refunds.
-   **[Philippines Over the Counter & ATM](pm_philippines_atm.md)**  
An article about the payment method which allows you to process payments in Philippine pesos by using payment cards and cash in the Philippines and supports purchases.
-   **[PIX](pm_pix.md)**  
An article about the payment method which allows to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and payouts.
-   **[Przelewy24](pm_przelewy.md)**  
An article about the payment method which allows you to process payments in euros and zlotys by using bank accounts and payment cards in Poland and supports purchases and refunds.
-   **[Swish](pm_swish.md)**  
An article about the payment method which allows you to process payments in Swedish kronor by using bank accounts in Sweden and supports purchases and refunds.
-   **[Thai Online Banking](pm_thailand.md)**  
An article about the payment method which allows to process payments in Thai bahts by using bank accounts in Thailand and supports purchases and payouts.
-   **[Vietnamese Online Banking](pm_vietnam.md)**  
An article about the payment method which allows to process payments in Vietnamese dongs by using bank accounts in Vietnam and supports purchases and payouts.

**Parent topic:**[Payment methods](en_pm_about.md)



---

# Bancontact {#pm_bancontact}

An article about the payment method which allows you to process payments in euros by using payment cards in Belgium and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_bancontact_overview}

### Introduction {#section_t5z_rlg_ytb .section}

Bancontact is a payment method which allows you to process payments in euros by using payment cards in Belgium.This method supports purchasesand refunds.

This article provides information about working with the Bancontact method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|payments cards|
|Countries and regions|[BE](references/en/countries/BE.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|if the payment amount exceeds 500.00 [EUR](references/en/currencies/EUR.md), then the Bancontact mobile application can't be used for purchase processing|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/bancontact/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Bancontact method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the Bancontact service.

![](images/pm/eng_bancontact_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Bancontact method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [EUR](references/en/currencies/EUR.md)|Times¹|
|minimum|maximum|basic|threshold|
|--|-----------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|1.00|–|–|30 days|
|Refunds|–|–|–|–|

**Note:**

1.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Bancontact method, you need to redirect the customer to the Bancontact service,while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/eng_bancontact_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_bancontact_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/eng_bancontact_interfaces_gate_refund.svg "Refund by using Gate")

## Purchases by using Payment Page {#en_pm_bancontact_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Bancontact method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_bancontact_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Bancontact method.
8.  The payment platform receives the request for processing the payment by using the Bancontact method.
9.  The payment platform processes the request and sends it to the Bancontact service.
10. The request is processed on the Bancontact service side.
11. The data for redirecting the customer to the Bancontact service is sent from the Bancontact service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the Bancontact service.
14. The customer completes all required payment steps. If the payment amount is less than 500.00 [EUR](references/en/currencies/EUR.md), then the QR code is displayed to the customer \(fields for entering Bancontact card credentials are also displayed in this case\). The customer can scan the code by using the Bancontact mobile application. If the payment amount is exceeds 500.00 [EUR](references/en/currencies/EUR.md), then the QR code is not displayed and the purchase can't be processed by using the mobile application.
15. The purchase is processed in the Bancontact service.
16. The result information is displayed to the customer in the Bancontact service.
17. The customer is redirected to Payment Page.
18. The Bancontact service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Bancontact method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Bancontact method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the last name of the customer in the parameter `customer_last_name` \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\). If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  If you need to have the payment form displayed with the Bancontact method selected, set the `force_payment_method` parameter to `bancontact`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Bancontact method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and last name, as well as signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_last_name": "Johnson",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_last_name": "Johnson",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Bancontact method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `211` project.

```language-json
{
        "project_id": 211,
        "payment": {
            "id": "ECT_TEST_1562051806691899",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-02T09:28:29+0000",
            "method": "bancontact",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1562051806691810"
        },
        "customer": {
            "last_name": "Johnson"
        },
        "operation": {
            "id": 37493000003351,
            "type": "sale",
            "status": "success",
            "date": "2019-07-02T09:28:29+0000",
            "created_date": "2019-07-02T09:28:24+0000",
            "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1241,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "e7wGQAoo1wKMPwsJVCg4zwpWiZVR83hnRnYsIZ84g=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 211,
        "payment": {
            "id": "ECT_TEST_1562051806691810",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-02T09:28:29+0000",
            "method": "bancontact",
            "sum": {
                "amount": 50,
                "currency": "EUR"
            }
        },
        "customer": {
            "last_name": "Johnson"
        },
        "operation": {
            "id": 37493000003351,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-02T09:28:29+0000",
            "created_date": "2019-07-02T09:28:24+0000",
            "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c",
            "sum_initial": {
                "amount": 50,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 50,
                "currency": "EUR"
            },
            "provider": {
                "id": 1241,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "e7wGQAoo1wKMPwsJVCghpAH3AqwpWiZVR83hnRnYsIZ84g=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_bancontact_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Bancontact method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Bancontact service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_bancontact_uml_gate.svg)

1.  A customer initiates a purchase by using the Bancontact method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Bancontact service.
7.  The request is processed on the Bancontact service side.
8.  The Bancontact service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the Bancontact service.
11. The customer completes all required payment steps. If the payment amount is less than 500.00 [EUR](references/en/currencies/EUR.md), then the QR code is displayed to the customer \(fields for entering Bancontact card credentials are also displayed in this case\). The customer can scan the code by using the Bancontact mobile application. If the payment amount is exceeds 500.00 [EUR](references/en/currencies/EUR.md), then the QR code is not displayed and the purchase can't be processed by using the mobile application.
12. The purchase is processed in the Bancontact service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The Bancontact service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Bancontact method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Bancontact method:

1.  To initiate each purchase, send a separate POST request to the `[/v2/payment/bancontact/sale](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bancontact-sale)` endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\). If the parameter is not specified in the request, a callback containing this parameter is sent for additional payment information submission \(for more details, see [Submission of additional payment information](en_Gate_Clarification.md)\)
    -   Object `return_url`—contains the URLs to which customer is redirected while or after payment processing:
        -   `return`—URL to return customer to the web service during any step before the payment is completed with a click of the return button.
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Bancontact method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier, IP address and last name, as well as URL for redirection and signature.

```language-json
{
    "general": {
      "project_id": 211,
      "payment_id": "payment_id",
      "signature": "PLwY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "customer": {
      "last_name": "Johnson",
      "id": "123",
      "ip_address": "192.0.2.0"
    },
    "return_url": {
      "return": "http://example.com/return"
    }  
}
```

```language-json
{
    "general": {
      "project_id": 211,
      "payment_id": "payment_id",
      "signature": "PLwY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "customer": {
      "last_name": "Johnson",
      "id": "123",
      "ip_address": "192.0.2.0"
    },
    "return_url": {
      "return": "http://example.com/return"
    }  
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Bancontact method requires redirection of customers from the merchant's web service to the Bancontact service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
"redirect_data": {
      "body": [],
      "method": "GET",
      "url": "https://bancontact.girogate.be/bi/t0bc?tx=example
```

### Callback format {#section_wsx_3jl_ggb .section}

The Bancontact method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `211` project.

```language-json
{
        "project_id": 211,
        "payment": {
            "id": "ECT_TEST_1562051806691899",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-02T09:28:29+0000",
            "method": "bancontact",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1562051806691810"
        },
        "customer": {
            "last_name": "Johnson"
        },
        "operation": {
            "id": 37493000003351,
            "type": "sale",
            "status": "success",
            "date": "2019-07-02T09:28:29+0000",
            "created_date": "2019-07-02T09:28:24+0000",
            "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1241,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "e7wGQAoo1wKMPwsJVCg4zwpWiZVR83hnRnYsIZ84g=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 211,
        "payment": {
            "id": "ECT_TEST_1562051806691810",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-02T09:28:29+0000",
            "method": "bancontact",
            "sum": {
                "amount": 50,
                "currency": "EUR"
            }
        },
        "customer": {
            "last_name": "Johnson"
        },
        "operation": {
            "id": 37493000003351,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-02T09:28:29+0000",
            "created_date": "2019-07-02T09:28:24+0000",
            "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c",
            "sum_initial": {
                "amount": 50,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 50,
                "currency": "EUR"
            },
            "provider": {
                "id": 1241,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "e7wGQAoo1wKMPwsJVCghpAH3AqwpWiZVR83hnRnYsIZ84g=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_bancontact_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Bancontact method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/eng_bancontact_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Bancontact service.
7.  The refund is processed on the side of the Bancontact service.
8.  The Bancontact service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Bancontact method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Bancontact method:

1.  To initiate each refund, send a separate POST request to the `[/v2/payment/bancontact/refund](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bancontact-refund)` endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Bancontact method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Bancontact method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` refund made in the `211` project.

```
{
        "project_id": 211,
        "payment": {
            "id": "refund_02",
            "type": "purchase",
            "status": "refunded",
            "date": "2019-02-19T14:25:25+0000",
            "method": "bancontact",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "test_02"
        },
        "account": {
            "number": "035209875690435"
        },
        "operation": {
            "id": 14153000003282,
            "type": "refund",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "created_date": "2019-02-19T14:25:24+0000",
            "request_id": "9d11b2ca618ec3ba0f588af8af3c4fc9f5fa58f174",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1169,
                "payment_id": "105887607",
                "date": "2019-02-19T14:25:24+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "of8k9xerKSKpFBR4XL1QFaDH3p9ZYO56lCv+f1M0Sf/7eg=="
    }
```

The following is the example of a callback with information about a declined refund.

```language-json
{
        "project_id": 211,
        "payment": {
            "id": "refund_02",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "method": "bancontact",
            "sum": {
                "amount": 100000,
                "currency": "EUR"
            },
            "description": "test_02"
        },
        "account": {
            "number": "035209875690435"
        },
        "operation": {
            "id": 14153000003282,
            "type": "refund",
            "status": "decline",
            "date": "2019-02-19T14:25:25+0000",
            "created_date": "2019-02-19T14:25:24+0000",
            "request_id": "9d11b2ca618ec3ba0f588af8af3c4fc9f5fa58f174",
            "sum_initial": {
                "amount": 100000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1169,
                "payment_id": "105887607",
                "date": "2019-02-19T14:25:24+0000",
                "auth_code": ""
            },
            "code": "3283",
            "message": "Refund amount more than init amount"
        },
        "signature": "of8k9xerKSKpFwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_bancontact_dash_analysis}

To analyse information about payments made with the Bancontact method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Banks of Hong Kong {#pm_hk_banks}

An article about the payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong and supports payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_hk_banks_overview}

An article about the payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong and supports payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Banks of Hong Kong is a payment method which allows you to process payments in Hong Kong dollars and Chinese yuan by using bank accounts in Hong Kong.This method supports payouts.

This article provides information about working with the Banks of Hong Kong method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[HK](references/en/countries/HK.md)|
|Payment currencies|[HKD](references/en/currencies/HKD.md), [CNY](references/en/currencies/CNY.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Special considerations|–|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/bank-payouts-hong-kong/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Banks of Hong Kong method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_hk_banks_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Banks of Hong Kong method. Payouts can be processed by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following limitations are applicable.

| |Amounts, [HKD](references/en/currencies/HKD.md)|
|minimum|maximum|
|--|-----------------------------------------------|
|-------|-------|
|Payouts|–|4,000,000.00|

### Processing scenarios {#section_fgt_sdl_ggb .section}

To process a payout, you need to notify the customer via the web service.

![](images/pm/eng_hk_banks_interfaces_gate_payout.svg "Payout by using Gate")

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Ways of using bank identifiers are described in the next subsection, [Supported banks](pm_hk_banks.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of some banks supported by the Banks of Hong Kong method, the list may change without additional notice. For more details, see the [List of the supported banks](files_for_downloads/Banks%20of%20Hong%20Kong/pm_hk_banks_list.pdf). For the most recent list of supported banks, contact your Ecommpay Key Account Manager.

|Bank|ID|
|----|--|
|BANK OF CHINA \(HONG KONG\) LIMITED Cheung Chau Branch|54661|
|BANK OF COMMUNICATIONS CO., LTD. Hong Kong Branch|53911|
|CHANG HWA COMMERCIAL BANK LTD Hong Kong Branch|53121|
|CHINA CITIC BANK INTERNATIONAL LIMITED Mei Foo Branch|36991|
|CHINA CONSTRUCTION BANK \(ASIA\) CORPORATION LIMITED Hunghom Ma Tau Wai Road Branch|53571|
|CHONG HING BANK LTD Hong Kong Main Branch|31061|
|CHONG HING BANK LTD North Point Branch|54311|
|CIMB BANK BERHAD Hong Kong Branch|54021|
|CITIBANK \(HONG KONG\) LIMITED Mei Foo Sun Chuen Branch|54481|
|DAH SING BANK LTD Fortress Hill Branch|54071|
|DAH SING BANK LTD Tai Po Branch|53181|
|DBS BANK \(HONG KONG\) LIMITED Yaumatei Branch|54441|
|FUBON BANK \(HONG KONG\) LIMITED Chai Wan Branch|53851|
|FUBON BANK \(HONG KONG\) LIMITED Yuen Long Branch|48651|
|HANG SENG BANK LTD Fortune Kingswood Branch|35031|
|HANG SENG BANK LTD Tai Po Branch|54651|
|INDUSTRIAL AND COMMERCIAL BANK OF CHINA \(ASIA\) LTD Central Branch|54471|
|NANYANG COMMERCIAL BANK LTD Western Branch|54221|
|OCBC WING HANG BANK LIMITED Fortress Hill Branch|53031|
|PUBLIC BANK \(HONG KONG\) LIMITED Prince Edward Branch|53821|
|PUBLIC BANK \(HONG KONG\) LIMITED Tai Po Branch|44931|
|SHANGHAI COMMERCIAL BANK LTD Mongkok Branch|54511|
|SHANGHAI COMMERCIAL BANK LTD West Point Branch|54551|
|STANDARD CHARTERED BANK \(HONG KONG\) LIMITED Kwun Tong Branch|54011|
|TAI YAU BANK LTD Head Office|25681|
|THE BANK OF EAST ASIA, LTD Chai Wan Branch|43941|
|THE BANK OF EAST ASIA, LTD Main Branch|27401|
|THE HONGKONG AND SHANGHAI BANKING CORPORATION LTD Paterson Street HPC|54601|
|TMB BANK PUBLIC COMPANY LIMITED, HONG KONG Hong Kong Branch|54061|
|WING LUNG BANK LTD Happy Valley Branch|53991|

If you have any questions about working with banks supported by the Banks of Hong Kong method, refer to your Ecommpay account manager.

## Payout by using Gate {#en_pm_hk_banks_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Banks of Hong Kong method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/eng_hk_banks_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Banks of Hong Kong method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The payout is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Banks of Hong Kong method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Banks of Hong Kong method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/banks/hk/payout` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payout
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
        -   `number`—customer account number
        -   `customer_name`—customer name
3.  The currency of payment can only be [HKD](references/en/currencies/HKD.md) or [CNY](references/en/currencies/CNY.md).
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Banks of Hong Kong method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, as well as account information and signature.

```language-json
{
    "general": {
      "project_id": 383000,
      "payment_id": "12278b5d662764c9506b4db9df8c5c35",
      "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w=="
    },
    "customer": {
      "id": "fr-2374245",
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 10000,
      "currency": "HKD"
  },
    "account": {
      "bank_id": 22791,
      "number": "1234567890",
      "customer_name": "John Doe"
  }
}
```

```language-json
{
    "general": {
      "project_id": 383000,
      "payment_id": "12278b5d662764c9506b4db9df8c5c35",
      "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w=="
    },
    "customer": {
      "id": "fr-2374245",
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 10000,
      "currency": "HKD"
  },
    "account": {
      "bank_id": 22791,
      "number": "1234567890",
      "customer_name": "John Doe"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Banks of Hong Kong method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 HKD` payout made for the `customer3` customer in the `789` project.

```language-json
{
        "project_id": 789,
        "payment": {
            "id": "ABC1234321",
            "type": "payout",
            "status": "success",
            "date": "2021-04-26T08:41:59+0000",
            "method": "hk",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "account": {
            "number": "1234567"
        },
        "customer": {
            "id": "customer3"
        },
        "operation": {
            "id": 4348000010681,
            "type": "payout",
            "status": "success",
            "date": "2021-04-26T08:41:59+0000",
            "created_date": "2021-04-26T08:41:54+0000",
            "request_id": "3d7ef0727decad0829d608cabd0f8a6d96fbd3a...006256",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5181,
                "payment_id": "aff0b...cf9f2cd",
                "auth_code": "",
                "date": "2021-04-26T08:41:55+0000"
            }
        },
        "signature": "1L2fmnHY/51dZPI1j/IVa9LqzEPR67j9pPghn...c545R1xsGzw0zQ=="
    }
}
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 0123,
        "payment": {
            "id": "ABC1234567",
            "type": "payout",
            "status": "decline",
            "date": "2021-04-26T08:41:59+0000",
            "method": "hk",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "account": {
            "number": "123456789"
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 4348000010681,
            "type": "payout",
            "status": "decline",
            "date": "2021-04-26T08:41:59+0000",
            "created_date": "2021-04-26T08:41:54+0000",
            "request_id": "a19b65b2463fa7377f518d49674275cbaa4397a7...004349",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5181,
                "payment_id": "aff0b...cf9f2cd",
                "auth_code": "",
                "date": "2021-04-26T08:41:55+0000"
            }
        },
        "signature": "eQxj9hXHVWFBDMcko2Tj0071CvnFPsp...A9CchCgVr/Hqbu6w=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Banks of Hong Kong method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_hk_banks.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payment results {#en_pm_hk_banks_dash_analysis}

To analyse information about payments made with the Banks of Hong Kong method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Banks of the Philippines {#pm_philippines}

An article about the payment method which allows you to process payments in Philippine pesos by using bank accounts in the Philippines and supports purchases and payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_philippines_overview}

An article about the payment method which allows you to process payments in Philippine pesos by using bank accounts in the Philippines and supports purchases and payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Banks of the Philippines is a payment method which allows you to process payments in Philippine pesos by using bank accounts in the Philippines.This method supports purchasesand payouts.

This article provides information about working with the Banks of the Philippines method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PH](references/en/countries/PH.md)|
|Payment currencies|[PHP](references/en/currencies/PHP.md)|
|Currency conversion|available only for purchases—on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|+|
|Chargebacks|–|
|Notes|-   additional parameters can be specified while generating Payment Page
-   full and partial refunds are available only directly from the provider service

|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/online-banking-philippines/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Banks of the Philippines method involves the merchant's web service, one of the Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of one of the bank services which works with this payment method.

![](images/pm/eng_banksphilippines_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Banks of the Philippines method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), payouts—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [PHP](references/en/currencies/PHP.md)|Times¹|
|minimum|maximum|basic|threshold|
|--|-----------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|1.00|1,000,000.00|30 minutes|1 day|
|Refunds|\*|\*|\*|\*|
|Payouts|10.00|100, 000.00|up to 10 minutes|48 hours|

\* To request a full or partial refund, customer needs to submit [the online refund form](https://www.dragonpay.ph/refund).

**Note:**

1.  2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Banks of the Philippines method, you need to redirect the customer to the Banks of the Philippines service, to process a payout, you need to notify the customer via the web service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_4.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_5.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_6.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_philippines_7.svg "Redirecting to the web service")

General scenarios of processing purchasesand payouts can be presented as follows.

![](images/pm/eng_banksphilippines_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_banksphilippines_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_banks_overview_gate_payout.svg "Payout by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_philippines.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_philippines.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of banks supported by the Banks of the Philippines method. Each of banks has its own ID that identifies the bankin the request of payout by using Gate, as well as each of banks hasits own code that identifies the bank in callbacks.

|Bank|Purchase|Payout|ID|Code|
|----|--------|------|--|----|
|AUB Online/Cash Payment|–|+|485|AUB|
|Bank of Commerce|+|+|1561|BOC|
|BDO Corporate Internet Banking|+|–|2241|BDOC|
|BDO Internet Banking|+|+|486|BDO|
|BDO Internet Banking \(Bills Payment\)|+|–|2231|BDOP|
|BDO Mobile Internet Banking|+|–|2251|BDOM|
|BPI ExpressOnline/Mobile \(Fund Transfer\)|+|+|487|BPI|
|BPI ExpressOnline/Mobile \(new\)|+|–|2261|BPIA|
|BPI ExpressOnline \(Bills Payment\)|+|–|2271|BPIB|
|BPI Family Bank|–|+|488|BFB|
|Chinabank Online|+|+|489|CBC|
|Chinabank Savings|–|+|1531|CBCS|
|Chinatrust|–|+|1571|CTBC|
|EastWest CA/SA|–|+|490|EWB|
|Landbank ATM Online|+|–|2291|LBPA|
|Landbank CA/SA|–|+|491|LBP|
|Maybank|–|+|1541|MAY|
|Maybank Online Banking|+|–|2281|MAYB|
|Metrobankdirect|+|+|492|MBTC|
|PBCom|–|+|1511|PBCM|
|PNB E-Banking|–|+|493|PNB|
|PNB e-Banking Bills Payment|+|–|2301|PNBB|
|PSBank|–|+|1501|PSB|
|RCBC Online Banking|+|+|494|RCBC|
|RobinsonsBank Online Bills Payment|+|+|495|RSB|
|Security Bank Online Transfer|+|+|496|SBC|
|Sterling Bank|–|+|1551|SBA|
|UCPB Connect|+|+|498|UCPB|
|Unionbank CA/SA, EON|–|+|497|UBP|
|Unionbank EON|+|–|2321|UBE|
|Unionbank Internet Banking|+|–|2311|UBPB|
|Veterans Bank|–|+|1521|PVB|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/philippines/payout/list`\(for payouts\) or `/v2/info/banks/philippines/sale/list` \(for purchases\) endpoints to obtain up-to-date information. These endpoints belong to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP"
  }
}
```

If you have any questions about working with banks supported by the Banks of the Philippines method, refer to your Ecommpay account manager.

```language-json
[
  {
    "id": 2241, // Bank ID
    "abbr": "BDOC", // Bank abbreviation (for internal use)
    "name": "BDO Corporate Internet Banking", // International bank name
    "nativeName": "BDO Corporate Banking", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 1076, // Currency ID in the payment platform
        "alpha_3_4217": "PHP", // ISO-4217 alphabetic currency code
        "number_3_4217": "608", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 1571, 
    "abbr": "CTBC", 
    "name": "Chinatrust", 
    "nativeName": "Chinatrust",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2241, 
    "abbr": "MAY", 
    "name": "Maybank", 
    "nativeName": "Maybank",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  }
]
```

## Purchases by using Payment Page {#en_pm_philippines_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Banks of the Philippines method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result. At the same time, various options are available for choosing a method and a bank by specifying the appropriate parameters in requests.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_banksphilippines_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Banks of the Philippines method.
8.  The payment platform receives the request for processing the payment by using the Banks of the Philippines method.
9.  The payment platform processes the request and sends it to the bank service.
10. The request is processed on the bank service side.
11. The data for redirecting the customer to the bank service is sent from the bank service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to bank.
13. The customer is redirected to the bank service.
14. The customer completes all required payment steps.
15. The purchase is processed in the bank service.
16. The result information is displayed to the customer in the bank service.
17. The customer is redirected to Payment Page.
18. The bank service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Banks of the Philippines method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_philippines.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_asian_banking_pp_1_philippines.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_asian_banking_pp_2_philippines.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_asian_banking_pp_4_philippines.svg "3—Selecting bank among all available banks")

![](images/universal/pm/splits/en_asian_banking_pp_5_philippines.svg "4—Selecting bank among specific banks")

![](images/universal/pm/splits/en_asian_banking_pp_6_philippines.svg "5—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Banks of the Philippines method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Banks of the Philippines method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the e-mail address of the customer in the parameter `customer_email`. It may also be required to specify customer first name in the `customer_first_name` parameter and customer last name in the `customer_last_name` parameter. Refer to your Ecommpay key account manager for more information on the necessity of using these parameters. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option in the `payment_methods_options` object specify the `online_philippines_banks` object containing the `split_banks` parameter with the value `true`:

        ```language-json
        "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true}}"
        ```

    3.  *Selecting a bank among all available ones on Payment Page \(3\)*—for this option specify the method code `online-philippines-banks` in the `force_payment_method` parameter.
    4.  *Selecting a bank among specific ones on Payment Page \(4\)*—for this option specify the following:
        -   the online-philippines-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_philippines_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifiers:

            ```language-json
            "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261, 2271]}}"
            ```

    5.  *Confirming redirection to the service of the specific bank on Payment Page \(5\)*—for this option specify the following:
        -   the online-philippines-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_philippines_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifier:

            ```language-json
            "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261]}}"
            ```

4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Banks of the Philippines method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "online-philippines-banks",
   "payment_methods_options": {"online_philippines_banks": {"split_banks": true, "banks_id": [2261, 2271]}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Banks of the Philippines method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PHP` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_philippines_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Banks of the Philippines method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the bank service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_banksphilippines_uml_gate.svg)

1.  A customer initiates a purchase by using the Banks of the Philippines method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The request is processed on the bank service side.
8.  The bank service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the bank service.
11. The customer completes all required payment steps.
12. The purchase is processed in the bank service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The bank service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Banks of the Philippines method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Banks of the Philippines method:

1.  To initiate each purchase, send a separate POST request to the `v2/payment/banks/philippines/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `email`—customer email address
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—information on the bank:
        -   `bank_id`—bank identifier
    -   Object `return_url`—contains the URLs to which customer is redirected during or after payment processing:
        -   `success`—URL for redirecting the customer after a successful payment.
3.  It may also be required to specify the first name and the last name of the customer in the corresponding parameters:

    -   Object `customer`—customer information:
        -   `first_name`—customer first name
        -   `last_name`—customer last name
    Refer to your Ecommpay key account manager for more information on the necessity of using these parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission \(details are available in [Submission of additional payment information](en_Gate_Clarification.md)\).

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Banks of the Philippines method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, bank ID and URL for redirection, as well as signature.

```language-json
{
    "general": {
        "project_id": 580,
        "payment_id": "test_philippines_sale",
        "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "id": "123",
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}
```

```language-json
{
    "general": {
        "project_id": 580,
        "payment_id": "test_philippines_sale",
        "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "id": "123",
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Banks of the Philippines method requires redirection of customers from the merchant's web service to the bank service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
"redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Banks of the Philippines method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PHP` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Gate {#en_pm_philippines_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Banks of the Philippines method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/en_banks_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Banks of the Philippines method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The payout is processed on the side of the bank service.
8.  The bank service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Banks of the Philippines method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Banks of the Philippines method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/banks/philippines/payout` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
        -   `description`—payout description
    -   `customer`—object that contains customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payout
    -   Object `account`—customer account information:
        -   `bank_id`—bank ID
        -   `customer_name`—bank account holder's name
        -   `number`—customer account number
3.  The currency of payout can only be [PHP](references/en/currencies/PHP.md).
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Banks of the Philippines method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and account information, as well as signature.

```language-json
{
  "general": {
    "project_id": 445,
    "payment_id": "1000003",
    "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA=="
  },
 "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP",
    "description": "Payout description"
  },
    "account": {
    "bank_id": 486,
    "customer_name": "John Doe",
    "number": "1670033323"
  }
}
```

```language-json
{
  "general": {
    "project_id": 445,
    "payment_id": "1000003",
    "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA=="
  },
 "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP",
    "description": "Payout description"
  },
    "account": {
    "bank_id": 486,
    "customer_name": "John Doe",
    "number": "1670033323"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

In the Banks of the Philippines method, the callbacks that deliver payout results use the standard format described in [Handling callbacks](en_platform_callbacks.md).

Note that unlike other payment methods, in the Banks of the Philippines method, the callbacks contain the name of bank passed in the `endpoint_id` parameter of the `operation.provider` object. \(For more detailed information about banks and their codes, see [Supported banks](pm_philippines.md#section_rqp_zdl_ggb).\)

The following is the example of a callback with information about a `10.00 PHP` payout made for account `1670033323` of the `Banco de Oro CA/SA` bank for the `123` customer in the `445` project.

```language-json
 {
        "project_id": 445,
        "payment": {
            "id": "100011",
            "type": "payout",
            "status": "success",
            "date": "2019-03-18T08:06:13+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "payout"
        },
        "account": {
            "number": "1670033323"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 147,
            "type": "payout",
            "status": "success",
            "date": "2019-03-18T08:06:13+0000",
            "created_date": "2019-03-18T08:06:06+0000",
            "request_id": "9499286583e3d1102f752a9cd47d2fb7469cc613e11",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1346,
                "payment_id": "6Q2G5D83",
                "date": "2019-03-18T08:06:11+0000",
                "auth_code": "",
                "endpoint_id": "BDO"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "oFGfjOtZZkFxi7Pd1yikCw01b0BsedgKr8z/E8qfizh1A=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 445,
        "payment": {
            "id": "100014",
            "type": "payout",
            "status": "decline",
            "date": "2019-03-18T10:49:50+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 900,
                "currency": "PHP"
            },
            "description": "payout"
        },
        "account": {
            "number": "1670033323"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 148,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-18T10:49:51+0000",
            "created_date": "2019-03-18T10:49:46+0000",
            "request_id": "d626cece0855a8863f687985e6c57935d9872183c",
            "sum_initial": {
                "amount": 900,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 900,
                "currency": "PHP"
            },
            "provider": {
                "id": 1346,
                "payment_id": "YDK0QS4X",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "fz0Yu5BFLRLJez747kDfZHgmKGIOgMa5DAzPE/4GLWlZSzCwkdkqyrTqUQvLp6A=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Banks of the Philippines method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_philippines.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_philippines_dash_analysis}

To analyse information about payments made with the Banks of the Philippines method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Blik {#pm_blik}

An article about the payment method which allows you to process payments in zloty by using bank accounts in Poland and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_blik_overview}

An article about the payment method which allows you to process payments in zloty by using bank accounts in Poland and supports purchases and refunds.

### Introduction {#section_ccc_vk1_rvb .section}

Blik is a payment method which allows you to process payments in zloty by using bank accounts in Poland.This method supports purchasesand refunds.

This article provides information about working with the Blik method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PL](references/en/countries/PL.md)|
|Payment currencies|[PLN](references/en/currencies/PLN.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|the way of opening a payment form on the Blik website—any way except an iframe object|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/blik/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Blik method involves the merchant's web service, one of Ecommpay interfaces,and the Ecommpay payment platform, and technical facilities of the Blik service.

![](images/pm/eng_blik_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Blik method. Purchases can be processed by using Payment Page, Gate and Dashboard\(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable to all operations.

| |Amounts, [PLN](references/en/currencies/PLN.md) ¹|Times ²|
|minimum|maximum|basic|threshold|
|--|-------------------------------------------------|-------|
|-------|-------|-----|---------|
|Purchases|0.01|10 000.00\*|\*|\*|
|Refunds|–|–|–|–|

**Note:**

1.  Amount limits and payment processing times depend on banks.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Blik method, you need to redirect the customer to the Blik service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/eng_blik_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_blik_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/eng_blik_interfaces_gate_refund.svg "Refund by using Gate")

## Purchase by using Payment Page {#en_pm_blik_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Blik method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_blik_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Blik method.
8.  The payment platform receives the request for processing the payment by using the Blik method.
9.  The payment platform processes the request and sends it to the Blik service.
10. The request is processed on the Blik service side.
11. The data for redirecting the customer to the Blik service is sent from the Blik service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the Blik service.
14. The customer completes all required payment steps.
15. The purchase is processed in the Blik service.
16. The result information is displayed to the customer in the Blik service.
17. The customer is redirected to Payment Page.
18. The Blik service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Blik method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Blik method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is recommended to specify the first, last names and e-mail address of the customer in the `customer_first_name`, `customer_last_name` and `customer_email` parameters. To avoid errors during payment processing it is recommended to use from 3 to 100 characters when specifying the value of the `customer_first_name`and `customer_last_name` parameters. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  The currency of payment can only be [PLN](references/en/currencies/PLN.md).
4.  If you need to have payment form displayed with the Blik method selected, set the `force_payment_method` parameter to `blik`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Blik method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

``` {#codeblock_s3c_qpx_jgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "customer@example.com',
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_n22_qpx_jgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "customer@example.com',
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Blik method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `1.00 PLN` purchase made in the `423` project.

```language-json
{
        "project_id": 423,
        "payment": {
            "id": "03315",
            "type": "purchase",
            "status": "success",
            "date": "2022-05-12T14:32:59+0000",
            "method": "blik",
            "sum": {
                "amount": 100,
                "currency": "PLN"
            },
            "description": "PAYMENT_03315"
        },
            "customer": {
            "id": "11"
        },
        "operation": {
            "id": 50241,
            "type": "sale",
            "status": "success",
            "date": "2022-05-09T09:32:10+0000",
            "created_date": "2022-05-09T09:20:09+0000",
            "request_id": "6db6ed63860b74b33b0c870-00010993",
            "sum_initial": {
                "amount": 100,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "PLN"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 151,
                "payment_id": "8464654",
                "auth_code": ""
            }
        },
        "signature": "5xpLaag4iVH4p5poiI25KSUQWESwbgfpLZ/gVj4fWfTzVBg=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 423,
        "payment": {
            "id": "3614",
            "type": "purchase",
            "status": "decline",
            "date": "2022-05-16T08:16:29+0000",
            "method": "blik",
            "sum": {
                "amount": 100,
                "currency": "PLN"
            },
            "description": "PAYMENT_3614"
        }, 
        "customer": {
            "id": "11"
        },
        "operation": {
            "id": 73761,
            "type": "sale",
            "status": "decline",
            "date": "2022-05-16T08:16:29+0000",
            "created_date": "2022-05-16T08:06:20+0000",
            "request_id": "b4aa45de7042c95b992e9a5ab874bfbcf-00051169",
            "sum_initial": {
                "amount": 100,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "PLN"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 151,
                "payment_id": "600325",
                "auth_code": ""
            }
        },
        "signature": "wn7dHQhfVYLPZuVuzGfw1EJGZ5tHfS8oTW1EsxEhvJW6Tiw=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—how to organise interaction with the payment platform by using Payment Page
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_blik_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Blik method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Blik service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_blik_uml_gate.svg)

1.  A customer initiates a purchase by using the Blik method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Blik service.
7.  The request is processed on the Blik service side.
8.  The Blik service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the Blik service.
11. The customer completes all required payment steps.
12. The purchase is processed in the Blik service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The Blik service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Blik method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Blik method:

1.  To initiate each purchase, send a separate POST request to the [/v2/payment/blik/sale](https://api-developers.ecommpay.com/api-specification/blik/post-v2-payment-blik-sale) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  It is recommended to specify the last name and email address of the customer.

    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—email
    If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission \(details are available in [Submission of additional payment information](en_Gate_Clarification.md)\).

4.  If needed, you can also add URL for redirecting the customer to the web service:
    -   `return_url`—URL for redirecting the customer to the web service:
        -   `return`—URL for redirecting a customer while or after purchase performing.
5.  The currency of purchase can only be [PLN](references/en/currencies/PLN.md).
6.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Blik method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

``` {#codeblock_lnc_j4x_jgc .language-json}
{
    "general": {
      "project_id": 423,
      "payment_id": "5554",
      "signature": "PJkV8ej\/UG0Di8LwYipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 100,
      "currency": "PLN"
    },
    "customer": {
      "id": "123",
      "ip_address": "192.0.2.0",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Johnson"
    } 
}
```

``` {#codeblock_w3y_24x_jgc .language-json}
{
    "general": {
      "project_id": 423,
      "payment_id": "5554",
      "signature": "PJkV8ej\/UG0Di8LwYipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 100,
      "currency": "PLN"
    },
    "customer": {
      "id": "123",
      "ip_address": "192.0.2.0",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Johnson"
    } 
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Blik method requires redirection of customers from the merchant's web service to the Blik service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Blik method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `1.00 PLN` purchase made in the `423` project.

```language-json
{
        "project_id": 423,
        "payment": {
            "id": "03315",
            "type": "purchase",
            "status": "success",
            "date": "2022-05-12T14:32:59+0000",
            "method": "blik",
            "sum": {
                "amount": 100,
                "currency": "PLN"
            },
            "description": "PAYMENT_03315"
        },
            "customer": {
            "id": "11"
        },
        "operation": {
            "id": 50241,
            "type": "sale",
            "status": "success",
            "date": "2022-05-09T09:32:10+0000",
            "created_date": "2022-05-09T09:20:09+0000",
            "request_id": "6db6ed63860b74b33b0c870-00010993",
            "sum_initial": {
                "amount": 100,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "PLN"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 151,
                "payment_id": "8464654",
                "auth_code": ""
            }
        },
        "signature": "5xpLaag4iVH4p5poESwbgfpLZ/gVj4fWfTzVBg=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 423,
        "payment": {
            "id": "3614",
            "type": "purchase",
            "status": "decline",
            "date": "2022-05-16T08:16:29+0000",
            "method": "blik",
            "sum": {
                "amount": 100,
                "currency": "PLN"
            },
            "description": "PAYMENT_3614"
        }, 
        "customer": {
            "id": "11"
        },
        "operation": {
            "id": 73761,
            "type": "sale",
            "status": "decline",
            "date": "2022-05-16T08:16:29+0000",
            "created_date": "2022-05-16T08:06:20+0000",
            "request_id": "b4aa45de7042c95b992e9a5ab874bfbcf-00051169",
            "sum_initial": {
                "amount": 100,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "PLN"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 151,
                "payment_id": "600325",
                "auth_code": ""
            }
        },
        "signature": "wn7dHQhfVYLPZuVxZ5tHfS8oTW1EsxEhvJW6Tiw=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—how to organise interaction with the payment platform by using Gate
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_blik_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Blik method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/eng_blik_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Blik service.
7.  The refund is processed on the side of the Blik service.
8.  The Blik service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Blik method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Blik method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/blik/refund](https://api-developers.ecommpay.com/api-specification/blik/post-v2-payment-blik-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Blik method must contain the project and payment identifiers, description of the refund, signature, and, if necessary, currency code and refund amount.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "PLN"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "PLN"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Blik method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `50.00 PLN` refund to the `user_33` customer in the `171` project.

```language-json
{
        "project_id": 171,
        "payment": {
            "id": "PAYMENT_6315",
            "type": "purchase",
            "status": "refunded",
            "date": "2022-05-12T14:32:59+0000",
            "method": "blik",
            "sum": {
                "amount": 0,
                "currency": "PLN"
            },
            "description": "REFUND_FOR_PAYMENT_6315"
        },
            "customer": {
            "id": "user_33"
        },
        "operation": {
            "id": 10992010050461,
            "type": "refund",
            "status": "success",
            "date": "2022-05-12T14:32:59+0000",
            "created_date": "2022-05-12T14:32:56+0000",
            "request_id": "1d970130f663c4639a2058a6b4727c9b710ddb3-00010993",
            "sum_initial": {
                "amount": 5000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "PLN"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 151,
                "payment_id": "151983",
                "auth_code": ""
            }
        },
        "signature": "TueTURmjrc9Vw2b1LtOG1NCCRA+UO0ov3wWc6ueXYUSTdxaZHj0w=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—how to organise interaction with the payment platform by using Gate
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Blik method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_blik.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_blik_dash_analysis}

To analyse information about payments made with the Blik method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Brazil Online Banking {#pm_brazil_ob}

An article about the payment method which allows you to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_brazil_ob_overview}

An article about the payment method which allows you to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Brazil Online Banking is a payment method which allows you to process payments in Brazilian reals and US dollars by using bank accounts in Brazil.This method supports purchasesand refunds.

This article provides information about working with the Brazil Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[BR](references/en/countries/BR.md)|
|Payment currencies|[BRL](references/en/currencies/BRL.md), [USD](references/en/currencies/USD.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|full or partial refunds can be issued within 90 calendar days after the purchase|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Brazil Online Banking method involves the merchant's web service, one of Ecommpay interfaces,and the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_brazil_ob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Brazil Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts¹|Times²|
|minimum|maximum|base|threshold|
|--|--------|------|
|-------|-------|----|---------|
|Purchases|\*|\*|3 minutes|36 hours|
|Refunds|\*|\*|5 minutes|36 hours|

**Note:**

1.  Minimum and maximum payment amounts depend on the banks that the customer can select after redirection to the provider service. The bank will not be available for selection if the payment amount is outside the limits set by the bank.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Brazil Online Banking method, you need to redirect the customer to the provider service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_brazil_ob_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_brazil_ob_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_brazil_ob_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_brazil_ob_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Brazil Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_brazil_ob_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Brazil Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Brazil Online Banking method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps on the provider service side.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Brazil Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Brazil Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is required to specify the following parameters:

    -   `customer_first_name`—first name of the customer
    -   `customer_last_name`—last name of the customer
    -   `customer_email`—customer email address
    -   `identify_doc_number`—number of the CPF \(Brazilian tax identification number of customer\), must contain 11 digits, to be specified without masked characters, spaces, or other separators
    To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`.

3.  If you need to have the payment form displayed with the Brazil Online Banking method selected, set the `force_payment_method` parameter to `online-brazil-banks`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Brazil Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature, as well as possible additional parameters.

``` {#codeblock_gdb_pts_w2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_bll_wrl_33c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Brazil Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "brazil",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "brazil",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_brazil_ob_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Brazil Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_brazil_ob_uml_gate.svg)

1.  A customer initiates a purchase by using the Brazil Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps on the provider service side.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Brazil Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Brazil Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/brazil/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is required to specify the following objects and parameters:
    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—customer email address
        -   `identify`—information about the document which establishes identity:
            -   `doc_number`—number of the CPF \(Brazilian tax identification number of customer\), must contain 11 digits, to be specified without masked characters, spaces, or other separators.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Brazil Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com",
        "identify": {
            "doc_number": "12345678901"
     }
  }
}
```

``` {#codeblock_id3_zrl_33c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com",
        "identify": {
            "doc_number": "12345678901"
     }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Brazil Online Banking method requires redirection of customers from the merchant's web service to the provider service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Brazil Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "brazil",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-3c6a0ba271207cb817a0c683cf36e7a33ff2d9b4-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn15Q0dM2S+iD5RNQvCeMsG/PmpHnKhIw+5XaZ+Fsd6z/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "brazil",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_brazil_ob_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Brazil Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_brazil_ob_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The refund is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Brazil Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Brazil Online Banking method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Brazil Online Banking method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_gqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Brazil Online Banking method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` full refund made by the `1` customer in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
     "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_265608",
        "type": "purchase",
        "status": "refunded",
        "date": "2025-06-26T06:48:37+0000",
        "method": "brazil",
        "sum": {
            "amount": 0,
            "currency": "USD"
        },
        "description": "TEST_PAYMENT_265608"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 7373000014760,
        "type": "refund",
        "status": "success",
        "date": "2025-06-26T06:48:37+0000",
        "created_date": "2025-06-26T06:48:34+0000",
        "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1903,
            "payment_id": "1750920516487",
            "auth_code": ""
        }
    },
    "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ=="
}
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "test_29.04.25_3",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-29T11:36:34+0000",
        "method": "brazil",
        "sum": {
            "amount": 90000,
            "currency": "BRL"
        },
        "description": "test_29.04.25_3"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 5557000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-29T11:22:44+0000",
        "created_date": "2024-12-29T11:22:44+0000",
        "request_id": "c717b3de84d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 50000,
            "currency": "BRL"
        },
        "sum_converted": {
            "amount": 8994,
            "currency": "USD"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21514,
            "payment_id": "1418092457",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Brazil Online Banking method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_brazil_ob.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_brazil_ob_dash_analysis}

To analyse information about payments made with the Brazil Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Buy Now Pay Later {#pm_bnpl}

An article about the payment method which allows you to process installment payments in pounds sterling in the United Kingdom and supports purchases.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_bnpl_overview}

An article about the payment method which allows you to process installment payments in pounds sterling in the United Kingdom and supports purchases.

### Introduction {#section_t5z_rlg_ytb .section}

Buy Now Pay Later is a payment method which allows to process installment payments in pounds sterling in the United Kingdom. The terms of the installment payment plan are determined as a result of interaction between the customer and the provider. This method supports purchases.

This article provides information about working with the Buy Now Pay Later method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|payments cards|
|Countries and regions|[GB](references/en/countries/GB.md)|
|Payment currencies|[GBP](references/en/currencies/GBP.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|-   refunds are made only through applications in the provider's service, while the consideration of a separate application takes no more than one working day, but all applications are processed sequentially and each subsequent application is accepted only after the previous one has been processed
-   when redirecting to the provider service, the iframe element cannot be used; the relevant page can be opened in a separate tab or in a modal window

|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Buy Now Pay Later method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_bnpl_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Buy Now Pay Later method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, GBP|Times¹|
|minimum|maximum|base|threshold|
|--|------------|------|
|-------|-------|----|---------|
|Purchases|1.00|30,000.00|5 minutes|24 hours|

**Note:**

1.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Buy Now Pay Later method, you need to redirect customer to the provider service.

![](images/pm/en_bnpl_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_bnpl_interfaces_gate.svg "Purchase by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_bnpl_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Buy Now Pay Later method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_bnpl_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Buy Now Pay Later method.
8.  The payment platform receives the request for processing the payment by using the Buy Now Pay Later method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer set ups the payment plan and completes the required payment steps.
15. The information is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the purchase result and payment plan information to the payment platform.
19. The payment platform sends the purchase result and payment plant information to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Buy Now Pay Later method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Buy Now Pay Later method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is required to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`.
3.  If you need to have the payment form displayed with the Buy Now Pay Later method selected, set the `force_payment_method` parameter to `bnpl-humm`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Buy Now Pay Later method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), information about the customer and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 3000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Buy Now Pay Later method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md). It should be noted that the `bnpl` value can be specified in the `type` parameter of the `payment` object.

The following is the example of a callback with information about a `10.00 GBP` purchase that was processed in the `59051` project.

``` {#codeblock_jbq_jnd_f2c .language-json}
{
        "customer": {
            "id": "zxc",
            "phone": "07811123331"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_600055",
            "type": "bnpl",
            "status": "success",
            "date": "2024-11-14T11:20:31+0000",
            "method": "bnpl",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_600055"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16891,
                "payment_id": "Twp7saulXXF05mzi",
                "auth_code": ""
            },
            "id": 29741010169841,
            "type": "sale",
            "status": "success",
            "date": "2024-11-14T11:20:31+0000",
            "created_date": "2024-11-14T11:08:10+0000",
            "request_id": "497a5edb8ba907ae27d12f508c3d2ba096-00029742"
        },
        "signature": "XV7CVXtQv7n53zvg3jlt1ThyVdedpUKg3UX/9i6jWLPiA=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_kbq_jnd_f2c .language-json}
{
        "customer": {
            "id": "zxc"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_577285",
            "type": "bnpl",
            "status": "decline",
            "date": "2024-11-14T11:49:55+0000",
            "method": "bnpl",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_577285"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16891,
                "payment_id": "xAIr1FeVlr1QGo4h",
                "auth_code": ""
            },
            "id": 35876010169968,
            "type": "sale",
            "status": "decline",
            "date": "2024-11-14T11:49:55+0000",
            "created_date": "2024-11-14T11:39:57+0000",
            "request_id": "f5313e75fade8bb5076a05692a9c82-00035877"
        },
        "signature": "C3I7F8GCUMf/7MJjQszBerLdVWYncTyi+ZAD9uKDQDg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_bnpl_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Buy Now Pay Later method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_bnpl_uml_gate.svg)

1.  A customer initiates a purchase by using the Buy Now Pay Later method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer set ups the payment plan and completes the required payment steps.
12. The information is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends a notification about the purchase result and payment plan information to the payment platform.
16. The payment platform sends the purchase result and payment plant information to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Buy Now Pay Later method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Buy Now Pay Later method:

1.  To initiate each purchase, send a separate POST request to the [/v2/payment/bnpl/humm/sale](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bnpl-humm-sale) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Buy Now Pay Later method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, as well as signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej/UG0Di8hTng6JvipTv+AWoXW/9MTO8yJA=="
  },
  "payment": {
    "amount": 30000,
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej/UG0Di8hTng6JvipTv+AWoXW/9MTO8yJA=="
  },
  "payment": {
    "amount": 30000,
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Buy Now Pay Later method requires redirection of customers from the merchant's web service to the provider service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "POST",
    "url": "https://www.example.com/pay"
  }
```

### Callback format {#section_dpx_2hl_ggb .section}

The Buy Now Pay Later method uses the standard format for callbacks to deliver results. For more information, see [Handling callbacks](en_platform_callbacks.md). It should be noted that the `bnpl` value can be specified in the `type` parameter of the `payment` object.

The following is the example of a callback with information about a `10.00 GBP` purchase that was processed in the `59051` project.

``` {#codeblock_jbq_jnd_f2c .language-json}
{
        "customer": {
            "id": "zxc",
            "phone": "07811123331"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_600055",
            "type": "bnpl",
            "status": "success",
            "date": "2024-11-14T11:20:31+0000",
            "method": "bnpl",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_600055"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16891,
                "payment_id": "Twp7saulXXF05mzi",
                "auth_code": ""
            },
            "id": 29741010169841,
            "type": "sale",
            "status": "success",
            "date": "2024-11-14T11:20:31+0000",
            "created_date": "2024-11-14T11:08:10+0000",
            "request_id": "497a5edb8ba907ae27d12f508c3d2ba096-00029742"
        },
        "signature": "XV7CVXtQv7n53zvg3jlt1ThyVdedpUKg3UX/9i6jWLPiA=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_kbq_jnd_f2c .language-json}
{
        "customer": {
            "id": "zxc"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_577285",
            "type": "bnpl",
            "status": "decline",
            "date": "2024-11-14T11:49:55+0000",
            "method": "bnpl",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_577285"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16891,
                "payment_id": "xAIr1FeVlr1QGo4h",
                "auth_code": ""
            },
            "id": 35876010169968,
            "type": "sale",
            "status": "decline",
            "date": "2024-11-14T11:49:55+0000",
            "created_date": "2024-11-14T11:39:57+0000",
            "request_id": "f5313e75fade8bb5076a05692a9c82-00035877"
        },
        "signature": "C3I7F8GCUMf/7MJjQszBerLdVWYncTyi+ZAD9uKDQDg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_bnpl_dash_analysis}

To analyse information about payments made with the Buy Now Pay Later method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Chile Online Banking {#pm_chile_ob}

An article about the payment method which allows you to process payments in Chilean pesos and US dollars by using bank accounts in Chile and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_chile_ob_overview}

An article about the payment method which allows you to process payments in Chilean pesos and US dollars by using bank accounts in Chile and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Chile Online Banking is a payment method which allows you to process payments in Chilean pesos and US dollars by using bank accounts in Chile.This method supports purchases and refunds.

This article provides information about working with the Chile Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[CL](references/en/countries/CL.md)|
|Payment currencies|[CLP](references/en/currencies/CLP.md), [USD](references/en/currencies/USD.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|-   the amounts for [CLP](references/en/currencies/CLP.md) currency are specified in the smallest currency unit
-   full or partial refunds can be issued within 90 calendar days after the purchase

|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Chile Online Banking method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_chile_ob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Chile Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts¹|Times²|
|minimum|maximum|base|threshold|
|--|--------|------|
|-------|-------|----|---------|
|Purchases|\*|\*|3 minutes|36 hours|
|Refunds|\*|\*|5 minutes|36 hours|

**Note:**

1.  Minimum and maximum payment amounts depend on the banks that the customer can select after redirection to the provider service. The bank will not be available for selection if the payment amount is outside the limits set by the bank.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Chile Online Banking method, you need to redirect the customer to the provider service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_chile_ob_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_chile_ob_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_chile_ob_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_chile_ob_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Chile Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_chile_ob_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Chile Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Chile Online Banking method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps on the provider service side.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Chile Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Chile Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is also required to specify the first and last name and the email of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_email`. To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`.
3.  If you need to have the payment form displayed with the Chile Online Banking method selected, set the `force_payment_method` parameter to `online-chile-banks`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Chile Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature, as well as possible additional parameters.

``` {#codeblock_gdb_pts_w2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_nt1_w4f_ggc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Chile Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "chile",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "chile",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_chile_ob_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Chile Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_chile_ob_uml_gate.svg)

1.  A customer initiates a purchase by using the Chile Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps on the provider service side.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Chile Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Chile Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/chile/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is required to specify the following objects and parameters:
    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—customer email address
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Chile Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

``` {#codeblock_fp4_1tw_x2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Chile Online Banking method requires redirection of customers from the merchant's web service to the Chile Online Banking service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Chile Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "chile",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-3c6a0ba271207cb817a0c683cf36e7a33ff2d9b4-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn15Q0dM2S+iD5RNQvCeMsG/PmpHnKhIw+5XaZ+Fsd6z/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "chile",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_chile_ob_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Chile Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_chile_ob_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The refund is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Chile Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Chile Online Banking method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Chile Online Banking method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_gqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Chile Online Banking method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` full refund made by the `1` customer in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_265608",
        "type": "purchase",
        "status": "refunded",
        "date": "2025-06-26T06:48:37+0000",
        "method": "chile",
        "sum": {
            "amount": 0,
            "currency": "USD"
        },
        "description": "TEST_PAYMENT_265608"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 7373000014760,
        "type": "refund",
        "status": "success",
        "date": "2025-06-26T06:48:37+0000",
        "created_date": "2025-06-26T06:48:34+0000",
        "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1903,
            "payment_id": "1750920516487",
            "auth_code": ""
        }
    },
    "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ=="
}
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "test_29.04.25_3",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-29T11:36:34+0000",
        "method": "chile",
        "sum": {
            "amount": 200000,
            "currency": "CLP"
        },
        "description": "test_29.04.25_3"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 5557000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-29T11:22:44+0000",
        "created_date": "2024-12-29T11:22:44+0000",
        "request_id": "c717b3de84d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 100000,
            "currency": "CLP"
        },
        "sum_converted": {
            "amount": 106,
            "currency": "USD"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21514,
            "payment_id": "1418092457",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Chile Online Banking method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_chile_ob.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_chile_ob_dash_analysis}

To analyse information about payments made with the Chile Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# China UnionPay {#pm_unionpay}

An article about the payment method which allows you to process payments in different currencies by using payment cards in different countries and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_unionpay_overview}

An article about the payment method which allows you to process payments in different currencies by using payment cards in different countries and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

China UnionPay is a payment method which allows you to process payments in different currencies by using payment cards in different countries.This method supports purchasesand refunds.

This article provides information about working with the China UnionPay method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|payments cards|
|Countries and regions|[AE](references/en/countries/AE.md), [AG](references/en/countries/AG.md), [AT](references/en/countries/AT.md), [AU](references/en/countries/AU.md), [AZ](references/en/countries/AZ.md), [BD](references/en/countries/BD.md), [BE](references/en/countries/BE.md), [BN](references/en/countries/BN.md), [BY](references/en/countries/BY.md), [CA](references/en/countries/CA.md), [CN](references/en/countries/CN.md), [DE](references/en/countries/DE.md), [ES](references/en/countries/ES.md), [FI](references/en/countries/FI.md), [FR](references/en/countries/FR.md), [GB](references/en/countries/GB.md), [GE](references/en/countries/GE.md), [HK](references/en/countries/HK.md), [HU](references/en/countries/HU.md), [ID](references/en/countries/ID.md), [IE](references/en/countries/IE.md), [IT](references/en/countries/IT.md), [JP](references/en/countries/JP.md), [KE](references/en/countries/KE.md), [KG](references/en/countries/KG.md), [KH](references/en/countries/KH.md), [KR](references/en/countries/KR.md), [KZ](references/en/countries/KZ.md), [LB](references/en/countries/LB.md), [LI](references/en/countries/LI.md), [LK](references/en/countries/LK.md), [LT](references/en/countries/LT.md), [LU](references/en/countries/LU.md), [MG](references/en/countries/MG.md), [MN](references/en/countries/MN.md), [MO](references/en/countries/MO.md), [MT](references/en/countries/MT.md), [MU](references/en/countries/MU.md), [MX](references/en/countries/MX.md), [MY](references/en/countries/MY.md), [NL](references/en/countries/NL.md), [NP](references/en/countries/NP.md), [NZ](references/en/countries/NZ.md), [PA](references/en/countries/PA.md), [PF](references/en/countries/PF.md), [PH](references/en/countries/PH.md), [PT](references/en/countries/PT.md), [SC](references/en/countries/SC.md), [SG](references/en/countries/SG.md), [SI](references/en/countries/SI.md), [SK](references/en/countries/SK.md), [SR](references/en/countries/SR.md), [TH](references/en/countries/TH.md), [TJ](references/en/countries/TJ.md), [TZ](references/en/countries/TZ.md), [US](references/en/countries/US.md), [VN](references/en/countries/VN.md) \*|
|Payment currencies|[AUD](references/en/currencies/AUD.md), [CAD](references/en/currencies/CAD.md), [CHF](references/en/currencies/CHF.md), [CNY](references/en/currencies/CNY.md), [EUR](references/en/currencies/EUR.md), [GBP](references/en/currencies/GBP.md), [HKD](references/en/currencies/HKD.md), [JPY](references/en/currencies/JPY.md), [NZD](references/en/currencies/NZD.md), [SGD](references/en/currencies/SGD.md), [USD](references/en/currencies/USD.md), [THB](references/en/currencies/THB.md) \*|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|+|
|Notes|when handling chargebacks related to purchases processed by using the China UnionPay method, it is important to consider the following:

-   the procedure for handling such chargebacks may differ from the procedure for standard card payments described in this documentation
-   the Dashboard interface is not supported for handling such chargebacks
-   when such chargebacks are filed, Ecommpay specialists notify the merchant's specialists, provide information on the subsequent procedure and consult on any questions that arise
-   general questions about the procedure for handling such chargebacks can be addressed to your Ecommpay account manager

|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/unionpay-securepay/)|

**Note:** \* For more information refer to your Ecommpay key account manager.

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the China UnionPay method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the China UnionPay service.

![](images/pm/eng_chinaunionpay_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the China UnionPay method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the China UnionPay method, you need to redirect the customer to the China UnionPay service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/eng_chinaunionpay_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_chinaunionpay_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/eng_chinaunionpay_interfaces_gate_refund.svg "Refund by using Gate")

## Purchases by using Payment Page {#en_pm_unionpay_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the China UnionPay method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_chinaunionpay_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the China UnionPay method.
8.  The payment platform receives the request for processing the payment by using the China UnionPay method.
9.  The payment platform processes the request and sends it to the China UnionPay service.
10. The request is processed on the China UnionPay service side.
11. The data for redirecting the customer to the China UnionPay service is sent from the China UnionPay service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the China UnionPay service.
14. The customer completes all required payment steps.
15. The purchase is processed in the China UnionPay service.
16. The result information is displayed to the customer in the China UnionPay service.
17. The customer is redirected to Payment Page.
18. The China UnionPay service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the China UnionPay method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the China UnionPay method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, depending on the payment processing provider, it can be necessary to specify the last name of the customer in the parameter `customer_last_name`. If this parameter is missing, the payment form may display the input field for entering the missing value \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  The currency of payment can be one of the following: [AUD](references/en/currencies/AUD.md), [CAD](references/en/currencies/CAD.md), [CHF](references/en/currencies/CHF.md), [CNY](references/en/currencies/CNY.md), [EUR](references/en/currencies/EUR.md), [GBP](references/en/currencies/GBP.md), [HKD](references/en/currencies/HKD.md), [JPY](references/en/currencies/JPY.md), [NZD](references/en/currencies/NZD.md), [SGD](references/en/currencies/SGD.md), [USD](references/en/currencies/USD.md), [THB](references/en/currencies/THB.md). Consult with your Ecommpay account manager regarding availability of currencies.
4.  To open Payment Page in the language of the bank group, pass the `zh` code in the `language_code` parameter in the request for opening. For more information, see [Interface language support](en_PP_WigetLanguages.md).
5.  If you need to have the payment form displayed with the China UnionPay method selected, set the `force_payment_method` parameter to `cup-union`.
6.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
7.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the China UnionPay method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier last name, as well as signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_last_name": "Johnson",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_last_name": "Johnson",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The China UnionPay method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 USD` purchase made in the `198` project.

```language-json
"callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_154402240162030",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-06T13:33:33+0000",
            "method": "unionpay",
            "sum": {
                "amount": 100,
                "currency": "USD"
            },
            "description": "TEST_154402240162930"
        },
        "operation": {
            "id": 7458000002161,
            "type": "sale",
            "status": "success",
            "date": "2018-12-06T13:33:33+0000",
            "created_date": "2018-12-06T13:31:41+0000",
            "request_id": "986be38f02e8fe3fb8-c1990f3e7af3",
            "sum_initial": {
                "amount": 100,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": "74580000021610207055371314024366",
                "date": "2018-12-06T13:31:42+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
"callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_1548340290097231",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-26T14:36:35+0000",
            "method": "unionpay",
            "sum": {
                "amount": 2000000,
                "currency": "CNY"
            },
            "description": "TEST_1548340290097"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 4723000002794,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-26T14:36:35+0000",
            "created_date": "2019-01-24T14:36:33+0000",
            "request_id": "72b28ec3f95271699dcade",
            "sum_initial": {
                "amount": 2000000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 294684,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": "47230000027940105280386327826886",
                "date": "2019-01-24T14:36:35+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_unionpay_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the China UnionPay method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the China UnionPay service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_chinaunionpay_uml_gate.svg)

1.  A customer initiates a purchase by using the China UnionPay method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the China UnionPay service.
7.  The request is processed on the China UnionPay service side.
8.  The China UnionPay service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the China UnionPay service.
11. The customer completes all required payment steps.
12. The purchase is processed in the China UnionPay service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The China UnionPay service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the China UnionPay method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the China UnionPay method:

1.  To initiate each purchase, send a separate POST request to the [/v2/payment/cup/union/sale](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-cup-union-sale) endpoint.
2.  Each request must include the following objects and parameters:

    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   `customer`—object that contains customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `last_name*`—last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\). If the parameter is not specified in the request, a callback containing this parameter is sent for additional payment information submission \(for more details, see [Submission of additional payment information](en_Gate_Clarification.md)\)
    -   Object `return_url*`—contains the URLs to which customer is redirected during or after payment processing:
        -   `success*`—URL for redirecting a customer after a performed purchase
        -   `return*`—URL to return customer to the web service during any step before the payment is completed
    **Note:** \*Consult with your Ecommpay account manager for the detailed information what parameters are required.

3.  The currency of payment can be one of the following: [AUD](references/en/currencies/AUD.md), [CAD](references/en/currencies/CAD.md), [CHF](references/en/currencies/CHF.md), [CNY](references/en/currencies/CNY.md), [EUR](references/en/currencies/EUR.md), [GBP](references/en/currencies/GBP.md), [HKD](references/en/currencies/HKD.md), [JPY](references/en/currencies/JPY.md), [NZD](references/en/currencies/NZD.md), [SGD](references/en/currencies/SGD.md), [USD](references/en/currencies/USD.md), [THB](references/en/currencies/THB.md). Consult with your Ecommpay account manager regarding availability of currencies.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payment request in the China UnionPay method must include general information about request and information about payment and customer. The method may also require a URLs for redirection and the last name of the customer as shown in the following example. For details, refer to your Ecommpay account manager.

Thus, a correct purchase request by using the China UnionPay method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address and signature. The method may also require a URLs for redirection and the last name of the customer as shown in the following example.

```language-json
{
  "general": {
    "project_id": 198,
    "payment_id": "TEST_15532590003171111",
    "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...=="
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "last_name": "Johnson"
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "return_url": {
    "success": "https://example.com/success",
    "return": "https://example.com/return"
  }
}
```

```language-json
{
  "general": {
    "project_id": 198,
    "payment_id": "TEST_15532590003171111",
    "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...=="
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "last_name": "Johnson"
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "return_url": {
    "success": "https://example.com/success",
    "return": "https://example.com/return"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the China UnionPay method requires redirection of customers from the merchant's web service to the China UnionPay service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The China UnionPay method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 USD` purchase made in the `198` project.

```language-json
"callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_154402240162030",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-06T13:33:33+0000",
            "method": "unionpay",
            "sum": {
                "amount": 100,
                "currency": "USD"
            },
            "description": "TEST_154402240162930"
        },
        "operation": {
            "id": 7458000002161,
            "type": "sale",
            "status": "success",
            "date": "2018-12-06T13:33:33+0000",
            "created_date": "2018-12-06T13:31:41+0000",
            "request_id": "986be38f02e8fe3fb8-c1990f3e7af3",
            "sum_initial": {
                "amount": 100,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": "74580000021610207055371314024366",
                "date": "2018-12-06T13:31:42+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
"callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_1548340290097231",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-26T14:36:35+0000",
            "method": "unionpay",
            "sum": {
                "amount": 2000000,
                "currency": "CNY"
            },
            "description": "TEST_1548340290097"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 4723000002794,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-26T14:36:35+0000",
            "created_date": "2019-01-24T14:36:33+0000",
            "request_id": "72b28ec3f95271699dcade",
            "sum_initial": {
                "amount": 2000000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 294684,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": "47230000027940105280386327826886",
                "date": "2019-01-24T14:36:35+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_unionpay_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the China UnionPay method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.For one payment you can perform only one partial refund, then to make additional refunds for this payment you need to contact the technical support of the payment system. The full sequence and special aspects of refund performing are provided below.

![](images/pm/eng_chinaunionpay_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the China UnionPay service.
7.  The refund is processed on the side of the China UnionPay service.
8.  The China UnionPay service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the China UnionPay method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the China UnionPay method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/unionpay/refund](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-unionpay-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the China UnionPay method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The China UnionPay method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 USD` refund made in the `198` project.

```language-json
"callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_154402240162030",
            "type": "purchase",
            "status": "refunded",
            "date": "2018-12-06T14:24:08+0000",
            "method": "unionpay",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_154402240162930"
        },
        "operation": {
            "id": 7458000002162,
            "type": "refund",
            "status": "success",
            "date": "2018-12-06T14:24:08+0000",
            "created_date": "2018-12-06T14:23:58+0000",
            "request_id": "758cf8a4a495acf7f27eb0c1b",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": "",
                "date": "2018-12-06T22:24:04+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "pHyB8h89qctuJ3ksW9xsERYpVSi3SDWAAWnknJw4o9f...=="
    }
```

The following is the example of a callback with information about a declined refund.

```language-json
  "callbackBody": {
        "project_id": 198,
        "payment": {
            "id": "TEST_1542789072282111",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2018-11-21T12:33:38+0000",
            "method": "unionpay",
            "sum": {
                "amount": 50,
                "currency": "USD"
            },
            "description": "TEST_1542789072282"
        },
        "customer": {
            "id": "1"
        },
        "errors": [
            {
                "code": "2701",
                "message": "Rules Failed Code",
                "description": "fatal: RULES_FAILED_CODE"
            }
        ],
        "operation": {
            "id": 16115000001979,
            "type": "refund",
            "status": "decline",
            "date": "2018-11-21T12:49:38+0000",
            "created_date": "2018-11-21T12:49:38+0000",
            "request_id": "3abc68c33b2298127",
            "sum_initial": {
                "amount": 50,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 50,
                "currency": "USD"
            },
            "provider": {
                "id": 410,
                "payment_id": ""
            },
            "code": "2701",
            "message": "Rules Failed Code"
        },
        "signature": "hAS3NXs1LmLl0xYtaHqLrRCAANBq1Z+/g26NVka...=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_unionpay_dash_analysis}

To analyse information about payments made with the China UnionPay method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Direct Debit BACS {#pm_dd_bacs}

An article about the payment method which allows you to process payments in pounds by using bank accounts in the United Kingdom and supports COF purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_dd_bacs_overview}

An article about the payment method which allows you to process payments in pounds by using bank accounts in the United Kingdom and supports COF purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Direct Debit BACS is a payment method which allows you to process payments in pounds by using bank accounts in the United Kingdom.This method supports COF purchases and refunds.

This article provides information about working with the Direct Debit BACS method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[GB](references/en/countries/GB.md)|
|Payment currencies|[GBP](references/en/currencies/GBP.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|+|
|Full refunds|+|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|by default refunds can be performed only after seven calendar days since the purchase has been processed; to enable the possibility of performing refunds before this time, contact your Ecommpay account manager|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Direct Debit BACS method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Direct Debit BACS method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard.

The threshold time for processing purchases \(the maximum possible time between the moment a payment is initiated in the payment platform and the moment the web service receives the callback with the payment result information\) is 5 business days. This time can be extended due to holidays and weekends. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Direct Debit BACS method, you need to redirect the customer to the Direct Debit BACS service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

## COF purchases by using Payment Page {#en_pm_dd_bacs_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

When using Payment Page and the Direct Debit BACS method, you can register COF purchases of two types:

-   *Regular purchase*—regular automatic debits are carried out according to a schedule passed to the platform \([details](en_platform_sheduled_recurring_model.md)\). In this case, automatic debiting is used, without additional actions on the part of the merchant.
-   *Autopurchase*—debits are initiated by the web service by sending requests based on specified rules \([details](en_platform_recurring_model.md)\). In this case, to debit funds, each time a separate Gate request is required \([details](pm_dd_bacs.md)\).

At the same time, you can register a COF purchase of any of these types either with or without an initial debit of funds. Please note that for registration without the initial debit the `directdebit` payment type is used, and for registration with the first debit the `purchase` type is used.

To register a COF purchase through Payment Pageby using the Direct Debit BACS method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the registration result.

Information about the formats of requests and callbacks used for registering purchases by using the Direct Debit BACS method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format for registration without the initial debit of funds {#section_p5j_fgl_ggb .section}

When registering a COF purchase without the initial debit, the `directdebit` payment type is used, within which the following types of operations can be performed: `contract registration`, `recurring update` \(only when for regular purchases\), `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit BACS method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount, the `0` value must be specified
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is necessary to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`, as well as the `directdebit-bacs` method code in the `force_payment_method` parameter and the `card_verify` value in the `mode` parameter.
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit BACS method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [COF purchase registration](en_pp_recurring.md) section.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Direct Debit BACS method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and COF purchase information, as well as signature.

``` {#codeblock_cqt_1hy_m2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_currency": "GBP",
   "payment_amount": 0,
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "directdebit-bacs",
   "mode": "card_verify",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_kky_1hy_m2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_currency": "GBP",
   "payment_amount": 0,
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "directdebit-bacs",
   "mode": "card_verify",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Request format for registration with the initial debit of funds {#section_qt3_qfl_j1c .section}

When registering a COF purchase with the initial debit, the `purchase` payment type is used, within which the following types of operations can be performed: `sale`, `reversal`, `refund`, `contract registration`, `recurring update` \(only for regular purchases\) and `recurring cancel` \(only for regular purchases\).

There are several things you need to consider when sending purchase registration requests by using the Direct Debit BACS method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is necessary to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`.
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit BACS method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be passed in the `recurring` object is presented in the [COF purchase registration](en_pp_recurring.md) section.
4.  If you need to have the payment form displayed with the Direct Debit BACS method selected, set the `force_payment_method` parameter to `directdebit-bacs`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Direct Debit BACS method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit BACS method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a COF purchase without an initial debit of funds that has been registered in the `430716` project.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_342011450",
            "type": "directdebit",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 1,
                "currency": "GBP"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 9738,
            "currency": "GBP",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2048000011083,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "created_date": "2024-01-19T07:54:38+0000",
            "request_id": "881f81f7cd8e1a11b0903a8d8f98-00002049",
            "sum_initial": {
                "amount": 1,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "K4vshmZkpqPMEHr",
                "auth_code": ""
            }
        },
        "signature": "bepC/BLdBruEdA/1pqB4aJ4KnihVW0pfWM7Y1uAw=="
    }
```

The following is the example of a callback with information about a COF purchase with an initial debit of funds that has been registered in the `430716` project.

```language-json
 {
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_702917140",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 10000,
                "currency": "GBP"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 8224,
            "currency": "GBP",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2330000011063,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "created_date": "2024-01-18T12:39:37+0000",
            "request_id": "5f3e8be0ed6967412c89beab965-00002331",
            "sum_initial": {
                "amount": 10000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "ZOrsGv5u8fyQ4SM",
                "auth_code": ""
            }
        },
        "signature": "vdTeWodANtRGz80gHPeI+oyYioNu7T/YISzA=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase.

```
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_bacs",
            "type": "directdebit",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 0,
                "currency": "GBP"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "MD000ZBRK2P769",
                "auth_code": ""
            },
            "id": 51271010116645,
            "type": "contract registration",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "created_date": "2024-02-26T10:54:33+0000",
            "request_id": "741a4d68a1f039c794e309063c4dd-00051272"
        },
        "signature": "+mPKi+A2RMCU7e2S+vXDIUoQzk9rkbwq4dE/xQ=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase and a declined purchase.

```
{
        "customer": {
            "id": "customer 1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_246302",
            "type": "purchase",
            "status": "awaiting customer",
            "date": "2024-02-26T10:46:12+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 100,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_246302"
        },
        "operation": {
            "sum_initial": {
                "amount": 100,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "PM009FAY0JJF1G",
                "auth_code": ""
            },
            "id": 63155010115589,
            "type": "sale",
            "status": "decline",
            "date": "2024-02-26T10:46:12+0000",
            "created_date": "2024-02-26T10:45:21+0000",
            "request_id": "35ed3b53c8101de9bacb8601f9cbe2633c56917968e-00063156"
        },
        "signature": "0nENQAYq+xYe5MxS2Qsend4Lt0EPPTpcXfPZdbg5p7WH4ZA=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## COF purchases by using Gate {#en_pm_dd_bacs_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

When using Gate and the Direct Debit BACS method, you can register COF purchases of two types:

-   *Regular purchase*—regular automatic debits are carried out according to a schedule passed to the platform \([details](en_platform_sheduled_recurring_model.md)\). In this case, automatic debiting is used, without additional actions on the part of the merchant.
-   *Autopurchase*—debits are initiated by the web service by sending requests based on specified rules \([details](en_platform_recurring_model.md)\). In this case, to debit funds, each time a separate request is required.

At the same time, you can register a COF purchase of any of these types either with or without an initial debit of funds. Please note that for registration without the initial debit the `directdebit` payment type is used, and for registration with the first debit the `purchase` type is used.

To register a purchase through Gate by using the Direct Debit BACS method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Direct Debit BACS service.
3.  Receive the callback from the payment platform informing about the registration result.

To perform each debit of funds within an autopurchase the merchant's web service is required to send a request with all the required parameters and signature to the Ecommpay URL and receive a callback from the payment platform informing abot the debit result.

Information about the formats of requests and callbacks used for processing payments by using the Direct Debit BACS method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format for registration without the initial debit of funds {#section_osx_3jl_ggb .section}

When registering a COF purchase without the initial debit, the `directdebit` payment type is used, within which the following types of operations can be performed: `contract registration`, `recurring update` \(only when for regular purchases\), `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit BACS method:

1.  To register each purchase, send a separate POST request to the `/v2/payment/directdebit/bacs/contract/registration` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/contract/registration](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-contract-registration).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit BACS method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [Registering COF purchase](en_gate_payment_recurring_registration.md) section.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase registration request by using the Direct Debit BACS method must contain the project identifier, basic payment information \(identifier and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

### Request format for registration with the initial debit of funds {#section_rkj_vlm_j1c .section}

When registering a COF purchase with the initial debit, the `purchase` payment type is used, within which the following types of operations can be performed: `sale`, `reversal`, `refund`, `contract registration`, `recurring update` \(only for regular purchases\) and `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit BACS method:

1.  To register each purchase, send a separate POST request to the `/v2/payment/directdebit/bacs/sale` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit BACS method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [Registering COF purchase](en_gate_payment_recurring_registration.md) section.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase registration request by using the Direct Debit BACS method must contain the project identifier, basic payment information \(identifier, amount and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "GBP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

### Request format for a separate debit of funds {#section_sxr_kmm_j1c .section}

There are several things you must consider when sending requests for separate debits of funds by using the Direct Debit BACS method:

1.  To perform each debit, send a separate POST request to the `/v2/payment/directdebit/bacs/recurring` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency code in the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP address relevant for the initiated payout
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct request for a separate debit of funds by using the Direct Debit BACS method must contain the project and COF purchase identifiers, customer and payment information, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "GBP"
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Request format for getting information about a debiting series {#section_slv_pmm_j1c .section}

There are several things you must consider when sending a request for information about a debiting series by using the Direct Debit BACS method:

1.  To request information each time send a separate POST request to the [/v2/payment/recurring/info](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-recurring-info) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct request for information by using the Direct Debit BACS method must contain the project, payment and COF purchase identifiers, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Request format for updating a debiting series {#section_zhr_wmm_j1c .section}

There are several things you must consider when updating a debiting series by using the Direct Debit BACS method:

1.  For each update send a separate POST request to the `/v2/payment/directdebit/bacs/recurring/update` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring/update](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring-update).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  You need also use other parameters of the `recurring` object:
    -   `expiry_year`—expiration year of the COF purchase
    -   `expiry_month`—expiration month of the COF purchase
    -   `expiry_day`—expiration day of the COF purchase
    -   `interval`—multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set `period` to `W` and `interval` to `3`. Possible values: from `1` to `100`
    -   `amount`—amount to debit after registration
    -   `scheduled_payment_id`—ID to assign the COF purchase \(for automatic debiting\)
    -   `period`—debiting period:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly
        -   `Q`—quarterly
        -   `Y`—yearly
    -   `time`—time of subsequent debiting in the `hh:mm:ss` format
    -   `start_date`—date to perform the first debit
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct update request by using the Direct Debit BACS method must contain project ID, payment ID, signature, ID of debit series, and debit series parameters to update.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890,
    "interval":3,
    "period":"M",
    "time":"12:00:00"
  }
}
```

### Request format for cancelling a COF purchase {#section_zcz_ymm_j1c .section}

There are several things you must consider when cancelling COF purchases by using the Direct Debit BACS method:

1.  To cancel each purchase, send a separate POST request to the `/v2/payment/directdebit/bacs/recurring/cancel` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring/cancel](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring-cancel).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Direct Debit BACS method must contain the project, payment and COF purchase identifiers, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Direct Debit BACS method requires redirection of customers from the merchant's web service to the Direct Debit BACS service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit BACS method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a COF purchase without an initial debit of funds that has been registered in the `430716` project.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_342011450",
            "type": "directdebit",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 1,
                "currency": "GBP"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 9738,
            "currency": "GBP",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2048000011083,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "created_date": "2024-01-19T07:54:38+0000",
            "request_id": "881f81f7cd8e1a11b0903a8d8f98-00002049",
            "sum_initial": {
                "amount": 1,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "K4vshmZkpqPMEHr",
                "auth_code": ""
            }
        },
        "signature": "bepC/BLdBruEdA/1pqB4aJ4KnihVW0pfWM7Y1uAw=="
    }
```

The following is the example of a callback with information about a COF purchase with an initial debit of funds that has been registered in the `430716` project.

```language-json
 {
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_702917140",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 10000,
                "currency": "GBP"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 8224,
            "currency": "GBP",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2330000011063,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "created_date": "2024-01-18T12:39:37+0000",
            "request_id": "5f3e8be0ed6967412c89beab965-00002331",
            "sum_initial": {
                "amount": 10000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "ZOrsGv5u8fyQ4SM",
                "auth_code": ""
            }
        },
        "signature": "vdTeWodANtRGz80gHPeI+oyYioNu7T/YISzA=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase.

```
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_bacs",
            "type": "directdebit",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 0,
                "currency": "GBP"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "MD000ZBRK2P769",
                "auth_code": ""
            },
            "id": 51271010116645,
            "type": "contract registration",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "created_date": "2024-02-26T10:54:33+0000",
            "request_id": "741a4d68a1f039c794e309063c4dd-00051272"
        },
        "signature": "+mPKi+A2RMCU7e2S+vXDIUoQzk9rkbwq4dE/xQ=="
    }
```

The following is the example of a callback with information about a separate debit of funds.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_494065730",
            "type": "recurring",
            "status": "success",
            "date": "2024-01-24T16:02:17+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 10000,
                "currency": "GBP"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 5768,
            "currency": "GBP",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 4653000011052,
            "type": "recurring",
            "status": "success",
            "date": "2024-01-24T16:02:17+0000",
            "created_date": "2024-01-24T16:01:49+0000",
            "request_id": "0e716081819385b6448b8c3387c4-00004654",
            "sum_initial": {
                "amount": 10000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "a5xCcVqriGOJ8Ty",
                "auth_code": ""
            }
        },
        "signature": "VkmznYWPXQOYOqHyH5SuZRdzLab5GW5RUoe67QqBvw=="
    }
```

The following is the example of a callback with information about a declined separate debit of funds.

```language-json
{
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_001",
            "type": "recurring",
            "status": "scheduled recurring processing",
            "date": "2024-02-16T11:36:37+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 400,
                "currency": "GBP"
            },
            "description": ""
        },
        "recurring": {
            "valid_thru": "2030-01-31T23:59:59+0000",
            "id": 1721154593,
            "currency": "GBP"
        },
        "operation": {
            "sum_initial": {
                "amount": 400,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 400,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "PM009DFXAP3EQR",
                "auth_code": ""
            },
            "id": 76329010120929,
            "type": "recurring",
            "status": "decline",
            "date": "2024-02-16T11:36:37+0000",
            "created_date": "2024-02-16T11:33:44+0000",
            "request_id": "5e19acd1e577f9f35a52c2706f-00076330"
        },
        "signature": "uUUVa/0siyHKibfL+CRo1cshrlVoJhkGoByn1g=="
    }
```

The following is the example of a callback with information about an updated debiting series.

```language-json
{  
  "project_id":123,
  "recurring":{
    "id":1079,              
    "currency":"GBP",
    "status":"active",       
    "type":"R",
    "expiry_month":"5",    
    "expiry_year":"2025",   
    "period":"M",            
    "period_interval":3,
    "time":"12:00:00"        
  },
  "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...=="
}
```

The following is the example of a callback with information about a cancelled COF purchase.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_878918",
            "type": "purchase",
            "status": "success",
            "date": "2024-02-16T11:08:25+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 100,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_878918"
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": ""
            },
            "sum_converted": {
                "amount": 0,
                "currency": ""
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16351,
                "payment_id": "MD000Z79BA94NF",
                "auth_code": ""
            },
            "id": 5049531010137015,
            "type": "recurring_cancel",
            "status": "success",
            "date": "2024-02-16T11:39:12+0000",
            "created_date": "2024-02-16T11:38:35+0000",
            "request_id": "6ef48716ca0809f0588e53d3-00094164"
        },
        "signature": "4M8mbH3W5oplKW1ipmZKApYVbTHrdGBNg=="
    }
```

### Response format {#section_mxj_bnm_j1c .section}

The payment platform uses the standard format for response with debit series information. For more information about response format, see [Response format](en_gate_interaction_organisation.md).

```language-json
{
    "project_id": 1602,
    "recurring": {
        "id": 7305,
        "type": "R",
        "period": "W",
        "period_interval": 1,
        "start_date": "2024-02-06",
        "start_time": "00:49:23",
        "amount": 74000,
        "last_payment_at": "0000-00-00 00:00:00",
        "valid_thru": "2027-02-28 23:59:59",
        "status": "active",
        "description": "",
        "schedule_date": {
            "next": "2024-02-13 00:49:23"
        },
        "currency": "GBP"
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_dd_bacs_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Direct Debit BACS method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Direct Debit BACS service.
7.  The refund is processed on the side of the Direct Debit BACS service.
8.  The Direct Debit BACS service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Direct Debit BACS method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

**Note:** By default refunds can be performed only after seven calendar days since the purchase has been processed; to enable the possibility of performing refunds before this time, contact your Ecommpay account manager.

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Direct Debit BACS method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Direct Debit BACS method must contain the project and payment identifiers, description of the refund, the customer IP address and signature

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_un3_gyn_42c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit BACS method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `1.00 GBP` refund made in the `59051` project.

```language-json
 {
        "payment": {
            "method_id": 2931,
            "need_confirm_retry": false,
            "actual_amount": 100,
            "cascading_with_redirect": false,
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "status": "refunded",
            "id": "TEST_PAYMENT_175421",
            "method": "Direct Debit BACS",
            "date": "2024-02-12T13:57:14+0000",
            "result_code": "0",
            "result_message": "Success",
            "split_with_redirect": false,
            "provider_id": 16341
        },
        "sum_request": {
            "amount": 0,
            "currency": "GBP"
        },
        "rrn": "",
        "customer": {
            "id": "zxc"
        },
        "request_id": "daf48fcefbe98ca53fc82969c409-00081884",
        "transaction": {
            "id": 81883010089421,
            "date": "2024-02-12T13:57:14+0000",
            "type": "purchase"
        },
        "sum_real": {
            "amount": 100,
            "currency": "GBP"
        },
        "sum_refund": {
            "amount": 100,
            "currency": "GBP"
        },
        "recurring": {
            "id": 1720779781
        },
        "general": {
            "project_id": 59051,
            "payment_id": "TEST_PAYMENT_175421"
        },
        "description": "TEST_PAYMENT_175421",
        "cashout_data": {
            "customer_first_name": "Paul",
            "customer_id": "zxc",
            "customer_last_name": "Allen"
        },
        "signature": "xEumPOToRyH9/PFnyICB7eY/oxVatslhQWw=="
    }
```

The following is the example of a callback with information about a declined refund of an initial debit of funds.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_816625",
            "type": "purchase",
            "status": "success",
            "date": "2024-02-26T11:40:18+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 100,
                "currency": "GBP"
            },
            "description": "TEST_PAYMENT_816625"
        },
        "recurring": {
            "valid_thru": "2034-02-28T23:59:59+0000",
            "id": 1722138911,
            "currency": "GBP"
        },
        "operation": {
            "sum_initial": {
                "amount": 100,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "RF00006W2JHZWT",
                "auth_code": ""
            },
            "id": 83482010120825,
            "type": "refund",
            "status": "decline",
            "date": "2024-02-26T11:40:18+0000",
            "created_date": "2024-02-26T11:39:36+0000",
            "request_id": "b63907d503e7dc24bbe83981a1-00083483"
        },
        "signature": "Si+nDkjd+n/P1rGVwa3DZl5+sQ=="
    }
```

The following is the example of a callback with information about a declined refund of a separate debit of funds.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "qweqwe_1231231231001",
            "type": "recurring",
            "status": "success",
            "date": "2024-02-26T11:42:36+0000",
            "method": "Direct Debit BACS",
            "sum": {
                "amount": 400,
                "currency": "GBP"
            },
            "description": ""
        },
        "recurring": {
            "valid_thru": "2034-02-28T23:59:59+0000",
            "id": 1722138911,
            "currency": "GBP"
        },
        "operation": {
            "sum_initial": {
                "amount": 400,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 400,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 65138010114741,
            "type": "refund",
            "status": "decline",
            "date": "2024-02-26T11:42:36+0000",
            "created_date": "2024-02-26T11:42:35+0000",
            "request_id": "adc663dacdec30ef1abbc60653e10-00065139"
        },
        "signature": "OTvoVoPScN5N4tvEVhteWi/TQZB6qxew=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_dd_bacs_dash_analysis}

To analyse information about payments made with the Direct Debit BACS method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Direct Debit SEPA {#pm_dd_sepa}

An article about the payment method which allows you to process payments in euros by using bank accounts in the SEPA countries and supports COF purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_dd_sepa_overview}

An article about the payment method which allows you to process payments in euros by using bank accounts in the SEPA countries and supports COF purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Direct Debit SEPA is a payment method which allows you to process payments in euros by using bank accounts in the SEPA countries. This method allows funds to be debited directly from the bank accounts of customers. This method supports COF purchases and refunds.

This article provides information about working with the Direct Debit SEPA method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[AD](references/en/countries/AD.md), [AT](references/en/countries/AT.md), [BE](references/en/countries/BE.md), [BG](references/en/countries/BG.md), [HR](references/en/countries/HR.md), [CY](references/en/countries/CY.md), [CZ](references/en/countries/CZ.md), [DK](references/en/countries/DK.md), [EE](references/en/countries/EE.md), [FI](references/en/countries/FI.md), [FR](references/en/countries/FR.md), [DE](references/en/countries/DE.md), [GR](references/en/countries/GR.md), [HU](references/en/countries/HU.md), [IS](references/en/countries/IS.md), [IE](references/en/countries/IE.md), [IT](references/en/countries/IT.md), [LV](references/en/countries/LV.md), [LI](references/en/countries/LI.md), [LT](references/en/countries/LT.md), [LU](references/en/countries/LU.md), [MT](references/en/countries/MT.md), [MC](references/en/countries/MC.md), [NL](references/en/countries/NL.md), [NO](references/en/countries/NO.md), [PL](references/en/countries/PL.md), [PT](references/en/countries/PT.md), [RO](references/en/countries/RO.md), [SM](references/en/countries/SM.md), [SK](references/en/countries/SK.md), [SI](references/en/countries/SI.md), [ES](references/en/countries/ES.md), [SE](references/en/countries/SE.md), [CH](references/en/countries/CH.md), [GB](references/en/countries/GB.md), [VA](references/en/countries/VA.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|+|
|Full refunds|+|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|by default refunds can be performed only after seven calendar days since the purchase has been processed; to enable the possibility of performing refunds before this time, contact your Ecommpay account manager|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Direct Debit SEPA method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Direct Debit SEPA method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard.

The threshold time for processing purchases \(the maximum possible time between the moment a payment is initiated in the payment platform and the moment the web service receives the callback with the payment result information\) is 2 business days. This time can be extended due to holidays and weekends. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Direct Debit SEPA method, you need to redirect the customer to the Direct Debit SEPA service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

## COF purchases by using Payment Page {#en_pm_dd_sepa_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

When using Payment Page and the Direct Debit SEPA method, you can register COF purchases of two types:

-   *Regular purchase*—regular automatic debits are carried out according to a schedule passed to the platform \([details](en_platform_sheduled_recurring_model.md)\). In this case, automatic debiting is used, without additional actions on the part of the merchant.
-   *Autopurchase*—debits are initiated by the web service by sending requests based on specified rules \([details](en_platform_recurring_model.md)\). In this case, to debit funds, each time a separate Gate request is required \([details](pm_dd_sepa.md)\).

At the same time, you can register a COF purchase of any of these types either with or without an initial debit of funds. Please note that for registration without the initial debit the `directdebit` payment type is used, and for registration with the first debit the `purchase` type is used.

To register a COF purchase through Payment Pageby using the Direct Debit SEPA method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the registration result.

Information about the formats of requests and callbacks used for registering purchases by using the Direct Debit SEPA method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format for registration without the initial debit of funds {#section_p5j_fgl_ggb .section}

When registering a COF purchase without the initial debit, the `directdebit` payment type is used, within which the following types of operations can be performed: `contract registration`, `recurring update` \(only when for regular purchases\), `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit SEPA method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount, the `0` value must be specified
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is necessary to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`, as well as the `directdebit-sepa` method code in the `force_payment_method` parameter and the `card_verify` value in the `mode` parameter.
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit SEPA method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [COF purchase registration](en_pp_recurring.md) section.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Direct Debit SEPA method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and COF purchase information, as well as signature.

``` {#codeblock_qy4_bhy_m2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_currency": "EUR",
   "payment_amount": 0,
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "directdebit-sepa",
   "mode": "card_verify",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_yzq_bhy_m2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_currency": "EUR",
   "payment_amount": 0,
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "directdebit-sepa",
   "mode": "card_verify",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Request format for registration with the initial debit of funds {#section_qt3_qfl_j1c .section}

When registering a COF purchase with the initial debit, the `purchase` payment type is used, within which the following types of operations can be performed: `sale`, `reversal`, `refund`, `contract registration`, `recurring update` \(only for regular purchases\) and `recurring cancel` \(only for regular purchases\).

There are several things you need to consider when sending purchase registration requests by using the Direct Debit SEPA method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is necessary to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`.
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit SEPA method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be passed in the `recurring` object is presented in the [COF purchase registration](en_pp_recurring.md) section.
4.  If you need to have the payment form displayed with the Direct Debit SEPA method selected, set the `force_payment_method` parameter to `directdebit-sepa`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Direct Debit SEPA method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "recurring": "{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit SEPA method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a COF purchase without an initial debit of funds that has been registered in the `430716` project.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_342011450",
            "type": "directdebit",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 1,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 9738,
            "currency": "EUR",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2048000011083,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "created_date": "2024-01-19T07:54:38+0000",
            "request_id": "881f81f7cd8e1a11b0903a8d8f98-00002049",
            "sum_initial": {
                "amount": 1,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "K4vshmZkpqPMEHr",
                "auth_code": ""
            }
        },
        "signature": "bepC/BLdBruEdA/1pqB4aJ4KnihVW0pfWM7Y1uAw=="
    }
```

The following is the example of a callback with information about a COF purchase with an initial debit of funds that has been registered in the `430716` project.

```language-json
 {
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_702917140",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 8224,
            "currency": "EUR",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2330000011063,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "created_date": "2024-01-18T12:39:37+0000",
            "request_id": "5f3e8be0ed6967412c89beab965-00002331",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "ZOrsGv5u8fyQ4SM",
                "auth_code": ""
            }
        },
        "signature": "vdTeWodANtRGz80gHPeI+oyYioNu7T/YISzA=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase.

```
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_sepa",
            "type": "directdebit",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 0,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "MD000ZBRK2P769",
                "auth_code": ""
            },
            "id": 51271010116645,
            "type": "contract registration",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "created_date": "2024-02-26T10:54:33+0000",
            "request_id": "741a4d68a1f039c794e309063c4dd-00051272"
        },
        "signature": "+mPKi+A2RMCU7e2S+vXDIUoQzk9rkbwq4dE/xQ=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase and a declined purchase.

```
{
        "customer": {
            "id": "customer 1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_246302",
            "type": "purchase",
            "status": "awaiting customer",
            "date": "2024-02-26T10:46:12+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_246302"
        },
        "operation": {
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "PM009FAY0JJF1G",
                "auth_code": ""
            },
            "id": 63155010115589,
            "type": "sale",
            "status": "decline",
            "date": "2024-02-26T10:46:12+0000",
            "created_date": "2024-02-26T10:45:21+0000",
            "request_id": "35ed3b53c8101de9bacb8601f9cbe2633c56917968e-00063156"
        },
        "signature": "0nENQAYq+xYe5MxS2Qsend4Lt0EPPTpcXfPZdbg5p7WH4ZA=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## COF purchases by using Gate {#en_pm_dd_sepa_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

When using Gate and the Direct Debit SEPA method, you can register COF purchases of two types:

-   *Regular purchase*—regular automatic debits are carried out according to a schedule passed to the platform \([details](en_platform_sheduled_recurring_model.md)\). In this case, automatic debiting is used, without additional actions on the part of the merchant.
-   *Autopurchase*—debits are initiated by the web service by sending requests based on specified rules \([details](en_platform_recurring_model.md)\). In this case, to debit funds, each time a separate request is required.

At the same time, you can register a COF purchase of any of these types either with or without an initial debit of funds. Please note that for registration without the initial debit the `directdebit` payment type is used, and for registration with the first debit the `purchase` type is used.

To register a purchase through Gate by using the Direct Debit SEPA method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Direct Debit SEPA service.
3.  Receive the callback from the payment platform informing about the registration result.

To perform each debit of funds within an autopurchase the merchant's web service is required to send a request with all the required parameters and signature to the Ecommpay URL and receive a callback from the payment platform informing abot the debit result.

Information about the formats of requests and callbacks used for processing payments by using the Direct Debit SEPA method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format for registration without the initial debit of funds {#section_osx_3jl_ggb .section}

When registering a COF purchase without the initial debit, the `directdebit` payment type is used, within which the following types of operations can be performed: `contract registration`, `recurring update` \(only when for regular purchases\), `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit SEPA method:

1.  To register each purchase, send a separate POST request to the `/v2/payment/directdebit/sepa/contract/registration` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/contract/registration](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-contract-registration).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit SEPA method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [Registering COF purchase](en_gate_payment_recurring_registration.md) section.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase registration request by using the Direct Debit SEPA method must contain the project identifier, basic payment information \(identifier and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

### Request format for registration with the initial debit of funds {#section_rkj_vlm_j1c .section}

When registering a COF purchase with the initial debit, the `purchase` payment type is used, within which the following types of operations can be performed: `sale`, `reversal`, `refund`, `contract registration`, `recurring update` \(only for regular purchases\) and `recurring cancel` \(only for regular purchases\). There are several things you need to consider when sending purchase registration requests by using the Direct Debit SEPA method:

1.  To register each purchase, send a separate POST request to the `/v2/payment/directdebit/sepa/sale` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
3.  To register a COF purchase, you must specify a `recurring` object containing the registration attribute and the necessary information. The Direct Debit SEPA method supports two types of COF purchases: `U` \(autopurchase\) and `R` \(regular purchase\). To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of debits of funds. The full list of parameters that can be specified in the `recurring` object is presented in the [Registering COF purchase](en_gate_payment_recurring_registration.md) section.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase registration request by using the Direct Debit SEPA method must contain the project identifier, basic payment information \(identifier, amount and currency code\), customer and COF purchase information, as well as signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recurring": {
      "type": "R",
      "period": "W",
      "interval": 3,
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
      "time": "10:00:00",
      "register": true,
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}
```

### Request format for a separate debit of funds {#section_sxr_kmm_j1c .section}

There are several things you must consider when sending requests for separate debits of funds by using the Direct Debit SEPA method:

1.  To perform each debit, send a separate POST request to the `/v2/payment/directdebit/sepa/recurring` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency code in the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP address relevant for the initiated payout
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct request for a separate debit of funds by using the Direct Debit SEPA method must contain the project and COF purchase identifiers, customer and payment information, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Request format for getting information about a debiting series {#section_slv_pmm_j1c .section}

There are several things you must consider when sending a request for information about a debiting series by using the Direct Debit SEPA method:

1.  To request information each time send a separate POST request to the [/v2/payment/recurring/info](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-recurring-info) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct request for information by using the Direct Debit SEPA method must contain the project, payment and COF purchase identifiers, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Request format for updating a debiting series {#section_zhr_wmm_j1c .section}

There are several things you must consider when updating a debiting series by using the Direct Debit SEPA method:

1.  For each update send a separate POST request to the `/v2/payment/directdebit/sepa/recurring/update` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring/update](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring-update).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  You need also use other parameters of the `recurring` object:
    -   `expiry_year`—expiration year of the COF purchase
    -   `expiry_month`—expiration month of the COF purchase
    -   `expiry_day`—expiration day of the COF purchase
    -   `interval`—multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set `period` to `W` and `interval` to `3`. Possible values: from `1` to `100`
    -   `amount`—amount to debit after registration
    -   `scheduled_payment_id`—ID to assign the COF purchase \(for automatic debiting\)
    -   `period`—debiting period:
        -   `D`—daily
        -   `W`—weekly
        -   `M`—monthly
        -   `Q`—quarterly
        -   `Y`—yearly
    -   `time`—time of subsequent debiting in the `hh:mm:ss` format
    -   `start_date`—date to perform the first debit
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct update request by using the Direct Debit SEPA method must contain project ID, payment ID, signature, ID of debit series, and debit series parameters to update.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890,
    "interval":3,
    "period":"M",
    "time":"12:00:00"
  }
}
```

### Request format for cancelling a COF purchase {#section_zcz_ymm_j1c .section}

There are several things you must consider when cancelling COF purchases by using the Direct Debit SEPA method:

1.  To cancel each purchase, send a separate POST request to the `/v2/payment/directdebit/sepa/recurring/cancel` endpoint. This endpoint belongs to the group [/v2/payment/directdebit/\{payment\_method\}/recurring/cancel](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-directdebit-payment-method-recurring-cancel).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `recurring`—COF purchase information:
        -   `id`—registered COF purchase identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Direct Debit SEPA method must contain the project, payment and COF purchase identifiers, as well as signature.

```language-javascript
 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Direct Debit SEPA method requires redirection of customers from the merchant's web service to the Direct Debit SEPA service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit SEPA method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a COF purchase without an initial debit of funds that has been registered in the `430716` project.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_342011450",
            "type": "directdebit",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 1,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 9738,
            "currency": "EUR",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2048000011083,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-19T07:55:49+0000",
            "created_date": "2024-01-19T07:54:38+0000",
            "request_id": "881f81f7cd8e1a11b0903a8d8f98-00002049",
            "sum_initial": {
                "amount": 1,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "K4vshmZkpqPMEHr",
                "auth_code": ""
            }
        },
        "signature": "bepC/BLdBruEdA/1pqB4aJ4KnihVW0pfWM7Y1uAw=="
    }
```

The following is the example of a callback with information about a COF purchase with an initial debit of funds that has been registered in the `430716` project.

```language-json
 {
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_702917140",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 8224,
            "currency": "EUR",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 2330000011063,
            "type": "contract registration",
            "status": "success",
            "date": "2024-01-18T12:39:38+0000",
            "created_date": "2024-01-18T12:39:37+0000",
            "request_id": "5f3e8be0ed6967412c89beab965-00002331",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "ZOrsGv5u8fyQ4SM",
                "auth_code": ""
            }
        },
        "signature": "vdTeWodANtRGz80gHPeI+oyYioNu7T/YISzA=="
    }
```

The following is the example of a callback with information about a declined registration of a COF purchase.

```
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_sepa",
            "type": "directdebit",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 0,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "MD000ZBRK2P769",
                "auth_code": ""
            },
            "id": 51271010116645,
            "type": "contract registration",
            "status": "decline",
            "date": "2024-02-26T11:10:04+0000",
            "created_date": "2024-02-26T10:54:33+0000",
            "request_id": "741a4d68a1f039c794e309063c4dd-00051272"
        },
        "signature": "+mPKi+A2RMCU7e2S+vXDIUoQzk9rkbwq4dE/xQ=="
    }
```

The following is the example of a callback with information about a separate debit of funds.

```language-json
{
        "project_id": 430716,
        "payment": {
            "id": "ORDER_ID_494065730",
            "type": "recurring",
            "status": "success",
            "date": "2024-01-24T16:02:17+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "recurring": {
            "id": 5768,
            "currency": "EUR",
            "valid_thru": "2034-01-31T23:59:59+0000"
        },
        "operation": {
            "id": 4653000011052,
            "type": "recurring",
            "status": "success",
            "date": "2024-01-24T16:02:17+0000",
            "created_date": "2024-01-24T16:01:49+0000",
            "request_id": "0e716081819385b6448b8c3387c4-00004654",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21153,
                "payment_id": "a5xCcVqriGOJ8Ty",
                "auth_code": ""
            }
        },
        "signature": "VkmznYWPXQOYOqHyH5SuZRdzLab5GW5RUoe67QqBvw=="
    }
```

The following is the example of a callback with information about a declined separate debit of funds.

```language-json
{
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "test_001",
            "type": "recurring",
            "status": "scheduled recurring processing",
            "date": "2024-02-16T11:36:37+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 400,
                "currency": "EUR"
            },
            "description": ""
        },
        "recurring": {
            "valid_thru": "2030-01-31T23:59:59+0000",
            "id": 1721154593,
            "currency": "EUR"
        },
        "operation": {
            "sum_initial": {
                "amount": 400,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 400,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "PM009DFXAP3EQR",
                "auth_code": ""
            },
            "id": 76329010120929,
            "type": "recurring",
            "status": "decline",
            "date": "2024-02-16T11:36:37+0000",
            "created_date": "2024-02-16T11:33:44+0000",
            "request_id": "5e19acd1e577f9f35a52c2706f-00076330"
        },
        "signature": "uUUVa/0siyHKibfL+CRo1cshrlVoJhkGoByn1g=="
    }
```

The following is the example of a callback with information about an updated debiting series.

```language-json
{  
  "project_id":123,
  "recurring":{
    "id":1079,              
    "currency":"EUR",
    "status":"active",       
    "type":"R",
    "expiry_month":"5",    
    "expiry_year":"2025",   
    "period":"M",            
    "period_interval":3,
    "time":"12:00:00"        
  },
  "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...=="
}
```

The following is the example of a callback with information about a cancelled COF purchase.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_878918",
            "type": "purchase",
            "status": "success",
            "date": "2024-02-16T11:08:25+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_878918"
        },
        "operation": {
            "sum_initial": {
                "amount": 0,
                "currency": ""
            },
            "sum_converted": {
                "amount": 0,
                "currency": ""
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16351,
                "payment_id": "MD000Z79BA94NF",
                "auth_code": ""
            },
            "id": 5049531010137015,
            "type": "recurring_cancel",
            "status": "success",
            "date": "2024-02-16T11:39:12+0000",
            "created_date": "2024-02-16T11:38:35+0000",
            "request_id": "6ef48716ca0809f0588e53d3-00094164"
        },
        "signature": "4M8mbH3W5oplKW1ipmZKApYVbTHrdGBNg=="
    }
```

### Response format {#section_mxj_bnm_j1c .section}

The payment platform uses the standard format for response with debit series information. For more information about response format, see [Response format](en_gate_interaction_organisation.md).

```language-json
{
    "project_id": 1602,
    "recurring": {
        "id": 7305,
        "type": "R",
        "period": "W",
        "period_interval": 1,
        "start_date": "2024-02-06",
        "start_time": "00:49:23",
        "amount": 74000,
        "last_payment_at": "0000-00-00 00:00:00",
        "valid_thru": "2027-02-28 23:59:59",
        "status": "active",
        "description": "",
        "schedule_date": {
            "next": "2024-02-13 00:49:23"
        },
        "currency": "EUR"
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_dd_sepa_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Direct Debit SEPA method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Direct Debit SEPA service.
7.  The refund is processed on the side of the Direct Debit SEPA service.
8.  The Direct Debit SEPA service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Direct Debit SEPA method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

**Note:** By default refunds can be performed only after seven calendar days since the purchase has been processed; to enable the possibility of performing refunds before this time, contact your Ecommpay account manager.

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Direct Debit SEPA method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Direct Debit SEPA method must contain the project and payment identifiers, description of the refund, the customer IP address and signature.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_qqj_kyn_42c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Direct Debit SEPA method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `1.00 EUR` refund made in the `59051` project.

```language-json
 {
        "payment": {
            "method_id": 2931,
            "need_confirm_retry": false,
            "actual_amount": 100,
            "cascading_with_redirect": false,
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "status": "refunded",
            "id": "TEST_PAYMENT_175421",
            "method": "Direct Debit BACS",
            "date": "2024-02-12T13:57:14+0000",
            "result_code": "0",
            "result_message": "Success",
            "split_with_redirect": false,
            "provider_id": 16341
        },
        "sum_request": {
            "amount": 0,
            "currency": "EUR"
        },
        "rrn": "",
        "customer": {
            "id": "zxc"
        },
        "request_id": "daf48fcefbe98ca53fc82969c409-00081884",
        "transaction": {
            "id": 81883010089421,
            "date": "2024-02-12T13:57:14+0000",
            "type": "purchase"
        },
        "sum_real": {
            "amount": 100,
            "currency": "EUR"
        },
        "sum_refund": {
            "amount": 100,
            "currency": "EUR"
        },
        "recurring": {
            "id": 1720779781
        },
        "general": {
            "project_id": 59051,
            "payment_id": "TEST_PAYMENT_175421"
        },
        "description": "TEST_PAYMENT_175421",
        "cashout_data": {
            "customer_first_name": "Paul",
            "customer_id": "zxc",
            "customer_last_name": "Allen"
        },
        "signature": "xEumPOToRyH9/PFnyICB7eY/oxVatslhQWw=="
    }
```

The following is the example of a callback with information about a declined refund of an initial debit of funds.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_816625",
            "type": "purchase",
            "status": "success",
            "date": "2024-02-26T11:40:18+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_816625"
        },
        "recurring": {
            "valid_thru": "2034-02-28T23:59:59+0000",
            "id": 1722138911,
            "currency": "EUR"
        },
        "operation": {
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "RF00006W2JHZWT",
                "auth_code": ""
            },
            "id": 83482010120825,
            "type": "refund",
            "status": "decline",
            "date": "2024-02-26T11:40:18+0000",
            "created_date": "2024-02-26T11:39:36+0000",
            "request_id": "b63907d503e7dc24bbe83981a1-00083483"
        },
        "signature": "Si+nDkjd+n/P1rGVwa3DZl5+sQ=="
    }
```

The following is the example of a callback with information about a declined refund of a separate debit of funds.

```language-json
 {
        "customer": {
            "id": "customer1"
        },
        "project_id": 59051,
        "payment": {
            "id": "qweqwe_1231231231001",
            "type": "recurring",
            "status": "success",
            "date": "2024-02-26T11:42:36+0000",
            "method": "Direct Debit SEPA",
            "sum": {
                "amount": 400,
                "currency": "EUR"
            },
            "description": ""
        },
        "recurring": {
            "valid_thru": "2034-02-28T23:59:59+0000",
            "id": 1722138911,
            "currency": "EUR"
        },
        "operation": {
            "sum_initial": {
                "amount": 400,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 400,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16351,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 65138010114741,
            "type": "refund",
            "status": "decline",
            "date": "2024-02-26T11:42:36+0000",
            "created_date": "2024-02-26T11:42:35+0000",
            "request_id": "adc663dacdec30ef1abbc60653e10-00065139"
        },
        "signature": "OTvoVoPScN5N4tvEVhteWi/TQZB6qxew=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_dd_sepa_dash_analysis}

To analyse information about payments made with the Direct Debit SEPA method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Ecuador Online Banking {#pm_ecuador_ob}

An article about the payment method which allows you to process payments in US dollars by using bank accounts in Ecuador and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_ecuador_ob_overview}

An article about the payment method which allows you to process payments in US dollars by using bank accounts in Ecuador and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Ecuador Online Banking is a payment method which allows you to process payments in US dollars by using bank accounts in Ecuador.This method supports purchases and refunds.

This article provides information about working with the Ecuador Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[EC](references/en/countries/EC.md)|
|Payment currencies|[USD](references/en/currencies/USD.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|full or partial refunds can be issued within 90 calendar days after the purchase|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Ecuador Online Banking method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_ecuador_ob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Ecuador Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts¹|Times²|
|minimum|maximum|base|threshold|
|--|--------|------|
|-------|-------|----|---------|
|Purchases|\*|\*|3 minutes|36 hours|
|Refunds|\*|\*|5 minutes|36 hours|

**Note:**

1.  Minimum and maximum payment amounts depend on the banks that the customer can select after redirection to the provider service. The bank will not be available for selection if the payment amount is outside the limits set by the bank.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Ecuador Online Banking method, you need to redirect the customer to the provider service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_ecuador_ob_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_ecuador_ob_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_ecuador_ob_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_ecuador_ob_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Ecuador Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_ecuador_ob_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Ecuador Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Ecuador Online Banking method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps on the provider service side.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Ecuador Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Ecuador Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is also recommended to specify the first and last name and the email of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_email`. To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`.
3.  If you need to have the payment form displayed with the Ecuador Online Banking method selected, set the `force_payment_method` parameter to `online-ecuador-banks`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Ecuador Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature, as well as possible additional parameters.

``` {#codeblock_gdb_pts_w2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_hzt_vsw_x2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Ecuador Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "ecuador",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "ecuador",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_ecuador_ob_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Ecuador Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_ecuador_ob_uml_gate.svg)

1.  A customer initiates a purchase by using the Ecuador Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps on the provider service side.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Ecuador Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Ecuador Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/ecuador/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is required to specify the following objects and parameters:
    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—customer email address
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Ecuador Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

``` {#codeblock_fp4_1tw_x2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Ecuador Online Banking method requires redirection of customers from the merchant's web service to the provider service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Ecuador Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "ecuador",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "ecuador",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_ecuador_ob_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Ecuador Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_ecuador_ob_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The refund is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Ecuador Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Ecuador Online Banking method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Ecuador Online Banking method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_gqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Ecuador Online Banking method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` full refund made by the `1` customer in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_265608",
        "type": "purchase",
        "status": "refunded",
        "date": "2025-06-26T06:48:37+0000",
        "method": "ecuador",
        "sum": {
            "amount": 0,
            "currency": "USD"
        },
        "description": "TEST_PAYMENT_265608"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 7373000014760,
        "type": "refund",
        "status": "success",
        "date": "2025-06-26T06:48:37+0000",
        "created_date": "2025-06-26T06:48:34+0000",
        "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1903,
            "payment_id": "1750920516487",
            "auth_code": ""
        }
    },
    "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ=="
}
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "test_29.04.25_3",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-29T11:36:34+0000",
        "method": "ecuador",
        "sum": {
            "amount": 20000,
            "currency": "USD"
        },
        "description": "test_29.04.25_3"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 5557000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-29T11:22:44+0000",
        "created_date": "2024-12-29T11:22:44+0000",
        "request_id": "c717b3de84d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21514,
            "payment_id": "1418092457",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Ecuador Online Banking method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_ecuador_ob.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_ecuador_ob_dash_analysis}

To analyse information about payments made with the Ecuador Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# EPS {#pm_eps}

An article about the payment method which allows you to process payments in euros by using bank accounts in Austria and supports purchases.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_eps_overview}

An article about the payment method which allows you to process payments in euros by using bank accounts in Austria and supports purchases.

### Introduction {#section_t5z_rlg_ytb .section}

EPS is a payment method which allows you to process payments in euros by using bank accounts in Austria.This method supports purchases.

This article provides information about working with the EPS method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[AT](references/en/countries/AT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|–|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/eps/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the EPS method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the EPS service.

![](images/pm/eng_eps_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the EPS method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [EUR](references/en/currencies/EUR.md)¹|Times²|
|minimum|maximum|Basic|Threshold|
|--|------------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|1.00|10,000.00|within 10 minutes|up to 48 hours|

**Note:**

1.  Refer to the Ecommpay key account manager for more information on amount limits.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the EPS method, you need to redirect the customer to the EPS service.

![](images/pm/eng_eps_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_eps_interfaces_gate.svg "Purchase by using Gate")

## Purchases by using Payment Page {#en_pm_eps_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the EPS method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_eps_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the EPS method.
8.  The payment platform receives the request for processing the payment by using the EPS method.
9.  The payment platform processes the request and sends it to the EPS service.
10. The request is processed on the EPS service side.
11. The data for redirecting the customer to the EPS service is sent from the EPS service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the EPS service.
14. The customer completes all required payment steps.
15. The purchase is processed in the EPS service.
16. The result information is displayed to the customer in the EPS service.
17. The customer is redirected to Payment Page.
18. The EPS service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the EPS method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the EPS method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first, last names and email address of the customer in the parameters `customer_first_name`, `customer_last_name`, `customer_email`. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  If you need to have the payment form displayed with the EPS method selected, set the `force_payment_method` parameter to `eps`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the EPS method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "John@mail.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "John@mail.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The EPS method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_1560760354708",
            "type": "purchase",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "method": "eps",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 29891000002914,
            "type": "sale",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "created_date": "2019-06-17T08:50:34+0000",
            "request_id": "0d6aabd20c7925f1719b7cb63f728b32a3450cf0",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": "148907",
                "date": "2019-06-17T08:56:46+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "V0zYWk7OzwfcMBAJJxArOuQoQfNv92z0wBJeQIHwj75hpkuXFNqHjYGMdfhycMw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_156162712312",
            "type": "purchase",
            "status": "decline",
            "date": "2019-06-27T12:53:58+0000",
            "method": "eps",
            "sum": {
                "amount": 500,
                "currency": "USD"
            },
            "description": "TEST_1561627597648"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 1590021,
            "type": "sale",
            "status": "decline",
            "date": "2019-06-27T12:53:58+0000",
            "created_date": "2019-06-27T12:49:41+0000",
            "request_id": "935dc4ba8b35ca5046",
            "sum_initial": {
                "amount": 500,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 440,
                "currency": "EUR"
            },
            "provider": {
                "id": 1239,
                "payment_id": "922806",
                "date": "2019-06-27T12:53:57+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "S4qhcifHHzZgnOwRC0GSsEfoPl9zyGnNp7g=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_eps_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the EPS method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the EPS service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_eps_uml_gate.svg)

1.  A customer initiates a purchase by using the EPS method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the EPS service.
7.  The request is processed on the EPS service side.
8.  The EPS service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the EPS service.
11. The customer completes all required payment steps.
12. The purchase is processed in the EPS service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The EPS service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the EPS method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the EPS method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/bank-transfer/eps/sale` endpoint. This endpoint belongs to the group [/v2/payment/bank-transfer/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/bank-transfer/post-v2-payment-bank-transfer-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
        -   `email`—customer email address
    -   Object `return_url`—contains the URLs to which customer is redirected during or after payment processing:
        -   `return`—URL for redirecting a customer during a purchase
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the EPS method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, URL for redirection and signature.

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": "payment_id",
        "signature": "PJkV8ej\/UG0Di8NN5e7cIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
      "ip_address": "192.0.2.0",
      "email": "Johnson@mail.com",
      "first_name": "John",
      "last_name": "Johnson",
      "id": "123"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "return_url": {
      "return": "http://example.com"
    }
}
```

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": "payment_id",
        "signature": "PJkV8ej\/UG0Di8NN5e7cIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
      "ip_address": "192.0.2.0",
      "email": "Johnson@mail.com",
      "first_name": "John",
      "last_name": "Johnson",
      "id": "123"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "return_url": {
      "return": "http://example.com"
    }
}
```

### Formats of intermediate callbacks for customer redirection {#section_mwj_mnh_pzb .section}

Each payment made with the EPS method requires redirection of customers from the merchant's web service to the EPS service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The EPS method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_1560760354708",
            "type": "purchase",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "method": "eps",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 29891000002914,
            "type": "sale",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "created_date": "2019-06-17T08:50:34+0000",
            "request_id": "719b7cb63f728b32a3450cf0",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": "148907",
                "date": "2019-06-17T08:56:46+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "V0zYWk7OzwfcMBAJJxArOuQoQfNv92z0wBJeQIHwj75huXFNqHjYGMdfhycMw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_156162712312",
            "type": "purchase",
            "status": "decline",
            "date": "2019-06-27T12:53:58+0000",
            "method": "eps",
            "sum": {
                "amount": 500,
                "currency": "USD"
            },
            "description": "TEST_1561627597648"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 1590021,
            "type": "sale",
            "status": "decline",
            "date": "2019-06-27T12:53:58+0000",
            "created_date": "2019-06-27T12:49:41+0000",
            "request_id": "935dc4ba8b35ca5046",
            "sum_initial": {
                "amount": 500,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 440,
                "currency": "EUR"
            },
            "provider": {
                "id": 1239,
                "payment_id": "922806",
                "date": "2019-06-27T12:53:57+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "S4qhcifHHzZgnOwRC0GSsEfoPl9zyGnNp7g=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_eps_dash_analysis}

To analyse information about payments made with the EPS method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# iDEAL \| Wero {#pm_ideal}

An article about the payment method which allows to process payments in euros by using bank accounts in the Netherlands and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_ideal_overview}

An article about the payment method which allows to process payments in euros by using bank accounts in the Netherlands and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

iDEAL \| Wero is a payment method which allows to process payments in euros by using bank accounts in the Netherlands.This method supports purchasesand refunds.

This article provides information about working with the iDEAL \| Wero method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[NL](references/en/countries/NL.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|–|
|Onboarding and access fee|refer to your Ecommpay key account manager, additional information available in the [Ecommpay shop](https://ecommpay.com/shop/payment-methods/ideal/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the iDEAL \| Wero method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the iDEAL \| Wero service.

![](images/pm/en_ideal_wero_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the iDEAL \| Wero method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following limitations are applicable.

| |Amounts, [EUR](references/en/currencies/EUR.md)|
|minimum|maximum|
|--|-----------------------------------------------|
|-------|-------|
|Purchases|0,01|–|
|Full refunds|–|–|
|Partial refunds|–|–|

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the iDEAL \| Wero method, you need to redirect customer to the iDEAL \| Wero service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_ideal_wero_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_ideal_wero_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_ideal_wero_interfaces_gate_refund.svg "Refund by using Gate")



Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_ideal_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the iDEAL \| Wero method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_ideal_wero_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the iDEAL \| Wero method.
8.  The payment platform receives the request for processing the payment by using the iDEAL \| Wero method.
9.  The payment platform processes the request and sends it to the iDEAL \| Wero service.
10. The request is processed on the iDEAL \| Wero service side.
11. The data for redirecting the customer to the iDEAL \| Wero service is sent from the iDEAL \| Wero service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the iDEAL \| Wero service.
14. The customer completes all required payment steps.
15. The purchase is processed in the iDEAL \| Wero service.
16. The result information is displayed to the customer in the iDEAL \| Wero service.
17. The customer is redirected to Payment Page.
18. The iDEAL \| Wero service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the iDEAL \| Wero method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when requesting a payment through the iDEAL \| Wero method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  The currency of a payment can only be [EUR](references/en/currencies/EUR.md).
3.  Additionally, it is required to specify the firs and last names of the customer in the `customer_first_name` and `customer_last_name` parameters. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
4.  If you need to have the payment form displayed with the iDEAL \| Wero method selected, set the `force_payment_method` parameter to `ideal`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the iDEAL \| Wero method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

``` {#codeblock_xrt_n5w_m2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The iDEAL \| Wero method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json

{
        "project_id": 238,
        "payment": {
            "id": "TEST_15452119890903333",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-20T13:40:56+0000",
            "method": "ideal",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1545211989090"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 18496000002369,
            "type": "sale",
            "status": "success",
            "date": "2018-12-20T13:40:56+0000",
            "created_date": "2018-12-20T13:40:15+0000",
            "request_id": "768e72d3284eb2b269e4f3",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": "353827769",
                "date": "2018-12-20T13:40:56+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "ylWj/35wPzQRs+9dWcCYMduHnXwxMxYZy17g=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json

{
        "project_id": 1569,
        "payment": {
            "id": "145408-190628095914-cmY0LnByZ=",
            "type": "purchase",
            "status": "decline",
            "date": "2019-06-28T09:59:58+0000",
            "method": "ideal",
            "sum": {
                "amount": 300,
                "currency": "EUR"
            },
            "description": "3 Tage Premium-Mitgliedschaft"
        },
        "customer": {
            "id": "145408"
        },
        "operation": {
            "id": 33841000003201,
            "type": "sale",
            "status": "decline",
            "date": "2019-06-28T09:59:58+0000",
            "created_date": "2019-06-28T09:59:16+0000",
            "request_id": "cef7a32aa22a4e4bc8",
            "sum_initial": {
                "amount": 300,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": "474810276",
                "date": "2019-06-28T09:59:45+0000",
                "auth_code": ""
            },
            "code": "20301",
            "message": "Account owner cancelled operation"
        },
        "signature": "LifBDhURocEq9eVkzL1UxRCp1JNbQ9M46TyotjGT5io17TSw=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_ideal_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the iDEAL \| Wero method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the iDEAL \| Wero service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_ideal_wero_uml_gate.svg)

1.  A customer initiates a purchase by using the iDEAL \| Wero method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the iDEAL \| Wero service.
7.  The request is processed on the iDEAL \| Wero service side.
8.  The iDEAL \| Wero service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the iDEAL \| Wero service.
11. The customer completes all required payment steps.
12. The purchase is processed in the iDEAL \| Wero service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The iDEAL \| Wero service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the iDEAL \| Wero method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the iDEAL \| Wero method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/online-banking/ideal/sale` endpoint. This is an online banking endpount group: [/v2/payment/online-banking/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/online-banking/post-v2-payment-online-banking-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   `return_url`—URL for redirecting the customer:
        -   `return`—URL for redirecting a customer during any step of the purchase
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission \(details are available in [Submission of additional payment information](en_Gate_Clarification.md)\).
4.  The currency of a payment can only be [EUR](references/en/currencies/EUR.md).
5.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the iDEAL \| Wero method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and URL for redirection, as well as signature.

``` {#codeblock_y4m_n5w_m2c .language-json}
{
    "general": {
        "project_id": 2990,
        "payment_id": "payment_id",
        "signature": "PJkV8ej\/UG0OMeSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
      "ip_address": "192.0.2.0",
      "first_name": "John",
      "last_name": "Johnson",
      "id": "123"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "return_url": {
      "return": "http://example.com"
    }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the iDEAL \| Wero method requires redirection of customers from the merchant's web service to the iDEAL \| Wero service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The iDEAL \| Wero method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json

{
        "project_id": 238,
        "payment": {
            "id": "TEST_15452119890903333",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-20T13:40:56+0000",
            "method": "ideal",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1545211989090"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 18496000002369,
            "type": "sale",
            "status": "success",
            "date": "2018-12-20T13:40:56+0000",
            "created_date": "2018-12-20T13:40:15+0000",
            "request_id": "768e72d3284eb2b269e4f3",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": "353827769",
                "date": "2018-12-20T13:40:56+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "ylWj/35wPzQRs+9dWcCYMduHnXwxMxYZy17g=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json

{
        "project_id": 1569,
        "payment": {
            "id": "145408-190628095914-cmY0LnByZ=",
            "type": "purchase",
            "status": "decline",
            "date": "2019-06-28T09:59:58+0000",
            "method": "ideal",
            "sum": {
                "amount": 300,
                "currency": "EUR"
            },
            "description": "3 Tage Premium-Mitgliedschaft"
        },
        "customer": {
            "id": "145408"
        },
        "operation": {
            "id": 33841000003201,
            "type": "sale",
            "status": "decline",
            "date": "2019-06-28T09:59:58+0000",
            "created_date": "2019-06-28T09:59:16+0000",
            "request_id": "cef7a32aa22a4e4bc8",
            "sum_initial": {
                "amount": 300,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": "474810276",
                "date": "2019-06-28T09:59:45+0000",
                "auth_code": ""
            },
            "code": "20301",
            "message": "Account owner cancelled operation"
        },
        "signature": "LifBDhURocEq9eVkzL1UxRCp1JNbQ9M46TyotjGT5io17TSw=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_ideal_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the iDEAL \| Wero method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_ideal_wero_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the iDEAL \| Wero service.
7.  The refund is processed on the side of the iDEAL \| Wero service.
8.  The iDEAL \| Wero service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the iDEAL \| Wero method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the iDEAL \| Wero method:

1.  To initiate each refund, send a separate POST request to the `/v2/payment/online-banking/ideal/refund` enpoint. This is an online banking endpoint group: [/v2/payment/online-banking/\{payment\_method\}/refund](https://api-developers.ecommpay.com/api-specification/online-banking/post-v2-payment-online-banking-payment-method-refund).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the iDEAL \| Wero method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

```language-json
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The iDEAL \| Wero method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `1.00 EUR` refund made in the `238` project.

```language-json
 
{
        "project_id": 238,
        "payment": {
            "id": "TEST_15611060328012",
            "type": "purchase",
            "status": "refunded",
            "date": "2019-06-21T11:15:40+0000",
            "method": "ideal",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": ""
        },
        "provider_extra_fields": {
            "description": "Refund"
        },
        "operation": {
            "id": 36084000003050,
            "type": "refund",
            "status": "success",
            "date": "2019-06-21T11:15:40+0000",
            "created_date": "2019-06-21T11:15:38+0000",
            "request_id": "ec1a34153dc43fe1bae7b6397",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": "105796085",
                "date": "2019-06-21T11:15:39+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "DtwI1Wbg6Wda71k/xy0dGWGE2qHhfA7naVeEk0wtfqg=="
    }
```

The following is the example of a callback with information about a declined refund.

```language-json

{
        "project_id": 238,
        "payment": {
            "id": "TEST_15611060328012",
            "type": "purchase",
            "status": "success",
            "date": "2019-06-21T08:39:50+0000",
            "method": "ideal",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": ""
        },
        "errors": [
            {
                "code": "100",
                "message": "General decline",
                "description": "Gate. Operation was declined. General Gate error"
            }
        ],
        "operation": {
            "id": 36084000003046,
            "type": "refund",
            "status": "decline",
            "date": "2019-06-21T09:42:44+0000",
            "created_date": "2019-06-21T09:42:44+0000",
            "request_id": "5d0c7bf5304685ab9c9613a8e9a86",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1170,
                "payment_id": ""
            },
            "code": "100",
            "message": "General decline"
        },
        "signature": "AX+FugJdXi3kHaIUiIjCpaTk94+4gIvrhj/6n3PBA=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_ideal_dash_analysis}

To analyse information about payments made with the iDEAL \| Wero method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Indonesian Online Banking {#pm_indonesia}

An article about the payment method which allows to process payments in Indonesian rupiahs by using bank accounts in Indonesia and supports purchases and payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_indonesia_overview}

An article about the payment method which allows to process payments in Indonesian rupiahs by using bank accounts in Indonesia and supports purchases and payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Indonesian Online Banking is a payment method which allows to process payments in Indonesian rupiahs by using bank accounts in Indonesia.This method supports purchases and payouts.

This article provides information about working with the Indonesian Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[ID](references/en/countries/ID.md)|
|Payment currencies|[IDR](references/en/currencies/IDR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Notes|-   Payment Page supports different [bank selection options](pm_indonesia.md#section_p5j_fgl_ggb)
-   in this method all payment amounts in [IDR](references/en/currencies/IDR.md) are integer. If the currency [IDR](references/en/currencies/IDR.md) is specified in the payment request it is necessary to round the payment amount to an integer, otherwise the fractional part is severed during processing on the payment platform side. If another currency is specified in the request, the payment amount is converted to an equivalent amount in the [IDR](references/en/currencies/IDR.md) currency on the Ecommpay side and rounded to 1,000.00 [IDR](references/en/currencies/IDR.md)
-   Safari browser may not support the redirection to a bank service. For more information refer to the Ecommpay key account manager

|
|Onboarding and access fee|refer to your Ecommpay key account manager; more information is available in the [Ecommpay shop](https://ecommpay.com/shop/payment-methods/online-banking-indonesia/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Indonesian Online Banking method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the bank service.

![](images/pm/en_banks_indonesia_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Indonesian Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), payouts—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [IDR](references/en/currencies/IDR.md)|Times²|
|minimum|maximum|base|threshold|
|--|-----------------------------------------------|------|
|-------|-------|----|---------|
|Purchases|100 000.00|25,000 000.00|\*|\*|
|Payouts|100 000.00|10,000 000.00|\*|\*|

**Note:**

1.  Keep in mind that payment processing times depend on banks, that support purchases by using this payment method.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Indonesian Online Banking method, you need to redirect customer to the Indonesian Online Banking service, while to initiate a payout, you need to notify the customer via the web service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_4.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_5.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_6.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_indonesia_7.svg "Redirecting to the web service")

General scenarios of processing purchases and payouts can be presented as follows.

![](images/pm/en_banks_overview_pp.svg "Purchase by using Payment Page")

![](images/pm/en_banks_overview_gate_purchase.svg "Purchase by using Gate")

![](images/pm/en_banks_overview_gate_payout.svg "Payout by using Gate")

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselected as well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_indonesia.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_indonesia.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of banks supported by the Indonesian Online Banking method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|Purchase|Payout|
|----|--|--------|------|
|Bank Artha Graha|2871|–|+|
|Bank Bukopin|549|–|+|
|Bank Central Asia|140|+|+|
|Bank CIMB Niaga|507|–|+|
|Bank Commonwealth|567|–|+|
|Bank Danamon Indonesia|398|–|+|
|Bank HSBC|513|–|+|
|Bank Mandiri|143|+|+|
|Bank Maspion|2891|–|+|
|Bank MayBank Indonesia|565|–|+|
|Bank Mega|547|–|+|
|Bank Mestika|2901|–|+|
|Bank Negara Indonesia|141|+|+|
|Bank OCBC NISP|509|–|+|
|Bank Panin|506|–|+|
|Bank Permata|396|–|+|
|Bank Rakyat Indonesia|142|+|+|
|Bank Rakyat Indonesia Syariah|545|–|+|
|Bank Sinar Mas|2911|–|+|
|Bank Sumut|525|–|+|
|Bank Tabungan Pensiunan Nasional /BTPN|544|–|+|
|Bank UOB Buana Indonesia|508|–|+|
|OCBC Indonesia|2921|–|+|

Since the list of available banks may change over time, it is recommended to send a POST request to the one of the following endpoints: `/v2/info/banks/indonesia/sale/list` for purchases and `/v2/info/banks/indonesia/payout/list` for payouts to obtain up-to-date information. These endpoints belong to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "IDR"
  }
}
```

```language-json
[
  {
    "id": 507, // Bank ID
    "abbr": "CIMB", // Bank abbreviation (for internal use)
    "name": "BANK CIMB NIAGA", // International bank name
    "nativeName": "Bank CIMB Niaga", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 982, // Currency ID in the payment platform
        "alpha_3_4217": "IDR", // ISO-4217 alphabetic currency code
        "number_3_4217": "360", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 2901, 
    "abbr": "BMTK", 
    "name": "Bank Mestika", 
    "nativeName": "Bank Mestika", 
    "currencies": [
      {
        "id": 982,
        "alpha_3_4217": "IDR",
        "number_3_4217": "360",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2871, 
    "abbr": "BAG", 
    "name": "Bank Artha Graha", 
    "nativeName": "Bank Artha Graha",
    "currencies": [
      {
        "id": 982,
        "alpha_3_4217": "IDR",
        "number_3_4217": "360",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Indonesian Online Banking method, refer to your Ecommpay account manager.

## Purchases by using Payment Page {#en_pm_indonesia_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Indonesian Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_banks_indonesia_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Indonesian Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Indonesian Online Banking method.
9.  The payment platform processes the request and sends it to the bank service.
10. The request is processed on the bank service side.
11. The data for redirecting the customer to the bank service is sent from the bank service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the bank service.
14. The customer completes all required payment steps.
15. The purchase is processed in the bank service.
16. The result information is displayed to the customer in the bank service.
17. The customer is redirected to Payment Page.
18. The bank service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Indonesian Online Banking method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_indonesia.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_asian_banking_pp_1_indonesia.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_asian_banking_pp_2_indonesia.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_asian_banking_pp_4_indonesia.svg "3—Selecting bank among all available banks")

![](images/universal/pm/splits/en_asian_banking_pp_5_indonesia.svg "4—Selecting bank among specific banks")

![](images/universal/pm/splits/en_asian_banking_pp_6_indonesia.svg "5—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Indonesian Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Indonesian Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option in the `payment_methods_options` object specify the `online_indonesian_banks` object containing the `split_banks` parameter with the value `true`:

        ```language-json
        "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true}}"
        ```

    3.  *Selecting a bank among all available ones on Payment Page \(3\)*—for this option specify the method code `online-indonesian-banks` in the `force_payment_method` parameter.
    4.  *Selecting a bank among specific ones on Payment Page \(4\)*—for this option specify the following:
        -   the online-indonesian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_indonesian_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifiers:

            ```language-json
            "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [140, 141]}}"
            ```

    5.  *Confirming redirection to the service of the specific bank on Payment Page \(5\)*—for this option specify the following:
        -   the online-indonesian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_indonesian_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifier:

            ```language-json
            "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [140]}}"
            ```

3.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
4.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Indonesian Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 20000000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 20000000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000000,
   "payment_currency": "THB",
   "customer_id": "customer1",
   "force_payment_method": "online-indonesian-banks",
   "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [140, 141]}}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The standard format for callbacks is used to deliver purchase results from Indonesian Online Banking. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `200,000.00 IDR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "154383173598055",
            "type": "purchase",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "1543831735980"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15788000002076,
            "type": "sale",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "created_date": "2022-09-03T10:40:20+0000",
            "request_id": "72cb91e7586004",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "",
                "date": "2022-09-03T10:44:27+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Cug4rIB6OimEkwmMBi00YrFyBErmi0OVw34WpHt5CzEA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "154356886034811111",
            "type": "purchase",
            "status": "decline",
            "date": "2022-09-10T14:11:13+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "154356886034811111"
        },
        "operation": {
            "id": 9830000002095,
            "type": "sale",
            "status": "decline",
            "date": "2022-09-10T14:11:13+0000",
            "created_date": "2022-09-10T14:11:06+0000",
            "request_id": "3b14e5b0fd1",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 10,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "cQbMiD0pON9eJc5QiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_indonesia_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Indonesian Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the bank service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_banks_indonesia_uml_gate.svg)

1.  A customer initiates a purchase by using the Indonesian Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The request is processed on the bank service side.
8.  The bank service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the bank service.
11. The customer completes all required payment steps.
12. The purchase is processed in the bank service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The bank service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Indonesian Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Indonesian Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/indonesia/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  The following objects and parameters must be specified in the request:
    -   Object general—general purchase information:
        -   project\_id—the project ID obtained from Ecommpay
        -   payment\_id—payment ID unique within the project
        -   signature—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object customer—customer information:
        -   id—the unique ID of the customer within your project
        -   ip\_address—customer IP address
    -   Object payment—purchase information:
        -   amount—rounded up integer purchase amount in minor currency units. On the merchant side, customers should be warned about rounding.
        -   currency—purchase currency in ISO-4217 alpha-3 format
    -   Object account—customer account information:
        -   bank\_id—bank identifier
3.  If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request through the Indonesian Online Banking method must include project, payment, customer, and bank IDs, customer IP-address, signature, currency and amount of the purchase, as shown in the following example:

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176"
    },
    "account":{
      "bank_id": 140
    }
}
```

### Formats of the customer redirection data {#section_nxg_hmn_zgb .section}

To redirect a customer from the web service to the bank site, you must receive a callback from the payment platform containing the URL for redirection in the redirect\_data.url parameter and data to be sent in the request body in the redirect\_data.body parameter, and use these parameters when opening the bank's HTML page using the method specified in the redirect\_data.method parameter.

The following is the callback fragment containing the redirection data.

```language-json

"redirect_data": {
            "body": {},
            "method": "POST",
            "url": "https://www.example.com/payment.php"
        },
```

### Callback format {#section_wsx_3jl_ggb .section}

In the Indonesian Online Banking method, the callbacks that deliver purchase results use the standard format described in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `200,000.00 IDR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "154383173598055",
            "type": "purchase",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "1543831735980"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15788000002076,
            "type": "sale",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "created_date": "2022-09-03T10:40:20+0000",
            "request_id": "72cb91e7586004",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "",
                "date": "2022-09-03T10:44:27+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Cug4rIB6OimEkwmMBi1OyBErmi0OVw34WpHt5CzEA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "154356886034811111",
            "type": "purchase",
            "status": "decline",
            "date": "2022-09-10T14:11:13+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "154356886034811111"
        },
        "operation": {
            "id": 9830000002095,
            "type": "sale",
            "status": "decline",
            "date": "2022-09-10T14:11:13+0000",
            "created_date": "2022-09-10T14:11:06+0000",
            "request_id": "3b14e5b0fd1",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 10,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "cQbMiD0pON9eJc5ZugiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Gate {#en_pm_indonesia_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Indonesian Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/en_banks_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Indonesian Online Banking method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The payout is processed on the side of the bank service.
8.  The bank service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Indonesian Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Indonesian Online Banking method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/banks/indonesia/payout` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payout
    -   Object `account`—customer account information:
        -   `number`—customer account number
        -   `bank_id`—bank identifier
        -   `customer_name`—bank account holder's name
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Indonesian Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and account information, as well as signature.

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNN5e7aRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176"
    },
    "account":{
      "bank_id": 140,
      "customer_name": "Putra account",
      "number": "314159265358979"
    }
}
```

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNN5e7aRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176"
    },
    "account":{
      "bank_id": 140,
      "customer_name": "Putra account",
      "number": "314159265358979"
    }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

In the Indonesian Online Banking method, the callbacks that deliver payout results use the standard format described in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `200,000.00 IDR` payout made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "PAYOUT7891022555",
            "type": "payout",
            "status": "success",
            "date": "2022-09-12T13:28:58+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "payout"
        },
        "account": {
            "number": "6419422222",
            "bank_id": 140,
            "region_id": 236
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15112000002236,
            "type": "payout",
            "status": "success",
            "date": "2022-09-12T13:28:58+0000",
            "created_date": "2022-09-12T13:22:15+0000",
            "request_id": "b54610e94a76",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "E80NPPQ6Z1YSYPZTPH0NBON42",
                "date": "2022-09-12T13:28:34+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "qV2FRs/wxoOaywQS0GpMkoW80mynkaQfSAUJpfQ=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "PAYOUT789",
            "type": "payout",
            "status": "decline",
            "date": "2022-09-07T09:44:43+0000",
            "method": "Indonesian banks",
            "sum": {
                "amount": 5000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "6419422222",
            "bank_id": 140,
            "region_id": 236
        },
        "customer": {
            "id": "1"
        },
        "errors": [
            {
                "code": "3104",
                "message": "Payment Constraint Invalid Payout Amount",
                "description": "Gate. Operation was declined. Maximum payout limit is exceeded"
            }
        ],
        "operation": {
            "id": 533000002202,
            "type": "payout",
            "status": "decline",
            "date": "2022-09-07T09:44:43+0000",
            "created_date": "2022-09-07T09:44:43+0000",
            "request_id": "205d3536a91f2a602dd42fa7d248258224fe3f6",
            "sum_initial": {
                "amount": 5000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1153,
                "payment_id": ""
            },
            "code": "3104",
            "message": "Payment Constraint Invalid Payout Amount"
        },
        "signature": "j4cxKDvx0EaDe4zKLbt6v83rzDMlinxE915lAWGHKVjurpQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Indonesian Online Banking method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_indonesia.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Testing {#en_pm_indonesia_testing}

### General information {#section_zqw_xfw_xjb .section}

For the Indonesian Online Banking method, it is possible to test purchases by using Payment Page and Gate, as well as payouts by using Gate. To enable and disable testing, as well getting assistance with setting up a test project, refer to Ecommpay technical support.

When testing payments keep in mind that the test project identifier must be indicated in requests, the interfaces of the emulator of Payment Page and Indonesian Online Banking payment forms can differ from the production environment.

### Test payments statuses {#section_j1z_1s5_zjb .section}

The final status of test payments and operations is determined by the amount specified in the request.

Test purchases:

-   `40000` or `40400` amount to get the `decline` status
-   any other amount to get the `success` status

Test payouts:

-   `40000` or `40400` amount to get the `decline` status
-   any other amount to get the `success` status

### Purchases by using Payment Page {#section_wlk_dgw_xjb .section}

To perform a test purchase by using Payment Page, do the following:

1.  Send a correct test request for Payment Page opening to the payment platform.
2.  If the `online-indonesian-banks` method was not specified in the request—select the method on the emulator page.
3.  If multiple banks are available for selection, select a bank; if only one bank is available, click the **Pay** button.
4.  Click the **Success** or **Decline** button \(depending on the amount specified in the request\).
5.  Receive the final callback with information about the payment result.

More information about processing purchases by using the Indonesian Online Banking method via Payment Page is provided in the [Purchases by using Payment Page](pm_indonesia.md) section.

### Purchases by using Gate {#section_uvm_ngw_xjb .section}

To perform a test purchase by using Gate, do the following:

1.  Send a correct test request for purchase to the payment platform \(the bank\_id parameter must be used in the request, refer to Ecommpay technical support for the parameter value\).
2.  Accept a callback with redirection data.
3.  Go to the received URL and click the **Success** or **Decline** button \(depending on the amount specified in the request\).
4.  Receive the final callback with information about the payment result.

More information about processing purchases by using the Indonesian Online Banking method via Gate is provided in the [Purchases by using Gate](pm_indonesia.md) section.

### Payouts by using Gate {#section_wwc_xhw_xjb .section}

o process a test payout by using Gate, send a valid test request for a payout to the payment platform and receive a final callback with information about the payout result. More information about processing payouts by using the Indonesian Online Banking method via Gate is provided in the [Payouts by using Gate](pm_indonesia.md) section.

## Analysis of payments results {#en_pm_indonesia_dash_analysis}

To analyse information about payments made with the Indonesian Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Indonesian Virtual Accounts {#pm_indonesia_va}

An article about the payment method which allows to process payments in Indonesian rupiahs by using cash, bank accounts, and payment cards in Indonesia and supports purchases.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_indonesia_va_overview}

An article about the payment method which allows to process payments in Indonesian rupiahs by using cash, bank accounts, and payment cards in Indonesia and supports purchases.

### Introduction {#section_t5z_rlg_ytb .section}

|Indonesian Virtual Accounts is a payment method which allows to process payments in Indonesian rupiahs by using cash, bank accounts and payment cards in Indonesia.This method supports purchases.

 This method is the most popular Indonesian alternative payment method that requires the customer to transfer funds to virtual bank account via a banking mobile application, internet banking or physically via ATM. A Virtual Account \(VA\), 16 digit payment code, is an account created and assigned to each of your paying clients automatically in response to the payment request so that your business would be able to differentiate each payment from the payment source. Ecommpay creates a virtual bank account on an interbank network that is unique to the payment. The payments made to the different Virtual Accounts will be automatically aggregated into the merchant's master account.

 The customer uses provided information to do a bank transfer into the virtual account before the account expires. A client can perform the bank transfer in the following ways:

 -   Physically going to the ATM
-   Mobile banking through bank applications
-   Internet banking

 Most \(80 %\) of transactions in Indonesia occur via bank transfer. Ecommpay offers payment processing with major banks in Indonesia—Mandiri, Permata, Danamon, CIMB.

 This article provides information about working with the Indonesian Virtual Accounts method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

|![](images/pm/indonesia_va_payment_instructions.png)|

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|-   cash
-   bank accounts
-   payments cards

|
|Countries and regions|[ID](references/en/countries/ID.md)|
|Payment currencies|[IDR](references/en/currencies/IDR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Notes|Payment Page supports different [bank selection options](pm_indonesia_va.md#section_dhh_vmq_cnb)|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information available in the [Ecommpay shop](https://ecommpay.com/shop/payment-methods/virtual-accounts-indonesia/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Indonesian Virtual Accounts method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_indonesiava_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Indonesian Virtual Accounts method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [IDR](references/en/currencies/IDR.md)¹|Times²|
|Minimum|Maximum|basic|threshold|
|--|------------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|\*|\*|–|48 hours|

**Note:**

1.  For the most recent amount limits, contact your Ecommpay key account manager.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Indonesian Virtual Accounts method, you need to redirect customer to the provider service.

![](images/pm/eng_indonesiava_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_indonesiava_interfaces_gate.svg "Purchase by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselected as well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_indonesia_va.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_indonesia_va.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of banks supported by the Indonesian Virtual Accounts method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|:---|::|
|Bank Sahabat Sampoerna VA|4391|
|Permata Virtual Account|433|
|Mandiri Virtual Account|434|
|Maybank Virtual Account|2831|
|BNI Virtual Account|2931|
|BRI Virtual Account|499|
|Sinarmas Virtual Account|562|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/indonesia-va/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000000,
    "currency": "IDR"
  }
}
```

```language-json
[
  {
    "id": 433, // Bank ID
    "abbr": "PMBVA", // Bank abbreviation (for internal use)
    "name": "Permata VA", // International bank name
    "nativeName": "Permata VA", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 982, // Currency ID in the payment platform
        "alpha_3_4217": "IDR", // ISO-4217 alphabetic currency code
        "number_3_4217": "360", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 434, 
    "abbr": "MDRIVA", 
    "name": "Mandiri VA", 
    "nativeName": "Mandiri VA", 
    "currencies": [
      {
        "id": 982,
        "alpha_3_4217": "IDR",
        "number_3_4217": "360",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2931, 
    "abbr": "BNIVA", 
    "name": "BNI Virtual Account", 
    "nativeName": "BNI VA", 
    "currencies": [
      {
        "id": 982,
        "alpha_3_4217": "IDR",
        "number_3_4217": "360",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Indonesian Virtual Accounts method, refer to your Ecommpay account manager.

## Purchases by using Payment Page {#en_pm_indonesia_va_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Indonesian Virtual Accounts method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_indonesiava_uml_pp.svg "Purchase by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the banks supported by the Indonesian Virtual Accounts method.
8.  The payment platform receives the request for processing the payment by using the Indonesian Virtual Accounts method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider website, where a 16 digit code and payment instructions are displayed to the customer.
14. In accordance with the payment instructions the customer enters the code on either the bank website, bank mobile application or the ATM, and confirms the purchase.
15. The purchase is processed in the provider service.
16. The provider service sends a notification about the result to the payment platform.
17. The payment platform sends the payment result callback to the web service.
18. The payment platform sends the result information to Payment Page.
19. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Indonesian Virtual Accounts method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_indonesia_va.md#section_dhh_vmq_cnb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_asian_banking_pp_1_indonesia_va.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_asian_banking_pp_2_indonesia_va.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_asian_banking_pp_4_indonesia_va.svg "3—Selecting bank among all available banks")

![](images/universal/pm/splits/en_asian_banking_pp_5_indonesia_va.svg "4—Selecting bank among specific banks")

![](images/universal/pm/splits/en_asian_banking_pp_6_indonesia_va.svg "5—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Indonesian Virtual Accounts method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_dhh_vmq_cnb .section}

There are several things you need to consider when sending purchase requests by using the Indonesian Virtual Accounts method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit. If the currency [IDR](references/en/currencies/IDR.md) is specified in the purchase request it is necessary to round the payment amount to an integer. If another currency is specified in the request, the payment amount is converted to an equivalent amount in the [IDR](references/en/currencies/IDR.md) currency on the Ecommpay side and rounded up to an integer \(for example, if the converted amount is 200,000.05 [IDR](references/en/currencies/IDR.md), such an amount is rounded up to 200,001.00 [IDR](references/en/currencies/IDR.md)\)
    -   `customer_id`—customer identifier unique within the project
2.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option in the `payment_methods_options` object specify the `indonesia_va` object containing the `split_banks` parameter with the value `true`:

        ```language-json
        "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true}}"
        ```

    3.  *Selecting a bank among all available ones on Payment Page \(3\)*—for this option specify the method code `online-indonesian-banks` in the `force_payment_method` parameter.
    4.  *Selecting a bank among specific ones on Payment Page \(4\)*—for this option specify the following:
        -   the online-indonesian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `indonesia_va` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifiers:

            ```language-json
            "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831, 2931]}}"
            ```

    5.  *Confirming redirection to the service of the specific bank on Payment Page \(5\)*—for this option specify the following:
        -   the online-indonesian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `indonesia_va` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifier:

            ```language-json
            "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831]}}"
            ```

3.  It may be necessary to specify the first and last names of the customer in the `customer_first_name` and `customer_last_name` parameters. Refer to your Ecommpay key account manager for more information on the necessity of using these parameters.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Indonesian Virtual Accounts method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_first_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_first_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_first_name": "Doe",
   "force_payment_method": "online-indonesian-banks",
   "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831, 2931]}}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The standard format for callbacks is used to deliver purchase results from Indonesian Virtual Accounts. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `200,000.00 IDR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001045"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1164,
                "payment_id": "644206",
                "auth_code": "",
                "date": "2020-02-22T22:44:45+0000"
            }
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001046"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "IDR"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_indonesia_va_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Indonesian Virtual Accounts method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Indonesian Virtual Accounts service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_indonesiava_uml_gate.svg "Purchase by using Gate")

1.  A customer initiates a purchase by using the Indonesian Virtual Accounts method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service, where a 16 digit code and payment instructions are displayed to the customer.
11. In accordance with the payment instructions the customer enters the code on either the bank website, bank mobile application or the ATM, and confirms the purchase.
12. The purchase is processed in the provider service.
13. The provider service sends the payment result notification to the payment platform.
14. The payment platform sends the payment result callback to the web service.
15. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Indonesian Virtual Accounts method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_smw_4mr_cnb .section}

There are several things you need to consider when sending purchase requests by using the Indonesian Virtual Accounts method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/indonesia-va/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit. If the currency [IDR](references/en/currencies/IDR.md) is specified in the purchase request it is necessary to round the payment amount to an integer. If another currency is specified in the request, the payment amount is converted to an equivalent amount in the [IDR](references/en/currencies/IDR.md) currency on the Ecommpay side and rounded up to an integer \(for example, if the converted amount is 200,000.05 [IDR](references/en/currencies/IDR.md), such an amount is rounded up to 200,001.00 [IDR](references/en/currencies/IDR.md)\)
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
3.  It may also be required to specify the first name and the last name of the customer in the corresponding parameters:

    -   Object `customer`—customer information:
        -   `first_name`—customer first name
        -   `last_name`—customer last name
    -   Object `return_url`—contains the URLs to which customer is redirected during or after payment processing:
        -   `return`—URL to return customer to the web service during any step before the payment is completed
    Refer to your Ecommpay key account manager for more information on the necessity of using these parameters.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Indonesian Virtual Accounts method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, URL for redirection, as well bank identifier as signature.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
    },
    "customer": {
      "id": "12345",
      "ip_address": "192.0.2.0"
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 2961
    },
    "return_url": {
      "return": "https://example.com/return"
    }
 }
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
    },
    "customer": {
      "id": "12345",
      "ip_address": "192.0.2.0"
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 2961
    },
    "return_url": {
      "return": "https://example.com/return"
    }
 }
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Indonesian Virtual Accounts method requires redirection of customers from the merchant's web service to the Indonesian Virtual Accounts service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

In the Indonesian Virtual Accounts method, the callbacks that deliver purchase results use the standard format described in [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `200,000.00 IDR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001045"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1164,
                "payment_id": "644206",
                "auth_code": "",
                "date": "2020-02-22T22:44:45+0000"
            }
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8C5/JSKObUxTvkUuCZL4phAiFQA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001046"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "IDR"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_indonesia_va_dash_analysis}

To analyse information about payments made with the Indonesian Virtual Accounts method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Local payouts to bank accounts in the UK {#pm_bankpayout_uk}

An article about the payment method which allows you to process payments in pounds sterling by using bank accounts in the UK and supports payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_bankpayout_uk_overview}

An article about the payment method which allows you to process payments in pounds sterling by using bank accounts in the UK and supports payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Local payouts to bank accounts in the UK is a payment method which allows you to process payments in pounds sterling by using bank accounts in the UK.This method supports payouts. You can also perform purchases by using [Open Banking in the UK](pm_uk.md) as a complementary payment method.

This article provides information about working with the Local payouts to bank accounts in the UK method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[GB](references/en/countries/GB.md)|
|Payment currencies|[GBP](references/en/currencies/GBP.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Special considerations|performing purchases is possible with the use of the complementary payment method [Open Banking in the UK](pm_uk.md)|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Local payouts to bank accounts in the UK method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_bankpayout_uk_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Local payouts to bank accounts in the UK method. Payouts can be processed by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [GBP](references/en/currencies/GBP.md)¹|Times²|
|minimum|maximum|basic|threshold|
|--|------------------------------------------------|------|
|-------|-------|-----|---------|
|Payouts|\*|\*|\*|\*|

**Note:**

1.  Amount limits and processing times depend on banks.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To process a payout by using the Local payouts to bank accounts in the UK method, you need to notify the customer via the web service.

![](images/pm/eng_bankpayout_uk_interfaces_gate_payout.svg "Payout by using Gate")

## Payouts by using Gate {#en_pm_bankpayout_uk_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Local payouts to bank accounts in the UK method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/eng_bankpayout_uk_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Local payouts to bank accounts in the UK method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The payout is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Local payouts to bank accounts in the UK method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Local payouts to bank accounts in the UK method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/bank-transfer/uk/payout` endpoint. This endpoint belongs to the group [/v2/payment/bank-transfer/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/bank-transfer/post-v2-payment-bank-transfer-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
        -   `description`—payout description
    -   Object `customer`—recipient information:
        -   `id`—recipient identifierunique within the project
        -   `ip_address`—recipient IP addressrelevant for the initiated payout
        -   `first_name`—full name of the recipient or name of the company
    -   Object `account`—recipient account information:
        -   `bank_code`—SORT bank code of the recipient
        -   `number`—recipient bank account number in domestic format
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Local payouts to bank accounts in the UK method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), payout description, recipient information, account number, SORT code of the bank, as well as signature.

```language-json
 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9c8hA8xCjEwH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "customer": {
     "id": "customer1",
     "ip_address": "192.0.2.0",
     "first_name": "John Doe"
  },
   "account": {
     "bank_code": "123",
     "number": "1020304010"
  },
   "payment": {
     "amount": 10000,
     "currency": "GBP",
     "description": "test payout"
  }
}
```

```language-json
 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9c8hA8xCjEwH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "customer": {
     "id": "customer1",
     "ip_address": "192.0.2.0",
     "first_name": "John Doe"
  },
   "account": {
     "bank_code": "123",
     "number": "1020304010"
  },
   "payment": {
     "amount": 10000,
     "currency": "GBP",
     "description": "test payout"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Local payouts to bank accounts in the UK method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `305.00 GBP` payout made in the `4991` project.

```language-json
 {
        "project_id": 4991,
        "payment": {
            "id": "85777022",
            "type": "payout",
            "status": "success",
            "date": "2021-02-22T13:47:30+0000",
            "method": "bank-transfer-uk",
            "sum": {
                "amount": 30500,
                "currency": "GBP"
            },
            "description": "test payout"
        },
        "account": {
            "number": "5345765"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 4205000000072,
            "type": "payout",
            "status": "success",
            "date": "2021-02-22T13:47:30+0000",
            "created_date": "2021-02-22T13:47:09+0000",
            "request_id": "d61112fb05c3c558a5b77dde36fa41b649d-00004206",
            "sum_initial": {
                "amount": 30500,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 30500,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2944,
                "payment_id": "j29UpFMgQ0",
                "auth_code": ""
            }
        },
        "signature": "EaiGnnSGbZ20U0wmq1x1v/UiIDbzAAxECZegwQqZlYUA=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
 {
        "project_id": 4991,
        "payment": {
            "id": "31596106",
            "type": "payout",
            "status": "decline",
            "date": "2021-02-22T13:57:40+0000",
            "method": "bank-transfer-uk",
            "sum": {
                "amount": 23400,
                "currency": "GBP"
            },
            "description": "test payout"
        },
        "account": {
            "number": "312312543"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 7033000000070,
            "type": "payout",
            "status": "decline",
            "date": "2021-02-22T13:57:40+0000",
            "created_date": "2021-02-22T13:57:37+0000",
            "request_id": "c84225facb18f7218f76b053af8b717f946-00007034",
            "sum_initial": {
                "amount": 23400,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 23400,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2944,
                "payment_id": "j29ih8EBLQ",
                "auth_code": ""
            }
        },
        "signature": "9PcGBHYLfgObqD1cUHXN/iGInDB0KVS2RFVyht5k5wIei75g=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Local payouts to bank accounts in the UK method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_bankpayout_uk.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_bankpayout_uk_dash_analysis}

To analyse information about payments made with the Local payouts to bank accounts in the UK method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Malaysian Online Banking {#pm_malaysia}

An article about the payment method which allows to process payments in Malaysian ringgits by using bank accounts in Malaysia and supports purchases and payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_malaysia_overview}

An article about the payment method which allows to process payments in Malaysian ringgits by using bank accounts in Malaysia and supports purchases and payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Malaysian Online Banking is a payment method which allows to process payments in Malaysian ringgits by using bank accounts in Malaysia.This method supports purchases and payouts.

This article provides information about working with the Malaysian Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[MY](references/en/countries/MY.md)|
|Payment currencies|[MYR](references/en/currencies/MYR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Notes|-   Payment Page supports different [bank selection options](pm_malaysia.md#section_p5j_fgl_ggb)
-   Safari browser may not support the redirection to a bank service. For the more details, contact your Ecommpay key account manager

|
|Onboarding and access fee|refer to your Ecommpay key account manager; more information is available in the [Ecommpay shop](https://ecommpay.com/shop/payment-methods/online-banking-malaysia/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Malaysian Online Banking method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the bank service.

![](images/pm/en_banks_malaysia_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Malaysian Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), payouts—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [MYR](references/en/currencies/MYR.md)|Times²|
|minimum|maximum|base|threshold|
|--|-----------------------------------------------|------|
|-------|-------|----|---------|
|Purchases|50.00|50,000.00|\*|\*|
|Payouts|10.00|50,000.00|\*|\*|

**Note:**

1.  Keep in mind that payment processing times depend on banks, that support purchases by using this payment method.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Malaysian Online Banking method, you need to redirect customer to the Malaysian Online Banking service, while to initiate a payout, you need to notify the customer via the web service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_4.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_5.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_6.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_malaysia_7.svg "Redirecting to the web service")

General scenarios of processing purchases and payouts can be presented as follows.

![](images/pm/en_banks_overview_pp.svg "Purchase by using Payment Page")

![](images/pm/en_banks_overview_gate_purchase.svg "Purchase by using Gate")

![](images/pm/en_banks_overview_gate_payout.svg "Payout by using Gate")

At the same time, the specifics of working with the method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselected as well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_malaysia.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_malaysia.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of banks supported by the Malaysian Online Banking method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|Purchase|Payout|
|----|--|--------|------|
|Alliance Bank|110|–|+|
|Affin Bank|109|–|+|
|AM Bank|108|+|+|
|Bank Islam Malaysia|471|–|+|
|Bank Rakyat|112|–|+|
|Bank Simpanan Nasional|481|–|+|
|CIMB Bank|105|–|+|
|Citi bank|114|–|+|
|Hong Leong Bank|106|+|+|
|Hong Leong Bank Enterprise|115|–|+|
|HSBC Bank|116|–|+|
|Maybank|103|+|+|
|Maybank Enterprise|117|–|+|
|Oversea-Chinese Banking Corporation Limited \(OCBC\)|118|–|+|
|Public Bank|104|+|+|
|RHB Bank|107|+|+|
|Standard Chartered Bank|122|–|+|
|United Overseas Bank \(UOB\)|121|–|+|

Since the list of available banks may change over time, it is recommended to send a POST request to the one of the following endpoints: `/v2/info/banks/malaysia/sale/list` for purchases and `/v2/info/banks/malaysia/payout/list` for payouts to obtain up-to-date information. These endpoints belong to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "MYR"
  }
}
```

```language-json
[
  {
    "id": 110, // Bank ID
    "abbr": "ALB", // Bank abbreviation (for internal use)
    "name": "ALB", // International bank name
    "nativeName": "Alliance Bank", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 980, // Currency ID in the payment platform
        "alpha_3_4217": "MYR", // ISO-4217 alphabetic currency code
        "number_3_4217": "458", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 104, 
    "abbr": "PBB", 
    "name": "PBB", 
    "nativeName": "Public Bank Berhad", 
    "currencies": [
      {
        "id": 980,
        "alpha_3_4217": "MYR",
        "number_3_4217": "458",
        "exponent": 2
      }
    ]
  },
  {
    "id": 122, 
    "abbr": "SCTB", 
    "name": "SCTB", 
    "nativeName": "Standard Chartered Bank",
    "currencies": [
      {
        "id": 980,
        "alpha_3_4217": "MYR",
        "number_3_4217": "458",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Malaysian Online Banking method, refer to your Ecommpay account manager.

## Purchases by using Payment Page {#en_pm_malaysia_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Malaysian Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_banks_malaysia_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Malaysian Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Malaysian Online Banking method.
9.  The payment platform processes the request and sends it to the bank service.
10. The request is processed on the bank service side.
11. The data for redirecting the customer to the bank service is sent from the bank service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the bank service.
14. The customer completes all required payment steps.
15. The purchase is processed in the bank service.
16. The result information is displayed to the customer in the bank service.
17. The customer is redirected to Payment Page.
18. The bank service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Malaysian Online Banking method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_malaysia.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_asian_banking_pp_1_malaysia.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_asian_banking_pp_2_malaysia.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_asian_banking_pp_4_malaysia.svg "3—Selecting bank among all available banks")

![](images/universal/pm/splits/en_asian_banking_pp_5_malaysia.svg "4—Selecting bank among specific banks")

![](images/universal/pm/splits/en_asian_banking_pp_6_malaysia.svg "5—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Malaysian Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Malaysian Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option in the `payment_methods_options` object specify the `online_malaysian_banks` object containing the `split_banks` parameter with the value `true`:

        ```language-json
        "payment_methods_options": "{\"online_malaysian_banks\": {\"split_banks\": true}}"
        ```

    3.  *Selecting a bank among all available ones on Payment Page \(3\)*—for this option specify the method code `online-malaysian-banks` in the `force_payment_method` parameter.
    4.  *Selecting a bank among specific ones on Payment Page \(4\)*—for this option specify the following:
        -   the online-malaysian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_malaysian_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifiers:

            ```language-json
            "payment_methods_options": "{\"online_malaysian_banks\": {\"split_banks\": true, \"banks_id\": [110, 104]}}"
            ```

    5.  *Confirming redirection to the service of the specific bank on Payment Page \(5\)*—for this option specify the following:
        -   the online-malaysian-banks code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `online_malaysian_banks` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target bank identifier:

            ```language-json
            "payment_methods_options": "{\"online_malaysian_banks\": {\"split_banks\": true, \"banks_id\": [110]}}"
            ```

3.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
4.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Malaysian Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 20000000,
   "payment_currency": "MYR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 20000000,
   "payment_currency": "MYR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000000,
   "payment_currency": "THB",
   "customer_id": "customer1",
   "force_payment_method": "online-malaysian-banks",
   "payment_methods_options": "{\"online_malaysian_banks\": {\"split_banks\": true, \"banks_id\": [110, 104]}}",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The standard format for callbacks is used to deliver purchase results from Malaysian Online Banking. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `2 000,00 MYR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "54383173598055",
            "type": "purchase",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 200000,
                "currency": "MYR"
            },
            "description": "543831735980"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15788000002076,
            "type": "sale",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "created_date": "2022-09-03T10:40:20+0000",
            "request_id": "72cb91e7586004",
            "sum_initial": {
                "amount": 200000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 200000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1157,
                "payment_id": "",
                "date": "2022-09-03T10:44:27+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Cug4rIB6OimEkwmMBi1OfYpapSpZrzVw34WpHt5CzEA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "4356886034811111",
            "type": "purchase",
            "status": "decline",
            "date": "2022-09-30T14:11:13+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 1000,
                "currency": "MYR"
            },
            "description": "4356886034811111"
        },
        "operation": {
            "id": 9830000002095,
            "type": "sale",
            "status": "decline",
            "date": "2022-09-30T14:11:13+0000",
            "created_date": "2022-09-30T14:11:06+0000",
            "request_id": "3b14e5b0fd1",
            "sum_initial": {
                "amount": 1000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1157,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "cQbMiD0pON9eJcdFA4EKQiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_malaysia_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Malaysian Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the bank service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_banks_malaysia_uml_gate.svg)

1.  A customer initiates a purchase by using the Malaysian Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The request is processed on the bank service side.
8.  The bank service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the bank service.
11. The customer completes all required payment steps.
12. The purchase is processed in the bank service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The bank service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Malaysian Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Malaysian Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/malaysia/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  The following objects and parameters must be specified in the request:
    -   Object general—general purchase information:
        -   project\_id—the project ID obtained from Ecommpay
        -   payment\_id—payment ID unique within the project
        -   signature—signature created after you specify all the required parameters. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
    -   Object customer—customer information:
        -   id—the unique ID of the customer within your project
        -   ip\_address—customer IP address
    -   Object payment—purchase information:
        -   amount—purchase amount in minor currency units
        -   currency—purchase currency in ISO-4217 alpha-3 format.
    -   Object account—customer account information:
        -   bank\_id—bank identifier.
3.  If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request through the Malaysian Online Banking method must include project, payment, customer and bank IDs, customer IP-address, signature, currency and amount of the purchase, as shown in the following example:

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 10000,
      "currency": "MYR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176"
    },
    "account":{
      "bank_id": 130
    },
    
}
```

### Formats of the customer redirection data {#section_nxg_hmn_zgb .section}

To redirect a customer from the web service to the bank site, you must receive a callback from the payment platform containing the URL for redirection in the redirect\_data.url parameter and data to be sent in the request body in the redirect\_data.body parameter, and use these parameters when opening the bank’s HTML page using the method specified in the redirect\_data.method parameter.

The following is the callback fragment containing the redirection data.

```language-json
"redirect_data": {
            "body": {},
            "method": "POST",
            "url": "https://www.example.com/payment.php"
        },
```

### Callback format {#section_wsx_3jl_ggb .section}

The standard format for callbacks is used to deliver purchase results from Malaysian Online Banking. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `2 000,00 MYR` purchase made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "54383173598055",
            "type": "purchase",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 200000,
                "currency": "MYR"
            },
            "description": "543831735980"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15788000002076,
            "type": "sale",
            "status": "success",
            "date": "2022-09-03T10:50:29+0000",
            "created_date": "2022-09-03T10:40:20+0000",
            "request_id": "72cb91e7586004",
            "sum_initial": {
                "amount": 200000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 200000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1157,
                "payment_id": "",
                "date": "2022-09-03T10:44:27+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Cug4rIB6OimEkIwE/eugWYrFyBErmi0OVw34WpHt5CzEA=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "4356886034811111",
            "type": "purchase",
            "status": "decline",
            "date": "2022-09-30T14:11:13+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 1000,
                "currency": "MYR"
            },
            "description": "4356886034811111"
        },
        "operation": {
            "id": 9830000002095,
            "type": "sale",
            "status": "decline",
            "date": "2022-09-30T14:11:13+0000",
            "created_date": "2022-09-30T14:11:06+0000",
            "request_id": "3b14e5b0fd1",
            "sum_initial": {
                "amount": 1000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1157,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "cQbMiD0pON9eJcKQiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Gate {#en_pm_malaysia_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Malaysian Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/en_banks_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Malaysian Online Banking method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the bank service.
7.  The payout is processed on the side of the bank service.
8.  The bank service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Malaysian Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Malaysian Online Banking method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/banks/malaysia/payout` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payout
    -   Object `account`—customer account information:
        -   `number`—customer account number
        -   `customer_name`—name of bank account holder
        -   `bank_id`—bank identifier
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Malaysian Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer and account information, as well as signature.

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLHq3LweSAWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 10000,
      "currency": "MYR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "192.0.2.0"
    },
  "account":{
      "bank_id": 103,
      "customer_name": "Putra account",
      "number": "314159265358979"
    }
}
```

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLHq3LweSAWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 10000,
      "currency": "MYR"
      },
    "customer": {
      "id":"2990",
      "ip_address": "192.0.2.0"
    },
  "account":{
      "bank_id": 103,
      "customer_name": "Putra account",
      "number": "314159265358979"
    }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Malaysian Online Banking method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `2,000.00 MYR` payout made in the `200` project.

```language-json
 {
        "project_id": 200,
        "payment": {
            "id": "PAYOUT7891022555",
            "type": "payout",
            "status": "success",
            "date": "2022-09-12T13:28:58+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 200000,
                "currency": "MYR"
            },
            "description": "payout"
        },
        "account": {
            "number": "6419422222",
            "bank_id":105
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15112000002236,
            "type": "payout",
            "status": "success",
            "date": "2022-09-12T13:28:58+0000",
            "created_date": "2022-09-12T13:22:15+0000",
            "request_id": "b54610e94a76",
            "sum_initial": {
                "amount": 200000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 200000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1153,
                "payment_id": "E80NPPQ6Z1YSYPZTPH0NBON42",
                "date": "2022-09-12T13:28:34+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "qV2FRs/wxoOaywQS0GYQDiOrpMkoW80mynkaQfSAUJpfQ=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "PAYOUT789",
            "type": "payout",
            "status": "decline",
            "date": "2022-09-07T09:44:43+0000",
            "method": "Malaysian banks",
            "sum": {
                "amount": 6000000,
                "currency": "MYR"
            },
            "description": ""
        },
        "account": {
            "number": "6419422222",
            "bank_id":106
        },
        "customer": {
            "id": "1"
        },
        "errors": [
            {
                "code": "3104",
                "message": "Payment Constraint Invalid Payout Amount",
                "description": "Gate. Operation was declined. Maximum payout limit is exceeded"
            }
        ],
        "operation": {
            "id": 533000002202,
            "type": "payout",
            "status": "decline",
            "date": "2022-09-07T09:44:43+0000",
            "created_date": "2022-09-07T09:44:43+0000",
            "request_id": "205d3536a91f4737d6702dd42fa7d248258224fe3f6",
            "sum_initial": {
                "amount": 6000000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 6000000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1153,
                "payment_id": ""
            },
            "code": "3104",
            "message": "Payment Constraint Invalid Payout Amount"
        },
        "signature": "j4cxKDvx0EaDe4zKLbLclinxE915lAWGHKVjurpQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Malaysian Online Banking method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_malaysia.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Testing {#en_pm_malaysia_testing}

### General information {#section_zqw_xfw_xjb .section}

For the Malaysian Online Banking method, it is possible to test purchases by using Payment Page and Gate, as well as payouts by using Gate. To enable and disable testing, as well getting assistance with setting up a test project, refer to Ecommpay technical support.

When testing payments keep in mind that the test project identifier must be indicated in requests, the interfaces of the emulator of Payment Page and Malaysian Online Banking payment forms can differ from the production environment.

### Test payments statuses {#section_j1z_1s5_zjb .section}

The final status of test payments and operations is determined by the amount specified in the request.

Test purchases:

-   `40000` or `40400` amount to get the `decline` status
-   any other amount to get the `success` status

Test payouts:

-   `40000` or `40400` amount to get the `decline` status
-   any other amount to get the `success` status

### Purchases by using Payment Page {#section_wlk_dgw_xjb .section}

To perform a test purchase by using Payment Page, do the following:

1.  Send a correct test request for Payment Page opening to the payment platform.
2.  If the `online-malaysian-banks` method was not specified in the request—select the method on the emulator page.
3.  If multiple banks are available for selection, select a bank; if only one bank is available, click the **Pay** button.
4.  Click the **Success** or **Decline** button \(depending on the amount specified in the request\).
5.  Receive the final callback with information about the payment result.

More information about processing purchases by using the Malaysian Online Banking method via Payment Page is provided in the [Purchases by using Payment Page](pm_malaysia.md) section.

### Purchases by using Gate {#section_uvm_ngw_xjb .section}

To perform a test purchase by using Gate, do the following:

1.  Send a correct test request for purchase to the payment platform \(the bank\_id parameter must be used in the request, refer to Ecommpay technical support for the parameter value\).
2.  Accept a callback with redirection data.
3.  Go to the received URL and click the **Success** or **Decline** button \(depending on the amount specified in the request\).
4.  Receive the final callback with information about the payment result.

More information about processing purchases by using the Malaysian Online Banking method via Gate is provided in the [Purchases by using Gate](pm_malaysia.md) section.

### Payouts by using Gate {#section_wwc_xhw_xjb .section}

o process a test payout by using Gate, send a valid test request for a payout to the payment platform and receive a final callback with information about the payout result. More information about processing payouts by using the Malaysian Online Banking method via Gate is provided in the [Payouts by using Gate](pm_malaysia.md) section.

## Analysis of payments results {#en_pm_malaysia_dash_analysis}

To analyse information about payments made with the Malaysian Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Mexico Online Banking {#pm_mexico_ob}

An article about the payment method which allows you to process payments in Mexican pesos and US dollars by using bank accounts in Mexico and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_mexico_ob_overview}

An article about the payment method which allows you to process payments in Mexican pesos and US dollars by using bank accounts in Mexico and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Mexico Online Banking is a payment method which allows you to process payments in Mexican pesos and US dollars by using bank accounts in Mexico.This method supports purchasesand refunds.

This article provides information about working with the Mexico Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[MX](references/en/countries/MX.md)|
|Payment currencies|[MXN](references/en/currencies/MXN.md), [USD](references/en/currencies/USD.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|full or partial refunds can be issued within 90 calendar days after the purchase|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Mexico Online Banking method involves the merchant's web service, one of Ecommpay interfaces,and the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_mexico_ob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Mexico Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts¹|Times²|
|minimum|maximum|base|threshold|
|--|--------|------|
|-------|-------|----|---------|
|Purchases|\*|\*|3 minutes|36 hours|
|Refunds|\*|\*|5 minutes|36 hours|

**Note:**

1.  Minimum and maximum payment amounts depend on the banks that the customer can select after redirection to the provider service. The bank will not be available for selection if the payment amount is outside the limits set by the bank.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Mexico Online Banking method, you need to redirect the customer to the provider service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_mexico_ob_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_mexico_ob_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_mexico_ob_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_mexico_ob_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Mexico Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_mexico_ob_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Mexico Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Mexico Online Banking method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps on the provider service side.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Mexico Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Mexico Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is also required to specify the first and last name and the email of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_email`. To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`.
3.  If you need to have the payment form displayed with the Mexico Online Banking method selected, set the `force_payment_method` parameter to `online-mexico-banks`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Mexico Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature, as well as possible additional parameters.

``` {#codeblock_gdb_pts_w2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_hzt_vsw_x2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Mexico Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "mexico",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "mexico",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_mexico_ob_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Mexico Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_mexico_ob_uml_gate.svg)

1.  A customer initiates a purchase by using the Mexico Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps on the provider service side.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Mexico Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Mexico Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/mexico/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is required to specify the following objects and parameters:
    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—customer email address
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Mexico Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

``` {#codeblock_fp4_1tw_x2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Mexico Online Banking method requires redirection of customers from the merchant's web service to the provider service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Mexico Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "mexico",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-3c6a0ba271207cb817a0c683cf36e7a33ff2d9b4-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn15Q0dM2S+iD5RNQvCeMsG/PmpHnKhIw+5XaZ+Fsd6z/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "mexico",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_mexico_ob_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Mexico Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_mexico_ob_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The refund is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Mexico Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Mexico Online Banking method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Mexico Online Banking method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_gqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Mexico Online Banking method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` full refund made by the `1` customer in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_265608",
        "type": "purchase",
        "status": "refunded",
        "date": "2025-06-26T06:48:37+0000",
        "method": "mexico",
        "sum": {
            "amount": 0,
            "currency": "USD"
        },
        "description": "TEST_PAYMENT_265608"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 7373000014760,
        "type": "refund",
        "status": "success",
        "date": "2025-06-26T06:48:37+0000",
        "created_date": "2025-06-26T06:48:34+0000",
        "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1903,
            "payment_id": "1750920516487",
            "auth_code": ""
        }
    },
    "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ=="
}
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "test_29.04.25_3",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-29T11:36:34+0000",
        "method": "mexico",
        "sum": {
            "amount": 200000,
            "currency": "MXN"
        },
        "description": "test_29.04.25_3"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 5557000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-29T11:22:44+0000",
        "created_date": "2024-12-29T11:22:44+0000",
        "request_id": "c717b3de84d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 100000,
            "currency": "MXN"
        },
        "sum_converted": {
            "amount": 534,
            "currency": "USD"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21514,
            "payment_id": "1418092457",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Mexico Online Banking method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_mexico_ob.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_mexico_ob_dash_analysis}

To analyse information about payments made with the Mexico Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Multibanco {#pm_multibanco}

An article about the payment method which allows you to process payments in euros by using bank accounts in Portugal and supports purchases.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_multibanco_overview}

An article about the payment method which allows you to process payments in euros by using bank accounts in Portugal and supports purchases.

### Introduction {#section_t5z_rlg_ytb .section}

Multibanco is a payment method which allows you to process payments in euros by using bank accounts in Portugal.This method supports purchases.

This article provides information about working with the Multibanco method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PT](references/en/countries/PT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|–|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/multibanco/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Multibanco method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the Multibanco service.

![](images/pm/eng_multibanco_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Multibanco method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [EUR](references/en/currencies/EUR.md)|Times¹|
|minimum|maximum|basic|threshold|
|--|-----------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|–|99,999.99|–|7 days|

**Note:**

1.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Multibanco method, customers make purchases by using the displayed payment instructions.

![](images/pm/eng_multibanco_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_multibanco_interfaces_gate.svg "Purchase by using Gate")

## Purchases by using Payment Page {#en_pm_multibanco_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Multibanco method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_multibanco_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Multibanco method.
8.  The payment platform receives the request for processing the payment by using the Multibanco method.
9.  The payment platform processes the request and generates the payment instruction data.
10. The data is sent to Payment Page for displaying to the customer.
11. The payment form with the instructions to complete the payment is displayed to the customer.
12. The customer selects a bank, independently redirects to the bank website or redirects from Payment Page to the Multibanco service to complete all the payment steps required by using the instructions. A payment can be performed within 30 days.
13. The payment platform processes the request and sends it to the Multibanco service.
14. The purchase is processed in the Multibanco service.
15. The Multibanco service sends a notification about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The payment platform sends the result information to Payment Page.
18. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Multibanco method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Multibanco method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first, last names and email address of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_email`. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  The currency of payment can only be [EUR](references/en/currencies/EUR.md).
4.  If you need to have the payment form displayed with the Multibanco method selected, set the `force_payment_method` parameter to `multibanco`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Multibanco method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "customer@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "customer_email": "customer@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Multibanco method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_1560760354708",
            "type": "purchase",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "method": "multibanco",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 29891000002914,
            "type": "sale",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "created_date": "2019-06-17T08:50:34+0000",
            "request_id": "0d6aabd20c7925f1719b7cb63f728b32a3450cf0",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": "148907",
                "date": "2019-06-17T08:56:46+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "V0zYWk7OzwfcMJeQIHwj75hpkuXFNqHjYGMdfhycMw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_15593086938557",
            "type": "purchase",
            "status": "decline",
            "date": "2019-05-31T13:36:03+0000",
            "method": "multibanco",
            "sum": {
                "amount": 100,
                "currency": "RUB"
            },
            "description": "TEST_15593086938557"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 24680000002456,
            "type": "sale",
            "status": "decline",
            "date": "2019-05-31T13:36:03+0000",
            "created_date": "2019-05-31T13:20:11+0000",
            "request_id": "c4a6cb475cf610bac95feba1",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": ""
            },
            "code": "603",
            "message": "Auto decline"
        },
        "signature": "KDgghuSnXgvc9V9smeF+resLz/88b/uRrI04ggf2ALg=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_multibanco_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Multibanco method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Multibanco service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_multibanco_uml_gate.svg)

1.  A customer initiates a purchase by using the Multibanco method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Multibanco service.
7.  The request is processed on the Multibanco service side.
8.  The Multibanco service sends the data for displaying the payment instructions to the payment platform.
9.  The payment platform sends the callback with the data for displaying the payment instructions to the web service.
10. The customer receives the bank transfer instructions and independently redirects to the bank website.
11. The customer completes all the payment steps required by using the instructions. A payment can be performed within 30 days.
12. The purchase is processed in the Multibanco service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The Multibanco service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Multibanco method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Multibanco method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/bank-transfer/multibanco/sale` endpoint. This endpoint belongs to the group [/v2/payment/bank-transfer/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/bank-transfer/post-v2-payment-bank-transfer-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
        -   `email`—customer email address
    -   Object `return_url`—contains the URLs to which customer is redirected during or after payment processing:
        -   `return`—URL for redirecting a customer during a purchase
3.  The currency of purchase can only be [EUR](references/en/currencies/EUR.md).
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Multibanco method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, URL for redirection, as well as signature.

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": "payment_id",
        "signature": "PJkV8ej\/UGSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
      "ip_address": "192.0.2.0",
      "email": "Johnson@example.com",
      "first_name": "John",
      "last_name": "Johnson",
      "id": "customer123"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "return_url": {
      "return": "http://example.com"
    }
}
```

```language-json
{
    "general": {
        "project_id": 2990,
        "payment_id": "payment_id",
        "signature": "PJkV8ej\/UGSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
      "ip_address": "192.0.2.0",
      "email": "Johnson@example.com",
      "first_name": "John",
      "last_name": "Johnson",
      "id": "customer123"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
    },
    "return_url": {
      "return": "http://example.com"
    }
}
```

### Format of the customer redirection data {#section_nxg_hmn_zgb .section}

To complete the payment, customers must get the payment instructions from you. To display the payment data in the form of instructions, you need to receive a callback from the payment platform with the necessary data in the `provider_extra_fields` object:

-   `service_suppler_id`—bank identifier selected by a customer
-   `payment_reference`—reference number to complete payment

```language-json
{
"provider_extra_fields": {
            "service_suppler_id": "11854",
            "payment_reference": "646511672",
            "merchant_site_url": "https://example.com/"
        }
}
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Multibanco method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `238` project.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_1560760354708",
            "type": "purchase",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "method": "multibanco",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 29891000002914,
            "type": "sale",
            "status": "success",
            "date": "2019-06-17T08:56:47+0000",
            "created_date": "2019-06-17T08:50:34+0000",
            "request_id": "0d6aabd20c7925f1719b7cb63f728b32a3450cf0",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": "148907",
                "date": "2019-06-17T08:56:46+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "V0zYWk7OzwfcMJeQIHwj75hpkuXFNqHjYGMdfhycMw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
{
        "project_id": 238,
        "payment": {
            "id": "TEST_15593086938557",
            "type": "purchase",
            "status": "decline",
            "date": "2019-05-31T13:36:03+0000",
            "method": "multibanco",
            "sum": {
                "amount": 100,
                "currency": "RUB"
            },
            "description": "TEST_15593086938557"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 24680000002456,
            "type": "sale",
            "status": "decline",
            "date": "2019-05-31T13:36:03+0000",
            "created_date": "2019-05-31T13:20:11+0000",
            "request_id": "c4a6cb475cf610bac95feba1",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1208,
                "payment_id": ""
            },
            "code": "603",
            "message": "Auto decline"
        },
        "signature": "KDgghuSnXgvc9V9smeF+resLz/88b/uRrI04ggf2ALg=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_multibanco_dash_analysis}

To analyse information about payments made with the Multibanco method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# MyBank {#pm_mybank}

An article about the payment method which allows you to process payments in euros by using bank accounts in different European countries and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_mybank_overview}

An article about the payment method which allows you to process payments in euros by using bank accounts in different European countries and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

MyBank is a payment method which allows you to process payments in euros by using bank accounts in different European countries.This method supports purchases and refunds.

This article provides information about working with the MyBank method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[BE](references/en/countries/BE.md), [ES](references/en/countries/ES.md), [IT](references/en/countries/IT.md), [PT](references/en/countries/PT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|–|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the MyBank method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the MyBank service.

![](images/pm/en_mybank_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the MyBank method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amountsm EUR|Times¹|
|minimum|maximum|base|threshold|
|--|------------|------|
|-------|-------|----|---------|
|Purchases|0.01|999,999,999.99|3 minutes|30 minutes|
|Refunds|–|–|–|–|

**Note:**

1.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the MyBank method, you need to redirect the customer to the MyBank service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_mybank_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_mybank_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_pm_mybank_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_mybank_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the MyBank method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_mybank_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the MyBank method.
8.  The payment platform receives the request for processing the payment by using the MyBank method.
9.  The payment platform processes the request and sends it to the MyBank service.
10. The request is processed on the MyBank service side.
11. The data for redirecting the customer to the MyBank service is sent from the MyBank service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the MyBank service.
14. The customer completes all required payment steps.
15. The purchase is processed in the MyBank service.
16. The result information is displayed to the customer in the MyBank service.
17. The customer is redirected to Payment Page.
18. The MyBank service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the MyBank method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the MyBank method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first, last names, as well as the country code of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_country`. To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  If you need to have the payment form displayed with the MyBank method selected, set the `force_payment_method` parameter to `mybank`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the MyBank method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, and signature, as well as possible additional parameters.

``` {#codeblock_dfc_dpb_y2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_country": "IT",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_hq4_ctw_x2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_country": "IT",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The MyBank method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `133661` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "provider_extra_fields": {
            "description": "payment 1"
        },
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "PAYMENT_513414",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "PAYMENT_513414"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16571,
                "payment_id": "140346610492",
                "auth_code": ""
            },
            "id": 5031267010142511,
            "type": "sale",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "created_date": "2025-04-04T15:51:17+0000",
            "request_id": "0c4dd430b7016b9314a266ef1afdc95c4537-05031268"
        },
        "signature": "2dJ6jrj+jcWij/FyZi1+zyxrDybkKs5feZbifx9eTRPF8g=="
    }
}

```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "TEST_PAYMENT_593338",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_593338"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16571,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 5040750010141727,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "created_date": "2025-04-04T15:53:04+0000",
            "request_id": "db4a7fed5a83c6c45872675814a8968807988f-05040751"
        },
        "signature": "xmx6GdPS4hoEwPDtGWsHVjw8QA75qIUBzjA/O4SPvVbEIA=="
    }
}

```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_mybank_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the MyBank method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the MyBank service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_mybank_uml_gate.svg)

1.  A customer initiates a purchase by using the MyBank method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the MyBank service.
7.  The request is processed on the MyBank service side.
8.  The MyBank service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the MyBank service.
11. The customer completes all required payment steps.
12. The purchase is processed in the MyBank service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The MyBank service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the MyBank method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the MyBank method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/mybank/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is recommended to specify the following objects and parameters:

    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `country`—customer country code in accordance with ISO 3166-1 alpha-2
    If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission \(details are available in [Submission of additional payment information](en_Gate_Clarification.md)\).

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the MyBank method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, and signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Johnson",
    "country": "IT"
  }
}
```

``` {#codeblock_tc4_bqb_y2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Johnson",
    "country": "IT"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the MyBank method requires redirection of customers from the merchant's web service to the MyBank service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_rlf_tpb_y2c .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The MyBank method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `133661` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "provider_extra_fields": {
            "description": "payment 1"
        },
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "PAYMENT_513414",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "PAYMENT_513414"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16571,
                "payment_id": "140346610492",
                "auth_code": ""
            },
            "id": 5031267010142511,
            "type": "sale",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "created_date": "2025-04-04T15:51:17+0000",
            "request_id": "0c4dd430b7016b9314a266ef1afdc95c4537-05031268"
        },
        "signature": "2dJ6jrj+jcWij/FyZi1+zyxrDybkKs5feZbifx9eTRPF8g=="
    }
}

```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "TEST_PAYMENT_593338",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_593338"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16571,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 5040750010141727,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "created_date": "2025-04-04T15:53:04+0000",
            "request_id": "db4a7fed5a83c6c45872675814a8968807988f-05040751"
        },
        "signature": "xmx6GdPS4hoEwPDtGWsHVjw8QA75qIUBzjA/O4SPvVbEIA=="
    }
}

```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_mybank_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the MyBank method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_pm_mybank_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the MyBank service.
7.  The refund is processed on the side of the MyBank service.
8.  The MyBank service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the MyBank method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the MyBank method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the MyBank method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_bxk_glb_y2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The MyBank method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `5.00 EUR` partial refund made in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
        "project_id": 433772,
        "payment": {
            "id": "TEST_PAYMENT_122468",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2024-12-18T14:36:34+0000",
            "method": "MyBank",
            "sum": {
                "amount": 500,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_122468"
        },
        "customer": {
            "id": "1",
            "phone": "*************"
        },
        "operation": {
            "id": 3997000012221,
            "type": "refund",
            "status": "success",
            "date": "2024-12-18T14:36:34+0000",
            "created_date": "2024-12-18T14:36:30+0000",
            "request_id": "de99efb8e28702b165b5f9f117-00003998",
            "sum_initial": {
                "amount": 500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 500,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21414,
                "payment_id": "1418092071",
                "auth_code": ""
            }
        },
        "signature": "rq3TC04YQt1WFgSociHhJyfvjIQsj7n67UQ=="
    }
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
 {
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_122468",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-18T14:36:34+0000",
        "method": "MyBank",
        "sum": {
            "amount": 500,
            "currency": "EUR"
        },
        "description": "TEST_PAYMENT_122468"
    },
    "customer": {
        "id": "1",
        "phone": "*************"
    },
    "operation": {
        "id": 3997000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-22T14:22:44+0000",
        "created_date": "2024-12-22T14:22:44+0000",
        "request_id": "b3de84c717d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 5000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 5000,
            "currency": "EUR"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21414,
            "payment_id": "1418092071",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the MyBank method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_mybank.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_mybank_dash_analysis}

As with other payment methods Ecommpay offers, when using the MyBank method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard\(Old Dashboard\), for instance you can use the analytic panels on the **Analytics** tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

-   Dashboard\(Old Dashboard\) allows you to download reports in CSV and XLS formats—by using the tools on the [Payments](en_dbl_payments.md) tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
-   [Data API](en_dbl_api_protocol.md) allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get) queries.

If you have any further questions regarding payment data analysis, contact Ecommpay technical support.



---

# Open Banking {#pm_openbanking}

An article about the group of internet banking methods which are based on the use of open banking protocols and allow processing payments in euros and a number of other European currencies through various banks in Europe by using bank accounts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_openbanking_overview}

An article about the group of internet banking methods which are based on the use of open banking protocols and allow processing payments in euros and a number of other European currencies through various banks in Europe by using bank accounts.

### Introduction {#section_t5z_rlg_ytb .section}

Open Banking is a group of internet banking methods which are based on the use of open banking protocolsand provide advanced capabilities for secure processing of customer information. The methods of this group are characterized by a set of similar properties and allow processing payments in euros and a number of other European currencies through various banks in Europe by using bank accounts. At the same time, each of the methods is localized in a separate country, taking into account its specifics.

The Ecommpay payment platform supports processing purchases made with the Open Banking payment methods. You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) and [Local payouts to bank accounts in the UK](pm_bankpayout_uk.md) as complementary payment methods.Note that in this case payouts can be used to issue refunds to your customers.

This article provides general information about working with the Open Banking methods group, without the description of the parameters and features that apply to individual methods. This article may be useful in cases where it is necessary to enable Open Banking methods in a number of countries and it is reasonable to first configure the general parameters of the web service for the entire group of enabled methods, and then configure individual parameters for each of them.

Specific information about each Open Banking method, including information about available currencies and banks, as well as technical characteristics \(such as the method code for preselecting it in Payment Page and the endpoint address for sending requests by using Gate\), is presented in the articles describing these methods.

### General information {#section_tbf_2zk_ggb .section}

The general information about the Open Banking method group can be presented as follows.

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|basic availability: [AT](references/en/countries/AT.md), [BE](references/en/countries/BE.md), [DK](references/en/countries/DK.md), [EE](references/en/countries/EE.md), [ES](references/en/countries/ES.md), [FI](references/en/countries/FI.md), [FR](references/en/countries/FR.md), [DE](references/en/countries/DE.md), [HU](references/en/countries/HU.md),[IT](references/en/countries/IT.md), [IE](references/en/countries/IE.md), [LT](references/en/countries/LT.md), [LU](references/en/countries/LU.md), [LV](references/en/countries/LV.md), [NL](references/en/countries/NL.md), [NO](references/en/countries/NO.md), [PL](references/en/countries/PL.md), [PT](references/en/countries/PT.md), [RO](references/en/countries/RO.md), [SE](references/en/countries/SE.md)

 additionally, taking into account the development of the methods group, other regions may also be available

|
|Payment currencies|basic availability: [EUR](references/en/currencies/EUR.md) \(for [AT](references/en/countries/AT.md), [BE](references/en/countries/BE.md), [EE](references/en/countries/EE.md), [DK](references/en/countries/DK.md), [ES](references/en/countries/ES.md), [FI](references/en/countries/FI.md), [FR](references/en/countries/FR.md), [DE](references/en/countries/DE.md),[IT](references/en/countries/IT.md), [IE](references/en/countries/IE.md), [LT](references/en/countries/LT.md), [LU](references/en/countries/LU.md), [LV](references/en/countries/LV.md), [NL](references/en/countries/NL.md), [PL](references/en/countries/PL.md), [PT](references/en/countries/PT.md), [RO](references/en/countries/RO.md)\), [HUF](references/en/currencies/HUF.md) \(for [HU](references/en/countries/HU.md)\), [NOK](references/en/currencies/NOK.md) \(for [NO](references/en/countries/NO.md)\), [PLN](references/en/currencies/PLN.md) \(for [PL](references/en/countries/PL.md)\), [RON](references/en/currencies/RON.md) \(for [RO](references/en/countries/RO.md)\), [SEK](references/en/currencies/SEK.md) \(for [SE](references/en/countries/SE.md)\)

 additionally, taking into account the development of the methods group, other currencies may also be available

|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   refer to your Ecommpay account manager for information about countries and currencies supported by Open Banking methods \(in the light of active development of this group and the capabilities of providers\)
-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_openbanking.md#section_p5j_fgl_ggb)\)
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_openbanking.md#section_webview)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_openbanking.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment methods [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) and [Local payouts to bank accounts in the UK](pm_bankpayout_uk.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking methods involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the bank and provider services.

![](images/pm/en_openbanking_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking methods: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank and provider used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking methods, you need to redirect the customer to the provider \(if necessary\) and bank services.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this \(using the [Open Banking in the UK](pm_uk.md) method as an example\).

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_8.svg "Redirecting to the web service")

General scenarios of processing purchases can be presented as follows.

![](images/pm/en_openbanking_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_openbanking_interfaces_gate.svg "Purchase by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking methods include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_openbanking.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_openbanking.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

When making payments using any of the Open Banking group methods, various banks that support this method may be involved. To obtain up-to-date information about the banks available for a specific method, it is recommended to send POST requests to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) Gate API endpoint group. For Open Banking methods, the name of the catalog `{payment_method}` is the name of the country \(in accordance with how it is specified in the description of the method\), and the name of the catalog `{operationType}` is the type of operation \(`sale`\). So, for the [Open Banking in the UK](pm_uk.md) method the request to the `/v2/info/banks/uk/sale/list` endpoint is applicable.

The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
    "general": {
        "project_id": 200,
        "payment_id": "ORDER_155860015",
        "signature": "K6jllym+PtObocZtr345st...=="
    },
    "payment": {
        "amount": 1000,
        "currency": "EUR"
    }
}
```

```language-json
[
  {
    "id": 54991, // Bank ID
    "abbr": "COMMERZBANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "Commerzbank", // International bank name
    "nativeName": "Commerzbank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 54981,
    "abbr": "UNICREDIT-BANK",
    "name": "UniCredit Bank",
    "nativeName": "UniCredit Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 54971,
    "abbr": "DEUTSCHE-BANK",
    "name": "Deutsche Bank",
    "nativeName": "Deutsche Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking methods implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking payment methods, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_openbanking_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking methods, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information. To obtain such consent and information \(when required\), a corresponding [page](pm_openbanking.md#section_rnx_4cl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_openbanking_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the required service \(provider or bank\) where payment instructions are displayed.
12. The customer completes all required payment steps on the side of the used service.
13. The purchase is processed on the side of the used service.
14. The result information is displayed to the customer on the side of the used service.
15. The customer is redirected to Payment Page.
16. The used service sends information about the result to the payment platform.
17. The payment platform sends the payment result callback to the web service.
18. The payment platform sends the result information to Payment Page.
19. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking methods via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_webview .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Method and bank selection scenarios {#section_vpq_fj5_k3c .section}

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking methods, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_openbanking.md#section_p5j_fgl_ggb)\). The following options are available:

![](images/universal/pm/splits/en_open_banking_pp_1.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

-   1—when the payment form is opened, the tabs for selecting all available methods are displayed. Then the customer selects the method and one of the available banks \(this option is used by default\).
-   2—when the payment form is opened, the tabs for selecting methods of the target group are displayed. Then the customer selects the method and one of the available banks.
-   3—when the payment form is opened, the bank selection items for the target method are displayed. Then the customer selects one of the available banks.
-   4—when the payment form is opened, the tabs for selecting all available methods and the specified bank selection items for the target method are displayed. Then the customer selects one of the specified banks \(the choice is limited only to these banks\).
-   5—when the payment form is opened, the specified bank selection items for the target method are displayed. Then the customer selects one of the specified banks \(the choice is limited only to these banks\).
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking methods:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additional parameters may be required for payment processing, the list of which depends on the method, country, provider and bank. If such parameters are not included in the request, the payment form may display fields for the customer to specify them\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The bank selection options can be defined as follows \(with example values ​​for the [Open Banking in the UK](pm_uk.md) method\):

    1.  *Selecting the method among all available methods and then selecting one of the available banks \(1\)*—the default option, applied if the `force_payment_method`, `force_payment_group` and `payment_methods_options` parameters, mentioned in subpoints *2–6* are not used.

        As a result of using this option the tabs for selecting all available methods are displayed, and, after the method is selected, the available bank selection items are displayed.

    2.  *Selecting the method among other methods of the target group and then selecting one of the available banks \(2\)*—this option requires to specify the `openbanking` group code in the `force_payment_group` parameter

        ``` {#codeblock_zgy_zj5_k3c .language-json}
        "force_payment_group": "openbanking"
        ```

        As a result of using this option the tabs for selecting the methods of the target group are displayed, and, after the method is selected, the available bank selection items are displayed.

    3.  *Selecting one of the banks available for the target method \(3\)*—for this option specify the method code of the target method \(`uk`\) in the `force_payment_method` parameter.

        ``` {#codeblock_uqr_jk5_k3c .language-json}
        "force_payment_method": "uk"
        ```

        As a result of using this option the available bank selection items supported by this method are displayed.

    4.  *Selecting a method among all available methods and selecting one of the specified banks \(4\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifiers.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).

        ``` {#codeblock_t1g_dgc_h3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}"
        ```

        As a result of using this option the tabs for selecting all available are displayed, and, after the method is selected, the specified bank selection items are displayed \(taking into account which of these banks are available at the time of opening the payment form\) .

    5.  *Selecting one of the banks specified for the target method \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifiers.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).
        -   Specify the selected Open Banking method code \(`uk`\) in the `force_payment_method` parameter.
        ``` {#codeblock_jpm_5k5_k3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}",
        "force_payment_method": "uk"
        ```

        As a result of using this option the specified bank selection items supported by this method are displayed \(taking into account which of these banks are available at the time of opening the payment form\).

    6.  *Confirming redirection to the service of the specified bank \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifier.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).
        -   Specify the selected Open Banking method code \(`uk`\) in the `force_payment_method` parameter.
        ``` {#codeblock_jbz_4l5_k3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541]}}",
        "force_payment_method": "uk"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature, as well as various optional parameters.

```language-json
{ 
 // required parameters  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
 // optional parameters
    ...
 // signature
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{ 
 // required parameters  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
 // optional parameters
    ...
 // signature
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a method among all available methods and selecting one of the specified banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
 // required parameters  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
 // optional parameters
   ...
   "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}"
 // signature
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 GBP` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "UK Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "UK Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_openbanking_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking methods, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  If you receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer:
    1.  Check the integrity of the received data\(by checking the signature\), identify the composition of the requested information\(by parsing the parameters included in the callback\) and confirm receiving the callback\(by sending a synchronous response 200 OK\).
    2.  Obtain consent and additional information from the customer \(if requested\).
    3.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
3.  Receive an intermediate callback from the payment platform and redirect the customer to the required service\(provider or bank\).
4.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using one of the Open Banking methods and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the required service \(provider or bank\) where payment instructions are displayed.
9.  The customer completes all required payment steps on the side of the used service.
10. The purchase is processed on the side of the used service.
11. The result information is displayed to the customer on the side of the used service.
12. The customer is redirected to the web service.
13. The used service sends information about the result to the payment platform.
14. The payment platform sends the payment result callback to the web service.
15. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking methods via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking methods:

1.  To initiate each purchase, send a separate POST request to the [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale) endpoint, where the `{payment_method}` directory name is the name of the country \(as specified in the method description; for example, `uk` is used for the United Kingdom\).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additional parameters may be required for payment processing, the list of which depends on the method, country, provider and bank. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.To improve the customer experience, it is recommended to pass such parameters in initial requests.

    In addition, in some cases, taking into account the specifics of the provider or bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking methods must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
 // required parameters 
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7IipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "GBP"
      },
    "customer": {
      "id": "customer123",  
      "ip_address": "192.0.2.0"
    },
    "account": {
      "bank_id": 54981
    },
    "return_url":{
      "return": "http://example.com/return"
 // optional parameters
    ...
 }
}
```

```language-json
{
 // required parameters 
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7IipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "GBP"
      },
    "customer": {
      "id": "customer123",  
      "ip_address": "192.0.2.0"
    },
    "account": {
      "bank_id": 54981
    },
    "return_url":{
      "return": "http://example.com/return"
 // optional parameters
    ...
 }
}
```

### Formats for intermediate callbacks and requests for obtaining consent and additional information {#section_icz_bjm_ppb .section}

In cases where it is necessary to obtain additional consent from the customer and, if relevant, additional information, an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter. Information about parameters for which additional customer information must be provided is specified in accordance with the structures that are relevant for specific Open Banking group methods.

The following is a fragment of a callback informing about the necessity of obtaining customer's consent.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the customer's consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The text to be displayed on the payment form",
          "default": "The consent text to be displayed to the customer"
        }
      }
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
    "general": {
        "project_id": 10571,
        "payment_id": "1234567890",
        "signature": "PJkV8ej\/UG0Di8jQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "The consent text displayed to the customer"
        }
    }
 ...
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with Open Banking methods requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Open Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 GBP` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "UK Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "UK Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_openbanking_dash_analysis}

To analyse information about payments made with the Open Banking group methods, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Austria {#pm_austria}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Austria.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_austria_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Austria.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Austria an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Austria.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Austria payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Austria method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[AT](references/en/countries/AT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_austria.md#section_p5j_fgl_ggb)\)
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_austria.md#section_bfg_sc1_qjc)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_austria.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-austria/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Austria method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_austria_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Austria method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Austria method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Austria method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_austria.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_austria.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Austria method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|BAWAG PSK|21961|
|Erste BankAustria|21981|
|HYPO NOE|21941|
|Osterr. Arzte- und Apothekerbank|21921|
|Raiffeisen|21971|
|Schoellerbank|21951|
|Spardabank|21931|
|UniCredit Bank Austria - 24 You|21991|
|Volksbank Karnten|21901|
|Volksbank Niederosterreich|21851|
|Volksbank Oberosterreich|21861|
|Volksbank Salzburg|21881|
|Volksbank Steiermark|21871|
|Volksbank Tirol|21891|
|Volksbank Vorarlberg|21911|
|Volksbank Wien|21841|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/austria/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 21961, // Bank ID
    "abbr": "BAWAG PSK", // The service name of the bank in the platform (or its abbreviation)
    "name": "BAWAG PSK", // International bank name
    "nativeName": "BAWAG PSK", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 21971,
    "abbr": "RAIFFEISEN",
    "name": "Raiffeisen",
    "nativeName": "Raiffeisen",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 21931,
    "abbr": "SPARDABANK",
    "name": "Spardabank",
    "nativeName": "Spardabank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Austria methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Austria method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Austria payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_austria_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Austria method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Austria method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Austria method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_austria.md#section_tq2_sfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_austria.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Austria method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_tq2_sfd_wbc .section}

There are several things you need to consider when using the Open Banking in Austria method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_austrian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_austrian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_austrian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_austrian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Austria method code \(`online-austrian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-austrian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_austrian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Austria method code \(`online-austrian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_austrian_banks\": {\"split_banks\": true, \"banks_id\": [21971, 21961]}}",
        "force_payment_method": "online-austrian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_austrian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Austria method code \(`online-austrian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_austrian_banks\": {\"split_banks\": true, \"banks_id\": [21961]}}",
        "force_payment_method": "online-austrian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Austria method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-austrian-banks",
   "payment_methods_options": {"online_austrian_banks": {"split_banks": true, "banks_id": [21961, 21971]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Austria method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Austrian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Austrian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_austria_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Austria method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Austria method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Austria method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Austria method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/austria/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Austria method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Austria payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Austria method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Austria method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Austrian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Austrian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_austria_dash_analysis}

To analyse information about payments made with the Open Banking in Austria method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Belgium {#pm_belgium}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Belgium.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_belgium_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Belgium.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Belgium an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Belgium.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Belgium payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Belgium method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[BE](references/en/countries/BE.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_belgium.md#section_p5j_fgl_ggb)\)
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_belgium.md#section_bfg_sc1_qjc)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_belgium.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-belgium/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Belgium method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_belgium_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Belgium method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Belgium method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Belgium method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_belgium.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_belgium.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Belgium method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|AION Bank|22071|
|Argenta Bank|22081|
|AXA Bank Europe|22001|
|Belfius Bank|22021|
|BNP Paribas Fortis|22041|
|Crelan Bank|22061|
|Hello|22051|
|ING Belgium|22011|
|KBC|22031|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/belgium/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 22081, // Bank ID
    "abbr": "ARGENTA-BANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "Argenta Bank", // International bank name
    "nativeName": "Argenta Bank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 22001,
    "abbr": "AXA-BANK-EUROPE",
    "name": "AXA Bank Europe",
    "nativeName": "AXA Bank Europe",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22061,
    "abbr": "CRELAN-BANK",
    "name": "Crelan Bank",
    "nativeName": "Crelan Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Belgium methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Belgium method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Belgium payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_belgium_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Belgium method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Belgium method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Belgium method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_belgium.md#section_glz_jfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_belgium.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Belgium method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_glz_jfd_wbc .section}

There are several things you need to consider when using the Open Banking in Belgium method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_belgian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_belgian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_belgian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_belgian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Belgium method code \(`online-belgian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-belgian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_belgian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Belgium method code \(`online-belgian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_belgian_banks\": {\"split_banks\": true, \"banks_id\": [22061, 22051]}}",
        "force_payment_method": "online-belgian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_belgian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Belgium method code \(`online-belgian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_belgian_banks\": {\"split_banks\": true, \"banks_id\": [22061]}}",
        "force_payment_method": "online-belgian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Belgium method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-belgian-banks",
   "payment_methods_options": {"online_belgian_banks": {"split_banks": true, "banks_id": [22051, 22061]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Belgium method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Belgian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Belgian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_belgium_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Belgium method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Belgium method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Belgium method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Belgium method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/belgium/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Belgium method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Belgium payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Belgium method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Belgium method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Belgian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Belgian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_belgium_dash_analysis}

To analyse information about payments made with the Open Banking in Belgium method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Denmark {#pm_denmark}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Denmark.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_denmark_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Denmark.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Denmark an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Denmark.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Denmark payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Denmark method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[DK](references/en/countries/DK.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_denmark.md#section_p5j_fgl_ggb)\)
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_denmark.md#section_bfg_sc1_qjc)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_denmark.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-denmark/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Denmark method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_belgium_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Denmark method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Denmark method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Denmark method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_denmark.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_denmark.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Denmark method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|N26|4921|
|Nordea Bank|4931|
|Nykredit|4941|
|Sydbank|4951|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/denmark/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

``` {#codeblock_qmz_31v_53c .language-json}
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

``` {#codeblock_rmz_31v_53c .language-json}
[
  {
    "id": 4921, // Bank ID
    "abbr": "N26", // The service name of the bank in the platform (or its abbreviation)
    "name": "N26", // International bank name
    "nativeName": "N26", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 4931,
    "abbr": "NORDEA-DENMARK",
    "name": "Nordea Bank",
    "nativeName": "ANordea Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 4941,
    "abbr": "NYKREDIT",
    "name": "Nykredit",
    "nativeName": "Nykredit",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Denmark methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Denmark method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Denmark payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_denmark_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Denmark method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Denmark method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Denmark method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_denmark.md#section_glz_jfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Denmark method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_glz_jfd_wbc .section}

There are several things you need to consider when using the Open Banking in Denmark method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_danish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ``` {#codeblock_q4r_lbv_53c .language-json}
        "payment_methods_options": "{\"online_danish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_danish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ``` {#codeblock_s4r_lbv_53c .language-json}
        "payment_methods_options": "{\"online_danish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Denmark method code \(`online-danish-banks`\) in the `force_payment_method` parameter.

        ``` {#codeblock_u4r_lbv_53c .language-json}
        "force_payment_method": "online-danish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_danish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Denmark method code \(`online-danish-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_w4r_lbv_53c .language-json}
        "payment_methods_options": "{\"online_danish_banks\": {\"split_banks\": true, \"banks_id\": [22061, 22051]}}",
        "force_payment_method": "online-danish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_danish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Denmark method code \(`online-danish-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_y4r_lbv_53c .language-json}
        "payment_methods_options": "{\"online_danish_banks\": {\"split_banks\": true, \"banks_id\": [4931]}}",
        "force_payment_method": "online-danish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Denmark method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

``` {#codeblock_apr_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_bpr_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

``` {#codeblock_cpr_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "banks-denmark",
   "payment_methods_options": {"online_danish_banks": {"split_banks": true, "banks_id": [4931, 4941]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Denmark method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

``` {#codeblock_dpr_lbv_53c .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Danish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_epr_lbv_53c .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Danish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_denmark_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Denmark method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Denmark method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Denmark method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Denmark method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/denmark/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Denmark method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

``` {#codeblock_tgm_xbv_53c .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

``` {#codeblock_ugm_xbv_53c .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Denmark payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

``` {#codeblock_vgm_xbv_53c .language-json}
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

``` {#codeblock_xgm_xbv_53c .language-json}
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Denmark method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_zgm_xbv_53c .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Denmark method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

``` {#codeblock_ahm_xbv_53c .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Danish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_bhm_xbv_53c .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Danish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_denmark_dash_analysis}

To analyse information about payments made with the Open Banking in Denmark method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Estonia {#pm_estonia}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Estonia.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_estonia_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Estonia.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Estonia an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Estonia.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Estonia payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Estonia method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[EE](references/en/countries/EE.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_estonia.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_estonia.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_estonia.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-estonia/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Estonia method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_estonianob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Estonia method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Estonia method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_estonia_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Estonia method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_estonia.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_estonia.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Estonia method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|LHV bank|2111|
|Swedbank|2101|
|SEB bank|2091|
|COOP|22091|
|Citadele|5721|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/estonia/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 2091, // Bank ID
    "abbr": "SEB", // The service name of the bank in the platform (or its abbreviation)
    "name": "SEB bank", // International bank name
    "nativeName": "AS SEB Pank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 5721,
    "abbr": "CITADELE",
    "name": "Citadele",
    "nativeName": "Citadele",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22091,
    "abbr": "COOP",
    "name": "COOP",
    "nativeName": "COOP",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Estonia methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Estonia method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Estonia payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_estonia_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Estonia method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_estonia.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_pp.svg "Purchase processing by using Payment Page with redirecting the customer to provider service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Estonia methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The request for processing the payment is sent from the provider service to the bank service.
14. The purchase is processed on the side of the bank service.
15. The bank service sends the notification about the result to the provider service.
16. The result information is displayed to the customer on the side of the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends information about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

![](images/pm/eng_open_banking_bank_uml_pp.svg "Purchase sequence by using Payment Page with redirecting the customer to bank service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Estonia methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends the notification about the result to the provider service.
17. The provider service sends the notification about the result to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Estonia method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_estonia.md#section_igs_zfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_greece.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Estonia method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_igs_zfd_wbc .section}

There are several things you need to consider when using the Open Banking in Estonia method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_estonian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_estonian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_estonian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_estonian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Estonia method code \(`online-estonian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-estonian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_estonian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Estonia method code \(`online-estonian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_estonian_banks\": {\"split_banks\": true, \"banks_id\": [2101, 2111]}}",
        "force_payment_method": "online-estonian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_estonian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Estonia method code \(`online-estonian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_estonian_banks\": {\"split_banks\": true, \"banks_id\": [2111]}}",
        "force_payment_method": "online-estonian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Estonia method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-estonian-banks",
   "payment_methods_options": {"online_estonian_banks": {"split_banks": true, "banks_id": [2101, 2111]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Estonia method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_estonia_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Estonia method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to the provider service")

1.  A customer initiates a purchase by using the Open Banking in Estonia method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The request for processing the payment is sent from provider service to the bank service.
11. The purchase is processed on the side of the bank service.
12. The bank service sends the notification about the result to the provider service.
13. The result information is displayed to the customer on the side of the provider service.
14. The customer is redirected to the web service.
15. The provider service sends information about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

![](images/pm/eng_open_banking_bank_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to the bank service")

1.  A customer initiates a purchase by using the Open Banking in Estonia method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service, and then to the bank service, where payment instruction is displayed to the customer.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Estonia method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Estonia method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/estonia/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Estonia method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Estonia payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Estonia method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Estonia method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Estonian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_estonia_dash_analysis}

To analyse information about payments made with the Open Banking in Estonia method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Finland {#pm_finland}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Finland.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_finland_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Finland.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Finland an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Finland.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Finland payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Finland method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[FI](references/en/countries/FI.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file \(COF\) purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_finland.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_finland.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_finland.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-finland/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Finland method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_finland_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Finland method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Finland method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Finland method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_finland.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_finland.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Finland method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Aktia Bank|4971|
|Alandsbanken|55361|
|Danske Bank|55321|
|Handelsbanken|4981|
|Nordea Bank|4991|
|OmaSp|55331|
|OP Bank|5001|
|POP Pankki|55341|
|Saastopankki|55351|
|S-Pankki|55371|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/finland/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 4981, // Bank ID
    "abbr": "HANDELSBANKEN", // Bank abbreviation (for internal use)
    "name": "Handelsbanken", // Official bank name
    "nativeName": "Handelsbanken", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // Alphabetic code of the payment currency in ISO-4217 alpha-3 format
        "number_3_4217": "978", // Numeric code of the payment currency in ISO-4217 alpha-3 format
        "exponent": 2 // The number of minor units of the currency
      }
    ]
  },
  {
    "id": 4991,
    "abbr": "NORDEA-FINLAND",
    "name": "Nordea Bank",
    "nativeName": "Nordea Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55371,
    "abbr": "S-PANKKI",
    "name": "S-Pankki",
    "nativeName": "S-Pankki",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Open Banking in Finland methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Finland method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Finland payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_finland_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Finland method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_finland_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Finland method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
12. The customer completes all required payment steps on the side of the used service.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends information about the result to the provider service.
17. The provider service sends the payment result information to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Finland method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_finland.md#section_dpx_2hl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_finland.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Finland method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when using the Open Banking in Finland method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_finnish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_finnish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Finland method code \(`online-finnish-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-finnish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_finnish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Finland method code \(`online-finnish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true, \"banks_id\": [4981, 4991]}}",
        "force_payment_method": "online-finnish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_finnish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Finland method code \(`online-finnish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_finnish_banks\": {\"split_banks\": true, \"banks_id\": [4981]}}",
        "force_payment_method": "online-finnish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Finland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "force_payment_method": "online-finnish-banks",
   "payment_methods_options": {"online_finnish_banks": {"split_banks": true, "banks_id": [4991, 4981]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Finland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_finland_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Finland method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

Information about the data formats used to perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_finland_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Finland method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Finland method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_onh_2xj_wbc .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Finland method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/finland/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `success`—URL for redirecting a customer after a processed purchase
        -   `decline`—URL for redirecting a customer after a declined purchase
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Finland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URLs for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Finland method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Finland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Finnish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_finland_dash_analysis}

To analyse information about payments made with the Open Banking in Finland method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in France {#pm_france}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of France.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_france_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of France.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in France an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of France.

The Ecommpay payment platform supports processing purchases made with the Open Banking in France payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in France method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[FR](references/en/countries/FR.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_france.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_france.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_france.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-france/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in France method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_france_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in France method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in France method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in France method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_france.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_france.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in France method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|BNP Paribas \(MaBanque\)|22121|
|CIC Bank|22111|
|Credit Mutuel|22101|
|Hello Bank|22131|
|ING France|22141|
|La Banque Postale|22151|
|Societe Generale|22161|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/france/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 22111, // Bank ID
    "abbr": "CIC-BANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "CIC Bank", // International bank name
    "nativeName": "CIC Bank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 22141,
    "abbr": "ING-FRANCE",
    "name": "ING France",
    "nativeName": "ING France",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22161,
    "abbr": "SOCIETE-GENERALE",
    "name": "Societe Generale",
    "nativeName": "Société Générale",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in France methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in France method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in France payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_france_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in France method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in France method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in France method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_france.md#section_bbp_5fd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_france.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in France method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_bbp_5fd_wbc .section}

There are several things you need to consider when using the Open Banking in France method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_french_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_french_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_french_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_french_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in France method code \(`online-french-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-french-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_french_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in France method code \(`online-french-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_french_banks\": {\"split_banks\": true, \"banks_id\": [22161, 22151]}}",
        "force_payment_method": "online-french-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_french_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in France method code \(`online-french-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_french_banks\": {\"split_banks\": true, \"banks_id\": [22161]}}",
        "force_payment_method": "online-french-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in France method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-french-banks",
   "payment_methods_options": {"online_french_banks": {"split_banks": true, "banks_id": [22151, 22161]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in France method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "French Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "French Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_france_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in France method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in France method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in France method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in France method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/france/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in France method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in France payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in France method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in France method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "French Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "French Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_france_dash_analysis}

To analyse information about payments made with the Open Banking in France method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Germany {#pm_germany}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Germany.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_germany_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Germany.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Germany an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Germany.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Germany payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Germany method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[DE](references/en/countries/DE.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_germany.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_germany.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_germany.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-germany/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Germany method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_germany_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Germany method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Germany method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_germany_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Germany method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_germany.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_germany.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Germany method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Deutsche Bank, DB PFB AG|22731|
|Deutsche Bank, DB PFB AG - Postbank|22741|
|DKB \(Das kann Bank\)|22761|
|HypoVereinsbank eBanking Global|22701|
|HypoVereinsbank eBanking Global - UK branch|22711|
|HypoVereinsbank Online Banking|22691|
|ING-DiBa|22721|
|Norisbank GmbH|22751|
|UBS Germany|22771|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/germany/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 54991, // Bank ID
    "abbr": "COMMERZBANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "Commerzbank", // International bank name
    "nativeName": "Commerzbank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 54981,
    "abbr": "UNICREDIT-BANK",
    "name": "UniCredit Bank",
    "nativeName": "UniCredit Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 54971,
    "abbr": "DEUTSCHE-BANK",
    "name": "Deutsche Bank",
    "nativeName": "Deutsche Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Germany methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Germany method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Germany payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_germany_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Germany method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_germany.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Germany method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Germany method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_germany.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_germany.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Germany method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when using the Open Banking in Germany method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_german_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_german_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Germany method code \(`online-german-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-german-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_german_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Germany method code \(`online-german-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true, \"banks_id\": [54971, 54981]}}",
        "force_payment_method": "online-german-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_german_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Germany method code \(`online-german-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_german_banks\": {\"split_banks\": true, \"banks_id\": [54971]}}",
        "force_payment_method": "online-german-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Germany method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-german-banks",
   "payment_methods_options": {"online_german_banks": {"split_banks": true, "banks_id": [54971, 54981]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Germany method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "German Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "German Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_germany_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Germany method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Germany method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Germany method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Germany method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/germany/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Germany method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Germany payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Germany method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Germany method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_487",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "German Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "order_488",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "German Banks", // Indication of the method used
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Book order"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_germany_dash_analysis}

To analyse information about payments made with the Open Banking in Germany method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Hungary {#pm_hungary}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in forints via the banks of Hungary.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_hungary_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in forints via the banks of Hungary.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Hungary an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in forintss via the banks of Hungary.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Hungary payment method.

This article provides information about working with the Open Banking in Hungary method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[HU](references/en/countries/HU.md)|
|Payment currencies|[HUF](references/en/currencies/HUF.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_hungary.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_hungary.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_hungary.md#section_yln_qjn_ftb)\)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-hungary/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Hungary method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_hungary_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Hungary method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Hungary method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Hungary method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_hungary.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_hungary.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Hungary method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|K&H Bank|22401|
|OTP Banka Hungary|22391|
|Raiffeisen Bank|22381|
|UniCredit Bank Hungary|22371|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/hungary/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 22381, // Bank ID
    "abbr": "RAIFFEISEN-BANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "Raiffeisen Bank", // International bank name
    "nativeName": "Raiffeisen Bank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 22371,
    "abbr": "UNICREDIT-HUNGARY",
    "name": "UniCredit Bank Hungary",
    "nativeName": "UniCredit Bank Hungary",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22401,
    "abbr": "KH-BANK",
    "name": "K&H Bank",
    "nativeName": "K&H Bank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Hungary methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Hungary method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Hungary payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_hungary_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Hungary method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Hungary method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Hungary method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_hungary.md#section_o5s_vfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_hungary.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Hungary method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_o5s_vfd_wbc .section}

There are several things you need to consider when using the Open Banking in Hungary method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_hungarian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_hungarian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_hungarian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_hungarian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Hungary method code \(`online-hungarian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-hungarian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_hungarian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Hungary method code \(`online-hungarian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_hungarian_banks\": {\"split_banks\": true, \"banks_id\": [22401, 22391]}}",
        "force_payment_method": "online-hungarian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_hungarian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Hungary method code \(`online-hungarian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_hungarian_banks\": {\"split_banks\": true, \"banks_id\": [22391]}}",
        "force_payment_method": "online-hungarian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Hungary method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-hungarian-banks",
   "payment_methods_options": {"online_hungarian_banks": {"split_banks": true, "banks_id": [22381, 22391]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Hungary method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 HUF` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Hungarian Banks",
            "sum": {
                "amount": 1000,
                "currency": "HUF"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "HUF"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "HUF"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Hungarian Banks",
            "sum": {
                "amount": 100,
                "currency": "HUF"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "HUF"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "HUF"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_hungary_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Hungary method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Hungary method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Hungary method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Hungary method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/hungary/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Hungary method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "HUF"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "HUF"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Hungary payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Hungary method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Hungary method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 HUF` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Hungarian Banks",
            "sum": {
                "amount": 1000,
                "currency": "HUF"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "HUF"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "HUF"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Hungarian Banks",
            "sum": {
                "amount": 100,
                "currency": "HUF"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "HUF"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "HUF"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_hungary_dash_analysis}

To analyse information about payments made with the Open Banking in Hungary method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Italy {#pm_italy}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Italy.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_italy_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Italy.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Italy an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Italy.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Italy payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Italy method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|-   bank accounts
-   payments cards

|
|Countries and regions|[IT](references/en/countries/IT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|Purchases|+|
|Payouts|–|
|Stored credentials payments|–|
|Full refunds|–|
|Partial refunds|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_italy.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_italy.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_italy.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Obtaining access to the payment method and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-italy/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Italy method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_italy_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Italy method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Italy method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Italy method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_italy.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_italy.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Italy method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Banca Fideuram s.p.a|22291|
|Banca Monte dei Paschi di Siena Spa|22331|
|Banca Popolara di Sondrio|22311|
|Banca Popolare Cassinate|22251|
|Banca Popolare Cortona|22261|
|Banca Popolare Lajatico|22271|
|Banca Popolare Vesuviana|22281|
|Banca Sella|22351|
|Banco BPM|22201|
|BNL|22301|
|Buddybank|22181|
|Credito Emiliano S.p.A|22341|
|Credito Valtellinese|22361|
|ING Italy|22191|
|Intesa Sanpaolo|22211|
|Intesa Sanpaolo Private Banking|22221|
|IW Bank|22321|
|PostePay S.p.A|22241|
|UBI Banca|22231|
|UniCredit SpA|22171|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/italy/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

``` {#codeblock_mqf_bdm_rgc .language-json}
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

``` {#codeblock_nqf_bdm_rgc .language-json}
[
  {
    "id": 22291, // Bank ID
    "abbr": "FIDEURAM-SPA", // The service name of the bank in the platform (or its abbreviation)
    "name": "Banca Fideuram s.p.a", // International bank name
    "nativeName": "Banca Fideuram s.p.a", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 22201,
    "abbr": "BANCO-BPM",
    "name": "Banco BPM - YouWeb",
    "nativeName": "Banco BPM - YouWeb",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22191,
    "abbr": "ING-ITALY",
    "name": "ING Italy",
    "nativeName": "ING Italy",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Italy methods, refer to your Ecommpay account manager.

## Purchases by using Payment Page {#en_pm_italy_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Italy method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Italy method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Italy method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_italy.md#section_tq2_sfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Italy method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when using the Open Banking in Italy method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_italian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ``` {#codeblock_yls_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_italian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_italian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ``` {#codeblock_ams_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_italian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Italy method code \(`online-italian-banks`\) in the `force_payment_method` parameter.

        ``` {#codeblock_cms_y2m_rgc .language-json}
        "force_payment_method": "online-italian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_italian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Italy method code \(`online-italian-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_ems_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_italian_banks\": {\"split_banks\": true, \"banks_id\": [21971, 21961]}}",
        "force_payment_method": "online-italian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_italian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Italy method code \(`online-italian-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_gms_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_italian_banks\": {\"split_banks\": true, \"banks_id\": [21961]}}",
        "force_payment_method": "online-italian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Italy method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

``` {#codeblock_ims_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_jms_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

``` {#codeblock_kms_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-italian-banks",
   "payment_methods_options": {"online_italian_banks": {"split_banks": true, "banks_id": [21961, 21971]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Italy method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Italian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Italian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_italy_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Italy method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Italy method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Italy method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Italy method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/italy/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Italy method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

``` {#codeblock_ofw_3fm_rgc .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

``` {#codeblock_pfw_3fm_rgc .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Italy payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

``` {#codeblock_qfw_3fm_rgc .language-json}
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

``` {#codeblock_sfw_3fm_rgc .language-json}
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Italy method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_ufw_3fm_rgc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Italy method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Italian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Italian Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_italy_dash_analysis}

To analyse information about payments made with the Open Banking in Italy method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Ireland {#pm_ireland}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Ireland.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_ireland_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Ireland.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Ireland an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Ireland.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Ireland payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Ireland method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[IE](references/en/countries/IE.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_ireland.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_ireland.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_ireland.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-ireland/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Ireland method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_ireland_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Ireland method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Ireland method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Ireland method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_ireland.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_ireland.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Ireland method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|SumUp|81151|
|Airwallex|81141|
|N26|22561|
|Revolut Europe|55701|
|PTSB|69821|
|Elavon Financial Services|69811|
|Avant Money|69801|
|An Post Money Credit Card|69791|
|An Post Bank|69781|
|Allied Irish Banks Personal|69771|
|Bank Of Ireland|3511|
|Bank Of Ireland Business|55061|
|Allied Irish Bank Business|3501|
|Soldo|69593|
|Wise|55051|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/ireland/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

``` {#codeblock_mqf_bdm_rgc .language-json}
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

``` {#codeblock_nqf_bdm_rgc .language-json}
[
  {
    "id": 81151, // Bank ID
    "abbr": "SUMUP", // The service name of the bank in the platform (or its abbreviation)
    "name": "SumUp", // International bank name
    "nativeName": "SumUp Ireland", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 81141,
    "abbr": "AIRW-EU",
    "name": "Airwallex",
    "nativeName": "Airwallex",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22561,
    "abbr": "N26",
    "name": "N26",
    "nativeName": "N26",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Ireland methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Ireland method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Ireland payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_ireland_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Ireland method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Ireland method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Ireland method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_ireland.md#section_tq2_sfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Ireland method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_tq2_sfd_wbc .section}

There are several things you need to consider when using the Open Banking in Ireland method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_irish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ``` {#codeblock_yls_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_irish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_irish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ``` {#codeblock_ams_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_irish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Ireland method code \(`online-irish-banks`\) in the `force_payment_method` parameter.

        ``` {#codeblock_cms_y2m_rgc .language-json}
        "force_payment_method": "online-irish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_irish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Ireland method code \(`online-irish-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_ems_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_irish_banks\": {\"split_banks\": true, \"banks_id\": [21971, 21961]}}",
        "force_payment_method": "online-irish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_irish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Ireland method code \(`online-irish-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_gms_y2m_rgc .language-json}
        "payment_methods_options": "{\"online_irish_banks\": {\"split_banks\": true, \"banks_id\": [21961]}}",
        "force_payment_method": "online-irish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Ireland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

``` {#codeblock_ims_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_jms_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

``` {#codeblock_kms_y2m_rgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-irish-banks",
   "payment_methods_options": {"online_irish_banks": {"split_banks": true, "banks_id": [21961, 21971]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Ireland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

``` {#codeblock_lms_y2m_rgc .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Irish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_mms_y2m_rgc .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Irish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_ireland_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Ireland method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Ireland method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Ireland method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Ireland method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/ireland/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Ireland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

``` {#codeblock_ofw_3fm_rgc .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

``` {#codeblock_pfw_3fm_rgc .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Ireland payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

``` {#codeblock_qfw_3fm_rgc .language-json}
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

``` {#codeblock_sfw_3fm_rgc .language-json}
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Ireland method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_ufw_3fm_rgc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Ireland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

``` {#codeblock_vfw_3fm_rgc .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Irish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_wfw_3fm_rgc .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Irish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_ireland_dash_analysis}

To analyse information about payments made with the Open Banking in Ireland method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Latvia {#pm_latvia}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Latvia.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_latvia_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Latvia.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Latvia an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Latvia.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Latvia payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Latvia method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[LV](references/en/countries/LV.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_latvia.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_latvia.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_latvia.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-latvia/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Latvia method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_latvianob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Latvia method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Latvia method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_latvia_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Latvia method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_latvia.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_latvia.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Latvia method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|SEB bank|1991|
|Swedbank|1981|
|Rietumu bank|2001|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/latvia/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 1991, // Bank ID
    "abbr": "SEB", // The service name of the bank in the platform (or its abbreviation)
    "name": "SEB bank", // International bank name
    "nativeName": "SEB banka", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 1981,
    "abbr": "SWEDBANK",
    "name": "Swedbank",
    "nativeName": "Swedbank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2001,
    "abbr": "RIETUMU",
    "name": "Rietumu bank",
    "nativeName": "AS "Rietumu Banka"",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Latvia methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Latvia method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Latvia payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_latvia_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Latvia method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_latvia.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_pp.svg "Purchase processing by using Payment Page with redirecting the customer to provider service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Latvia methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The request for processing the payment is sent from the provider service to the bank service.
14. The purchase is processed on the side of the bank service.
15. The bank service sends the notification about the result to the provider service.
16. The result information is displayed to the customer on the side of the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends information about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

![](images/pm/eng_open_banking_bank_uml_pp.svg "Purchase sequence by using Payment Page with redirecting the customer to bank service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Latvia methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends the notification about the result to the provider service.
17. The provider service sends the notification about the result to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Latvia method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_latvia.md#section_jt1_yfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_latvia.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Latvia method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_jt1_yfd_wbc .section}

There are several things you need to consider when using the Open Banking in Latvia method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_latvian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_latvian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_latvian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_latvian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Latvia method code \(`online-latvian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-latvian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_latvian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Latvia method code \(`online-latvian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_latvian_banks\": {\"split_banks\": true, \"banks_id\": [1991, 1981]}}",
        "force_payment_method": "online-latvian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_latvian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Latvia method code \(`online-latvian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_latvian_banks\": {\"split_banks\": true, \"banks_id\": [1991]}}",
        "force_payment_method": "online-latvian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Latvia method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-latvian-banks",
   "payment_methods_options": {"online_latvian_banks": {"split_banks": true, "banks_id": [1981, 1991]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Latvia method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Latvian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Latvian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_latvia_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Latvia method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to provider service")

1.  A customer initiates a purchase by using the Open Banking in Latvia method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The request for processing the payment is sent from provider service to the bank service.
11. The purchase is processed on the side of the bank service.
12. The bank service sends the notification about the result to the provider service.
13. The result information is displayed to the customer on the side of the provider service.
14. The customer is redirected to the web service.
15. The provider service sends information about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

![](images/pm/eng_open_banking_bank_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to the bank service")

1.  A customer initiates a purchase by using the Open Banking in Latvia method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service, and then to the bank service, where payment instruction is displayed to the customer.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Latvia method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Latvia method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/latvia/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Latvia method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Latvia payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Latvia method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Latvia method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Latvian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Latvian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_latvia_dash_analysis}

To analyse information about payments made with the Open Banking in Latvia method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Lithuania {#pm_lithuania}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Lithuania.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_lithuania_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Lithuania.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Lithuania an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Lithuania.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Lithuania payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Lithuania method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[LT](references/en/countries/LT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_lithuania.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_lithuania.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_lithuania.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-lithuania/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Lithuania method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_lithuanianob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Lithuania method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Lithuania method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_lithuania_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Lithuania method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_lithuania.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_lithuania.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Lithuania method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Lietuvos centrinė kredito unija \(LCKU\)|2081|
|NEO Finance, AB|2071|
|Šiaulių bankas AB|2061|
|Luminor \(Nordea\)|2051|
|Luminor \(DNB\)|2041|
|Citadele|2031|
|SEB Bank|2021|
|Swedbank|2011|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/lithuania/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 2081, // Bank ID
    "abbr": "LCKU", // The service name of the bank in the platform (or its abbreviation)
    "name": "LCKU", // International bank name
    "nativeName": "Lietuvos centrinė kredito unija", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 2031,
    "abbr": "CITADELE",
    "name": "Citadele",
    "nativeName": "AB Citadele bankas",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2021,
    "abbr": "SEB",
    "name": "SEB bank",
    "nativeName": "AB SEB bankas",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Lithuania methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Lithuania method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Lithuania payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_lithuania_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Lithuania method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_lithuania.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_pp.svg "Purchase processing by using Payment Page with redirecting the customer to provider service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Lithuania methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The request for processing the payment is sent from the provider service to the bank service.
14. The purchase is processed on the side of the bank service.
15. The bank service sends the notification about the result to the provider service.
16. The result information is displayed to the customer on the side of the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends information about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

![](images/pm/eng_open_banking_bank_uml_pp.svg "Purchase sequence by using Payment Page with redirecting the customer to bank service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Lithuania methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends the notification about the result to the provider service.
17. The provider service sends the notification about the result to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Lithuania method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_lithuania.md#section_aff_tfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_lithuania.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Lithuania method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_aff_tfd_wbc .section}

There are several things you need to consider when using the Open Banking in Lithuania method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_lithuanian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_lithuanian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_lithuanian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_lithuanian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Lithuania method code \(`online-lithuanian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-lithuanian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_lithuanian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Lithuania method code \(`online-lithuanian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_lithuanian_banks\": {\"split_banks\": true, \"banks_id\": [2081, 2071]}}",
        "force_payment_method": "online-lithuanian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_lithuanian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Lithuania method code \(`online-lithuanian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_lithuanian_banks\": {\"split_banks\": true, \"banks_id\": [2081]}}",
        "force_payment_method": "online-lithuanian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Lithuania method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-lithuanian-banks",
   "payment_methods_options": {"online_lithuanian_banks": {"split_banks": true, "banks_id": [2071, 2081]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Lithuania method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Lithuanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Lithuanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_lithuania_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Lithuania method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_gate.svg "Purchase sequence by using Payment Page with redirecting the customer to provider service")

1.  A customer initiates a purchase by using the Open Banking in Lithuania method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The request for processing the payment is sent from provider service to the bank service.
11. The purchase is processed on the side of the bank service.
12. The bank service sends the notification about the result to the provider service.
13. The result information is displayed to the customer on the side of the provider service.
14. The customer is redirected to the web service.
15. The provider service sends information about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

![](images/pm/eng_open_banking_bank_uml_gate.svg "Purchase sequence by using Payment Page with redirecting the customer to the bank service")

1.  A customer initiates a purchase by using the Open Banking in Lithuania method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service, and then to the bank service, where payment instruction is displayed to the customer.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Lithuania method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Lithuania method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/lithuania/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Lithuania method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Lithuania payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Lithuania method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Lithuania method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Lithuanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Lithuanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_lithuania_dash_analysis}

To analyse information about payments made with the Open Banking in Lithuania method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Luxembourg {#pm_luxembourg}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Luxembourg.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_luxembourg_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Luxembourg.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Luxembourg an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Luxembourg.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Luxembourg payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Luxembourg method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[LU](references/en/countries/LU.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_luxembourg.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_luxembourg.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_luxembourg.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-luxembourg/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Luxembourg method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_belgium_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Luxembourg method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Luxembourg method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Luxembourg method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_luxembourg.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_luxembourg.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Luxembourg method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Deutsche Bank AG, Branch Luxemburg|22681|
|UBS Luxembourg|22671|
|Banque de Luxembourg|22661|
|Societe Generale|22651|
|Banque et Caisse d'Epargne de l'Etat|22641|
|ING Luxembourg|22631|
|Banque Raiffeisen Luxemburg|22621|
|Banque Internationale a Luxembourg|22611|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/luxembourg/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

``` {#codeblock_dvb_11v_53c .language-json}
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

``` {#codeblock_evb_11v_53c .language-json}
[
  {
    "id": 22681, // Bank ID
    "abbr": "DBGABL", // The service name of the bank in the platform (or its abbreviation)
    "name": "Deutsche Bank AG, Branch Luxemburg", // International bank name
    "nativeName": "Deutsche Bank AG, Branch Luxemburg", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 22651,
    "abbr": "SOCIETE-GENERALE",
    "name": "Societe Generale",
    "nativeName": "Societe Generale",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22631,
    "abbr": "ING",
    "name": "ING Luxembourg",
    "nativeName": "ING Luxembourg",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Luxembourg methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Luxembourg method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Luxembourg payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_luxembourg_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Luxembourg method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Luxembourg method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Luxembourg method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_luxembourg.md#section_glz_jfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Luxembourg method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_glz_jfd_wbc .section}

There are several things you need to consider when using the Open Banking in Luxembourg method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_luxembourg_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ``` {#codeblock_z14_lbv_53c .language-json}
        "payment_methods_options": "{\"online_luxembourg_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_luxembourg_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ``` {#codeblock_bb4_lbv_53c .language-json}
        "payment_methods_options": "{\"online_luxembourg_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Luxembourg method code \(`online-luxembourg-banks`\) in the `force_payment_method` parameter.

        ``` {#codeblock_db4_lbv_53c .language-json}
        "force_payment_method": "online-luxembourg-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_luxembourg_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Luxembourg method code \(`online-luxembourg-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_fb4_lbv_53c .language-json}
        "payment_methods_options": "{\"online_luxembourg_banks\": {\"split_banks\": true, \"banks_id\": [22681, 22651]}}",
        "force_payment_method": "online-luxembourg-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_luxembourg_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Luxembourg method code \(`online-luxembourg-banks`\) in the `force_payment_method` parameter.
        ``` {#codeblock_hb4_lbv_53c .language-json}
        "payment_methods_options": "{\"online_luxembourg_banks\": {\"split_banks\": true, \"banks_id\": [22651]}}",
        "force_payment_method": "online-luxembourg-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Luxembourg method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

``` {#codeblock_jb4_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_kb4_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

``` {#codeblock_lb4_lbv_53c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": " online-luxembourg-banks ",
   "payment_methods_options": {"online_luxembourg_banks": {"split_banks": true, "banks_id": [22681, 22651]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Luxembourg method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

``` {#codeblock_mb4_lbv_53c .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Luxembourg Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_nb4_lbv_53c .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Luxembourg Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_luxembourg_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Luxembourg method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Luxembourg method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Luxembourg method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Luxembourg method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/luxembourg/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Luxembourg method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

``` {#codeblock_n1j_xbv_53c .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

``` {#codeblock_o1j_xbv_53c .language-json}
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Luxembourg payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

``` {#codeblock_p1j_xbv_53c .language-json}
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

``` {#codeblock_r1j_xbv_53c .language-json}
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Luxembourg method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_t1j_xbv_53c .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Luxembourg method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

``` {#codeblock_u1j_xbv_53c .language-json}
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Luxembourg Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_v1j_xbv_53c .language-json}
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Luxembourg Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payment results {#en_pm_luxembourg_dash_analysis}

To analyse information about payments made with the Open Banking in Luxembourg method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in the Netherlands {#pm_netherlands}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of the Netherlands.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_netherlands_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of the Netherlands.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in the Netherlands an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of the Netherlands.

The Ecommpay payment platform supports processing purchases made with the Open Banking in the Netherlands payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in the Netherlands method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[NL](references/en/countries/NL.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_netherlands.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_netherlands.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_netherlands.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-netherlands/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in the Netherlands method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_netherlandsob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in the Netherlands method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in the Netherlands method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_netherlands_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in the Netherlands method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_netherlands.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_netherlands.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in the Netherlands method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Rabobank|2141|
|ABN AMRO Bank N.V.|2131|
|ING Group|2121|
|Van Lanschot NV|2151|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/netherlands/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 2141, // Bank ID
    "abbr": "RABOBANK", // The service name of the bank in the platform (or its abbreviation)
    "name": "Rabobank", // International bank name
    "nativeName": "Rabobank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 2121,
    "abbr": "ING",
    "name": "ING Group",
    "nativeName": "ING Groep N.V.",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2151,
    "abbr": "VL",
    "name": "Van Lanschot NV",
    "nativeName": "Van Lanschot NV",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in the Netherlands methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in the Netherlands method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in the Netherlands payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_netherlands_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in the Netherlands method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_netherlands.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_pp.svg "Purchase processing by using Payment Page with redirecting the customer to provider service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in the Netherlands methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The request for processing the payment is sent from the provider service to the bank service.
14. The purchase is processed on the side of the bank service.
15. The bank service sends the notification about the result to the provider service.
16. The result information is displayed to the customer on the side of the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends information about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

![](images/pm/eng_open_banking_bank_uml_pp.svg "Purchase sequence by using Payment Page with redirecting the customer to bank service")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in the Netherlands methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends the notification about the result to the provider service.
17. The provider service sends the notification about the result to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in the Netherlands method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_netherlands.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_netherlands.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in the Netherlands method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when using the Open Banking in the Netherlands method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_netherlands_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_netherlands_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_netherlands_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_netherlands_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in the Netherlands method code \(`online-netherlands-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-netherlands-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_netherlands_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in the Netherlands method code \(`online-netherlands-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_netherlands_banks\": {\"split_banks\": true, \"banks_id\": [2141, 2131]}}",
        "force_payment_method": "online-netherlands-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_netherlands_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in the Netherlands method code \(`online-netherlands-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_netherlands_banks\": {\"split_banks\": true, \"banks_id\": [2141]}}",
        "force_payment_method": "online-netherlands-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in the Netherlands method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-netherlands-banks",
   "payment_methods_options": {"online_netherlands_banks": {"split_banks": true, "banks_id": [2141, 2131]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in the Netherlands method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Netherlands Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Netherlands Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_netherlands_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in the Netherlands method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to provider service")

1.  A customer initiates a purchase by using the Open Banking in the Netherlands method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The request for processing the payment is sent from provider service to the bank service.
11. The purchase is processed on the side of the bank service.
12. The bank service sends the notification about the result to the provider service.
13. The result information is displayed to the customer on the side of the provider service.
14. The customer is redirected to the web service.
15. The provider service sends information about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

![](images/pm/eng_open_banking_bank_uml_gate.svg "Purchase sequence by using Gate with redirecting the customer to the bank service")

1.  A customer initiates a purchase by using the Open Banking in the Netherlands method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service, and then to the bank service, where payment instruction is displayed to the customer.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in the Netherlands method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in the Netherlands method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/netherlands/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in the Netherlands method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in the Netherlands payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in the Netherlands method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in the Netherlands method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "method": "Netherlands Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2020-03-20T14:22:06+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "method": "Netherlands Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-20T14:22:07+0000",
            "created_date": "2020-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_netherlands_dash_analysis}

To analyse information about payments made with the Open Banking in the Netherlands method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Norway {#pm_norway}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Norwegian kroner via the banks of Norway.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_norway_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Norwegian kroner via the banks of Norway.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Norway an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in Norwegian kroner via the banks of Norway.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Norway payment method.

This article provides information about working with the Open Banking in Norway method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[NO](references/en/countries/NO.md)|
|Payment currencies|[NOK](references/en/currencies/NOK.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   Payment Page supports different bank and method selection options\(more details [below](pm_norway.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_norway.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_norway.md#section_yln_qjn_ftb)\)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-norway/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Norway method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_norway_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Norway method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Norway method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Norway method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_norway.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_norway.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Norway method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Danske Bank|55251|
|DNB|55261|
|Handelsbanken|55311|
|Nordea|55271|
|SBanken|55301|
|Sparebank1|55281|
|Sparebanken Vest|55291|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/norway/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 55251, // Bank ID
    "abbr": "DANSKE-BANK", // Bank abbreviation (for internal use)
    "name": "Danske Bank", // Official bank name
    "nativeName": "Danske Bank", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // Alphabetic code of the payment currency in ISO-4217 alpha-3 format
        "number_3_4217": "978", // Numeric code of the payment currency in ISO-4217 alpha-3 format
        "exponent": 2 // The number of minor units of the currency
      }
    ]
  },
  {
    "id": 55271,
    "abbr": "NORDEA",
    "name": "Nordea",
    "nativeName": "Nordea",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55301,
    "abbr": "SBANKEN",
    "name": "SBanken",
    "nativeName": "SBanken",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Open Banking in Norway methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Norway method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Norway payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_norway_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Norway method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_norway_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Norway method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
12. The customer completes all required payment steps on the side of the used service.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends information about the result to the provider service.
17. The provider service sends the payment result information to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Norway method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_norway.md#section_sgg_wfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_norway.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Norway method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_sgg_wfd_wbc .section}

There are several things you need to consider when using the Open Banking in Norway method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_norwegian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_norwegian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_norwegian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_norwegian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Norway method code \(`online-norwegian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-norwegian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_norwegian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Norway method code \(`online-norwegian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_norwegian_banks\": {\"split_banks\": true, \"banks_id\": [55251, 55261]}}",
        "force_payment_method": "online-norwegian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_norwegian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Norway method code \(`online-norwegian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_norwegian_banks\": {\"split_banks\": true, \"banks_id\": [55251]}}",
        "force_payment_method": "online-norwegian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

3.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
4.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Norway method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature, as well as various optional parameters.

```language-json
{
   /"project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "NOK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "NOK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "NOK",
   "customer_id": "customer1",
   "force_payment_method": "online-norwegian-banks",
   "payment_methods_options": {"online_norwegian_banks": {"split_banks": true, "banks_id": [55261, 55251]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Norway method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 NOK` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Norwegian Banks",
            "sum": {
                "amount": 1000,
                "currency": "NOK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "NOK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "NOK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC5678",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Norwegian Banks",
            "sum": {
                "amount": 1000,
                "currency": "NOK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "NOK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "NOK"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_norway_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Norway method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

Information about the data formats used to perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_norway_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Norway method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Norway method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_onh_2xj_wbc .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Norway method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/norway/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `success`—URL for redirecting a customer after a processed purchase
        -   `decline`—URL for redirecting a customer after a declined purchase
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Norway method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URLs for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "NOK"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "NOK"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Norway method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Norway method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 NOK` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Norwegian Banks",
            "sum": {
                "amount": 1000,
                "currency": "NOK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "NOK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "NOK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Norwegian Banks",
            "sum": {
                "amount": 1000,
                "currency": "NOK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "NOK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "NOK"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_norway_dash_analysis}

To analyse information about payments made with the Open Banking in Norway method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Poland {#pm_poland}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in zloty via the banks of Poland.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_poland_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in zloty via the banks of Poland.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Poland an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in zloty via the banks of Poland.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Poland payment method.

This article provides information about working with the Open Banking in Poland method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PL](references/en/countries/PL.md)|
|Payment currencies|[PLN](references/en/currencies/PLN.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   Payment Page supports different bank and method selection options\(more details [below](pm_poland.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_poland.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_poland.md#section_yln_qjn_ftb)\)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-poland/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Poland method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_poland_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Poland method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Poland method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Poland method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_poland.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_poland.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Poland method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Alior Bank|22411|
|Bank Millennium|22421|
|Bank Pekao|22431|
|BNP Paribas|55421|
|Credit Agricole|22481|
|Idea Bank|22521|
|ING Bank Slaski|22531|
|Inteligo|22541|
|mBank|22551|
|Nest Bank|22571|
|PKO Bank Polski|22581|
|Santander Bank Polska|22591|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/poland/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 22411, // Bank ID
    "abbr": "ALIOR", // Bank abbreviation (for internal use)
    "name": "Alior Bank", // Official bank name
    "nativeName": "Alior Bank", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 1140, // Currency ID in the payment platform
        "alpha_3_4217": "PLN", // Alphabetic code of the payment currency in ISO-4217 alpha-3 format
        "number_3_4217": "985", // Numeric code of the payment currency in ISO-4217 alpha-3 format
        "exponent": 2 // The number of minor units of the currency
      }
    ]
  },
  {
    "id": 22551,
    "abbr": "MBANK",
    "name": "mBank",
    "nativeName": "mBank",
    "currencies": [
      {
        "id": 1140,
        "alpha_3_4217": "PLN",
        "number_3_4217": "985",
        "exponent": 2
      }
    ]
  },
  {
    "id": 22581,
    "abbr": "PKO-BANK-POLSKI",
    "name": "PKO Bank Polski",
    "nativeName": "PKO Bank Polski",
    "currencies": [
      {
        "id": 1140,
        "alpha_3_4217": "PLN",
        "number_3_4217": "985",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Open Banking in Poland methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Poland method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Poland payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_poland_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Poland method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_poland_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Poland method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
12. The customer completes all required payment steps on the side of the used service.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends information about the result to the provider service.
17. The provider service sends the payment result information to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Poland method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_poland.md#section_ndb_lfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_poland.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Poland method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_ndb_lfd_wbc .section}

There are several things you need to consider when using the Open Banking in Poland method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_polish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_polish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Poland method code \(`online-polish-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-polish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_polish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Poland method code \(`online-polish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true, \"banks_id\": [22411, 22421]}}",
        "force_payment_method": "online-polish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_polish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Poland method code \(`online-polish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_polish_banks\": {\"split_banks\": true, \"banks_id\": [22411]}}",
        "force_payment_method": "online-polish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Poland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "force_payment_method": "online-polish-banks",
   "payment_methods_options": {"online_polish_banks": {"split_banks": true, "banks_id": [22411, 22421]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Poland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PLN` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Polish Banks",
            "sum": {
                "amount": 1000,
                "currency": "PLN"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PLN"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Polish Banks",
            "sum": {
                "amount": 1000,
                "currency": "PLN"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PLN"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_poland_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Poland method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

Information about the data formats used to perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_poland_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Poland method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Poland method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_onh_2xj_wbc .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Poland method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/poland/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `success`—URL for redirecting a customer after a processed purchase
        -   `decline`—URL for redirecting a customer after a declined purchase
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Poland method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URLs for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "PLN"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "PLN"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Poland method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Poland method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PLN` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Polish Banks",
            "sum": {
                "amount": 1000,
                "currency": "PLN"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PLN"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Polish Banks",
            "sum": {
                "amount": 1000,
                "currency": "PLN"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PLN"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_poland_dash_analysis}

To analyse information about payments made with the Open Banking in Poland method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Portugal {#pm_portugal}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Portugal.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_portugal_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Portugal.

### Introduction {#section_itp_fcc_wbc .section}

Open Banking in Portugal an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information. This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Portugal.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Portugal payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Portugal method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PT](references/en/countries/PT.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_portugal.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_portugal.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_portugal.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-portugal/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Portugal method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_portugal_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Portugal method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Portugal method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Portugal method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_portugal.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_portugal.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Portugal method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
| | |
|Banco Activobank|6651|
|Millennium bcp|6641|
|Novo Banco Dos Acores|6631|
|Novo Banco|6621|
|Banco Santander Totta|6331|
|Banco BPI|6661|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/portugal/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 6631, // Bank ID
    "abbr": "NBDA", // The service name of the bank in the platform (or its abbreviation)
    "name": "NOVO BANCO DOS ACORES", // International bank name
    "nativeName": "NOVO BANCO DOS ACORES", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 6661,
    "abbr": "BANCO-BPI",
    "name": "Banco BPI",
    "nativeName": "Banco BPI",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 6331,
    "abbr": "BST-TOTA",
    "name": "Banco Santander Totta",
    "nativeName": "Banco Santander Totta",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Portugal methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Portugal method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Portugal payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_portugal_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Portugal method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Portugal method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Portugal method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_portugal.md#section_mlx_mfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_portugal.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Portugal method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_mlx_mfd_wbc .section}

There are several things you need to consider when using the Open Banking in Portugal method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_portuguese_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_portuguese_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Portugal method code \(`online-portuguese-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-portuguese-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_portuguese_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Portugal method code \(`online-portuguese-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true, \"banks_id\": [6651, 6641]}}",
        "force_payment_method": "online-portuguese-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_portuguese_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Portugal method code \(`online-portuguese-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_portuguese_banks\": {\"split_banks\": true, \"banks_id\": [6651]}}",
        "force_payment_method": "online-portuguese-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Portugal method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-portuguese-banks",
   "payment_methods_options": {"online_portuguese_banks": {"split_banks": true, "banks_id": [6651, 6641]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Portugal method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Portuguese Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Portuguese Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_portugal_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Portugal method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Portugal method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Portugal method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Portugal method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/portugal/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Portugal method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Portugal payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Portugal method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Portugal method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Portuguese Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Portuguese Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_portugal_dash_analysis}

To analyse information about payments made with the Open Banking in Portugal method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Romania {#pm_romania}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in lei via the banks of Romania.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_romania_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in lei via the banks of Romania.

### Introduction {#section_rlc_qcc_wbc .section}

Open Banking in Romania an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in lei via the banks of Romania.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Romania payment method.

This article provides information about working with the Open Banking in Romania method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[RO](references/en/countries/RO.md)|
|Payment currencies|[RON](references/en/currencies/RON.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Notes|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_romania.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_romania.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_romania.md#section_yln_qjn_ftb)\)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-romania/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Romania method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_romaniaob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Romania method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Romania method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Romania method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_romania.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_romania.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Romania method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Banca Comerciala Romana|55941|
|Banca Transilvania|55931|
|BRD Groupe Societe Generale|55951|
|ING Bank|55961|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/romania/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 55941, // Bank ID
    "abbr": "BANCACOMRO", // The service name of the bank in the platform (or its abbreviation)
    "name": "Banca Comerciala Romana", // International bank name
    "nativeName": "Banca Comerciala Romana", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 1080, // Currency ID in the payment platform
        "alpha_3_4217": "RON", // ISO-4217 alphabetic currency code
        "number_3_4217": "946", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 55931,
    "abbr": "BANCATRANSRO",
    "name": "Banca Transilvania",
    "nativeName": "Banca Transilvania",
    "currencies": [
      {
        "id": 1080,
        "alpha_3_4217": "RON",
        "number_3_4217": "946",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55951,
    "abbr": "BRDGSGRO",
    "name": "BRD Groupe Societe Generale",
    "nativeName": "BRD Groupe Societe Generale",
    "currencies": [
      {
        "id": 1080,
        "alpha_3_4217": "RON",
        "number_3_4217": "946",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Romania methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Romania method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Romania payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_romania_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Romania method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_ro_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Romania methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The request for processing the payment is sent from the provider service to the bank service.
14. The purchase is processed on the side of the bank service.
15. The bank service sends the notification about the result to the provider service.
16. The result information is displayed to the customer on the side of the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends information about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

![](images/pm/eng_open_banking_bank_ro_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects one of the Open Banking in Romania methods and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from Payment Page to the payment platform.
    5.  The information is processed on the payment platform side.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the provider service where payment instructions are displayed.
12. The customer completes all required payment steps.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends the notification about the result to the provider service.
17. The provider service sends the notification about the result to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Romania method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_romania.md#section_ubw_nfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_romania.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Romania method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_ubw_nfd_wbc .section}

There are several things you need to consider when using the Open Banking in Romania method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_romanian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_romanian_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_romanian_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_romanian_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Romania method code \(`online-romanian-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-romanian-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_romanian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Romania method code \(`online-romanian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_romanian_banks\": {\"split_banks\": true, \"banks_id\": [55941, 55931]}}",
        "force_payment_method": "online-romanian-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_romanian_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Romania method code \(`online-romanian-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_romanian_banks\": {\"split_banks\": true, \"banks_id\": [55941]}}",
        "force_payment_method": "online-romanian-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Romania method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "RON",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "RON",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "RON",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-romanian-banks",
   "payment_methods_options": {"online_romanian_banks": {"split_banks": true, "banks_id": [55931, 55941]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Romania method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 RON` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2022-03-20T14:22:06+0000",
            "method": "Romanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "RON"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2022-03-20T14:22:06+0000",
            "created_date": "2022-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "RON"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RON"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2022-03-20T14:22:07+0000",
            "method": "Romanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "RON"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2022-03-20T14:22:07+0000",
            "created_date": "2022-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "RON"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RON"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_romania_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Romania method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_open_banking_provider_ro_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Romania method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The request for processing the payment is sent from provider service to the bank service.
11. The purchase is processed on the side of the bank service.
12. The bank service sends the notification about the result to the provider service.
13. The result information is displayed to the customer on the side of the provider service.
14. The customer is redirected to the web service.
15. The provider service sends information about the result to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

![](images/pm/eng_open_banking_bank_ro_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Romania method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer. If such consent \(and information\) is required, the following steps are followed:
    1.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
    2.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
    3.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
    4.  The information provided by the customer is sent from the web service to the payment platform.
    5.  The information is processed on the payment platform side.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service, and then to the bank service, where payment instruction is displayed to the customer.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Romania method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Romania method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/romania/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Romania method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "RON"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "RON"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Romania payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Romania method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Romania method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 RON` purchase made in the `200` project.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc12345",
            "type": "purchase",
            "status": "success",
            "date": "2022-03-20T14:22:06+0000",
            "method": "Romanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "RON"
            },
            "description": "Success"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2022-03-20T14:22:06+0000",
            "created_date": "2022-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009530",
            "sum_initial": {
                "amount": 1000,
                "currency": "RON"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RON"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivMlmbhQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 200,
        "payment": {
            "id": "abc67890",
            "type": "purchase",
            "status": "decline",
            "date": "2022-03-20T14:22:07+0000",
            "method": "Romanian Banks",
            "sum": {
                "amount": 1000,
                "currency": "RON"
            },
            "description": "Decline"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 9529253065608,
            "type": "sale",
            "status": "decline",
            "date": "2022-03-20T14:22:07+0000",
            "created_date": "2022-03-20T14:22:00+0000",
            "request_id": "f1de353331a01fd14163fe4226-00009531",
            "sum_initial": {
                "amount": 1000,
                "currency": "RON"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RON"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1914,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "giRT+RB/rG5JrSMjb/...DaHDxz+JukI2+7HhMivM2mbhQ=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_romania_dash_analysis}

To analyse information about payments made with the Open Banking in Romania method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Spain {#pm_spain}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Spain.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_spain_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in euros via the banks of Spain.

### Introduction {#section_cdc_scc_wbc .section}

Open Banking in Spain an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in euros via the banks of Spain.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Spain payment method.You can also perform payouts by using [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in Spain method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[ES](references/en/countries/ES.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_spain.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_spain.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_spain.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Payouts to bank accounts in SEPA](pm_bankpayout_sepa.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-spain/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Spain method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_spain_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Spain method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Spain method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Spain method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_spain.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_spain.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Spain method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Banco Sabadell|56611|
|Bankinter|56621|
|Bantierra|56631|
|BBVA|56641|
|Caixa Bank|56651|
|Caixa Popular|56661|
|Caixa Rural Benicarlo|56671|
|Caja Rural de Asturias|56681|
|Caja Rural de Baena|56691|
|Caja Rural de Casas Ibanez|56701|
|Caja Rural de Extremadura|56711|
|Caja Rural de Jaen|56721|
|Caja Rural de Navarra|56731|
|Caja Rural de Onda|56741|
|Caja Rural de Rural Nostra|56751|
|Caja Rural de Salamanca|56761|
|Caja Rural de San Jose de Almassora|56771|
|Caja Rural de Soria|56781|
|Caja Rural de Villamalea|56791|
|Caja Rural de Zamora|56801|
|Caja Siete|56811|
|ING|56821|
|Kutxabank|56831|
|Santander|56841|
|Targobank|56851|
|Unicaja Banco|56861|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/spain/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 56611, // Bank ID
    "abbr": "T-SABADELES", // The service name of the bank in the platform (or its abbreviation)
    "name": "Banco Sabadell", // International bank name
    "nativeName": "Banco Sabadell", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // ISO-4217 alphabetic currency code
        "number_3_4217": "978", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 56641,
    "abbr": "T-BBVAES",
    "name": "BBVA",
    "nativeName": "BBVA",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 56661,
    "abbr": "T-CAIXAPOP",
    "name": "Caixa Popular",
    "nativeName": "Caixa Popular",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in Spain methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in Spain method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Spain payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchase by using Payment Page {#en_pm_spain_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Spain method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Spain method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Spain method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_spain.md#section_bmg_qfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_spain.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Spain method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_bmg_qfd_wbc .section}

There are several things you need to consider when using the Open Banking in Spain method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_spanish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_spanish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Spain method code \(`online-spanish-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-spanish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_spanish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Spain method code \(`online-spanish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true, \"banks_id\": [56611, 56621]}}",
        "force_payment_method": "online-spanish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_spanish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Spain method code \(`online-spanish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true, \"banks_id\": [56611]}}",
        "force_payment_method": "online-spanish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Spain method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "force_payment_method": "online-spanish-banks",
   "payment_methods_options": {"online_spanish_banks": {"split_banks": true, "banks_id": [56611, 56621]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Spain method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_spain_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Spain method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Spain method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Spain method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Spain method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/spain/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Spain method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in Spain payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Spain method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Spain method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 EUR` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_spain_dash_analysis}

To analyse information about payments made with the Open Banking in Spain method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in Sweden {#pm_sweden}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Swedish kronor via the banks of Sweden.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_sweden_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in Swedish kronor via the banks of Sweden.

### Introduction {#section_pgh_tcc_wbc .section}

Open Banking in Sweden an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in Swedish kronor via the banks of Sweden.

The Ecommpay payment platform supports processing purchases made with the Open Banking in Sweden payment method.

This article provides information about working with the Open Banking in Sweden method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[SE](references/en/countries/SE.md)|
|Payment currencies|[SEK](references/en/currencies/SEK.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   Payment Page supports different bank and method selection options\(more details [below](pm_sweden.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_sweden.md#section_bfg_sc1_qjc)\)

|
|Onboarding and access fee|refer to your Ecommpay account manager; additional information is available in [Ecommpay shop](https://ecommpay.com/shop/payment-methods/open-banking-sweden/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in Sweden method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_sweden_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in Sweden method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in Sweden method, you need to redirect the customer to the provider service.

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in Sweden method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchase by using Payment Page](pm_sweden.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_sweden.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in Sweden method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Nordea Bank|5121|
|Svenska Handelsbanken|5151|
|Swedbank|5161|
|DNB|55411|
|Alandsbanken|55401|
|Danske Bank|55391|
|SEB|55381|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/sweden/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 5121, // Bank ID
    "abbr": "NORDEA-SWEDEN", // Bank abbreviation (for internal use)
    "name": "Nordea Bank", // Official bank name
    "nativeName": "Nordea Bank", // Local bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 978, // Currency ID in the payment platform
        "alpha_3_4217": "EUR", // Alphabetic code of the payment currency in ISO-4217 alpha-3 format
        "number_3_4217": "978", // Numeric code of the payment currency in ISO-4217 alpha-3 format
        "exponent": 2 // The number of minor units of the currency
      }
    ]
  },
  {
    "id": 5161,
    "abbr": "SWEDBANK-SWEDEN",
    "name": "Swedbank",
    "nativeName": "Swedbank",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  },
  {
    "id": 55401,
    "abbr": "ALANDSBANKEN",
    "name": "Alandsbanken",
    "nativeName": "Alandsbanken",
    "currencies": [
      {
        "id": 978,
        "alpha_3_4217": "EUR",
        "number_3_4217": "978",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with banks supported by the Open Banking in Sweden methods, refer to your Ecommpay account manager.

## Purchase by using Payment Page {#en_pm_sweden_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in Sweden method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_sweden_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in Sweden method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request.
10. The data for redirecting the customer is sent from the payment platform to Payment Page.
11. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
12. The customer completes all required payment steps on the side of the used service.
13. The purchase is processed on the side of the bank service.
14. The result information is displayed to the customer on the side of the bank service.
15. The customer is redirected to Payment Page.
16. The bank service sends information about the result to the provider service.
17. The provider service sends the payment result information to the payment platform.
18. The payment platform sends the payment result callback to the web service.
19. The payment platform sends the result information to Payment Page.
20. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in Sweden method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_sweden.md#section_o1v_qfd_wbc)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, the buttons for selecting other methods of the specified group and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_open_banking_pp_1_sweden.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Sweden method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Request format {#section_o1v_qfd_wbc .section}

There are several things you need to consider when using the Open Banking in Sweden method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  The following are the bank selection options:

    1.  *Selecting the method and the bank on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object, mentioned in subpoints *2–6* are not used.
    2.  *Selecting a bank among other methods on Payment Page \(2\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_swedish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).

        ```language-json
        "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true}}"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed.

    3.  *Selecting a bank among other methods of the specified group on Payment Page \(3\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_swedish_banks`\), and the value of which is the `split_banks` parameter set to the value `true`.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the `openbanking` group code in the `force_payment_group` parameter
        ```language-json
        "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true}}",
        "force_payment_group": "openbanking"
        ```

        As a result of using this option for the specified method, instead of a button for selecting it, buttons for selecting all supported banks are displayed, as well as buttons for other methods of the Open Banking group.

    4.  *Selecting a bank among all available ones on Payment Page \(4\)*—for this option specify the selected Open Banking in Sweden method code \(`online-swedish-banks`\) in the `force_payment_method` parameter.

        ```language-json
        "force_payment_method": "online-swedish-banks"
        ```

        As a result of using this option for the specified method, buttons for selecting all banks, supported by this method, are displayed.

    5.  *Selecting a bank among specific ones on Payment Page \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_swedish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifiers.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Sweden method code \(`online-swedish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true, \"banks_id\": [5121, 5151]}}",
        "force_payment_method": "online-swedish-banks"
        ```

        As a result of using this option, buttons for selecting specified banks that support working with the specified method are displayed in the payment form.

    6.  *Confirming redirection to the service of the specific bank on Payment Page \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`online_swedish_banks`\), and the value of which is the `split_banks` parameter set to include the value `true` and the `banks_id` array containing the target bank identifier.While specifying such an object, all nested `"` characters \(`U+0022`\) must be escaped using the preceding `\` characters \(`U+005C`\).
        -   Specify the selected Open Banking in Sweden method code \(`online-swedish-banks`\) in the `force_payment_method` parameter.
        ```language-json
        "payment_methods_options": "{\"online_swedish_banks\": {\"split_banks\": true, \"banks_id\": [5121]}}",
        "force_payment_method": "online-swedish-banks"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

3.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
4.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in Sweden method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(5\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "SEK",
   "customer_id": "customer1",
   "force_payment_method": "online-swedish-banks",
   "payment_methods_options": {"online_swedish_banks": {"split_banks": true, "banks_id": [5121, 5151]}},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in Sweden method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 SEK` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchase by using Gate {#en_pm_sweden_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in Sweden method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

Information about the data formats used to perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_sweden_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in Sweden method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request.
7.  The payment platform sends the callback with the redirection data to the web service.
8.  The customer is redirected to the provider service where payment instructions are displayed.
9.  The customer completes all required payment steps.
10. The purchase is processed on the side of the bank service.
11. The result information is displayed to the customer on the side of the bank service.
12. The customer is redirected to the web service.
13. The bank service sends information about the result to the provider service.
14. The provider service sends information about the result to the payment platform.
15. The payment platform sends the payment result callback to the web service.
16. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in Sweden method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_onh_2xj_wbc .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in Sweden method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/sweden/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `success`—URL for redirecting a customer after a processed purchase
        -   `decline`—URL for redirecting a customer after a declined purchase
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in Sweden method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URLs for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "SEK"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "SEK"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "success": "http://example.com/success",
      "decline": "http://example.com/decline",
      "return": "http://example.com/return"
 }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in Sweden method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in Sweden method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 SEK` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "ABC12345",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 10801,
        "payment": {
            "id": "ABC67890",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Swedish Banks",
            "sum": {
                "amount": 1000,
                "currency": "SEK"
            },
            "description": ""
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 1000,
                "currency": "SEK"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "SEK"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_sweden_dash_analysis}

To analyse information about payments made with the Open Banking in Sweden method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Open Banking in the UK {#pm_uk}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in pounds sterling via the banks of the United Kingdom.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_uk_overview}

An article about the internet banking method which belongs to the Open Banking group and allows processing payments in pounds sterling via the banks of the United Kingdom.

### Introduction {#section_vlw_5cc_wbc .section}

Open Banking in the UK an internet banking method which is based on the use of open banking protocolsand provides advanced capabilities for secure processing of customer information.This payment method belongs to the group of [Open Banking](pm_openbanking.md) methods and allows processing payments in pounds sterling via the banks of the United Kingdom.

The Ecommpay payment platform supports processing purchases made with the Open Banking in the UK payment method.You can also perform payouts by using [Local payouts to bank accounts in the UK](pm_bankpayout_uk.md) as a complementary payment method. Note that in this case payouts can be used to issue refunds to your customers.

This article provides information about working with the Open Banking in the UK method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[GB](references/en/countries/GB.md)|
|Payment currencies|[GBP](references/en/currencies/GBP.md)|
|Currency conversion|–|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|–|
|Chargebacks|–|
|Special considerations|-   taking into account the specifics of the providers and banks involved,in some cases customers must provide additional consent to make paymentsusing open banking protocols, which adds the appropriate steps to payment scenarios \(more details below\)
-   Payment Page supports different bank and method selection options\(more details [below](pm_uk.md#section_p5j_fgl_ggb)\)
-   when redirecting to services of providers and banks, the iframe element cannot be used; the pages of these services can be opened in a separate tab or in a modal window
-   when invoking Payment Page from mobile applications, it is worth considering the special aspects of working with browsers \(more details [below](pm_uk.md#section_bfg_sc1_qjc)\)
-   payment confirmation procedure may be used during purchase processing \(more details [below](pm_uk.md#section_yln_qjn_ftb)\)
-   performing payouts is possible with the use of the complementary payment method [Local payouts to bank accounts in the UK](pm_bankpayout_uk.md)

|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Open Banking in the UK method involves the merchant's web service, one of the interfacesand the Ecommpay payment platform, as well as the technical facilities of the bank and provider services.

![](images/pm/eng_ukob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Open Banking in the UK method: purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links for opening Payment Page\). At the same time, regardless of the interfaces used, amount limitations are applicable depending on the bank used for purchase processing.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Open Banking in the UK method, you need to redirect the customer to the provider service.

The customer payment scenario via Payment Page \(in the basic case where the customer chooses the method and bank and is redirected from the final page of the payment form to the web service\) looks like this.

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_1.svg "Proceeding to payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_2.svg "Selecting method")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_3.svg "Selecting bank")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_4.svg "Accepting terms and conditions")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_5.svg "Authentication")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_6.svg "Confirming payment")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_7.svg "Redirecting to the payment form")

![](images/pm/pp_scenario/en_pp_customer_scenario_uk_8.svg "Redirecting to the web service")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional capabilities are used \(for example when using payment links and using separate additional capabilities\), scenarios for performing operations can be adjusted accordingly

At the same time, the specifics of working with the Open Banking in the UK method include the necessity of selecting a bank for each payment. When Payment Page is used for payment processing, the customer usually selects a bank while already in the payment form. When Payment Page is opened with the method and bank preselectedas well as when payments are initiated through Gate, the bank must be selected on the side of the web service and the identifier of this bank must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_uk.md), ways of using bank identifiers—in the next subsection, [Supported banks](pm_uk.md#section_rqp_zdl_ggb).

### Supported banks {#section_rqp_zdl_ggb .section}

Payments through the Open Banking in the UK method are carried out through banks that support the work with this method. The following table lists the names and identifiers of banks supported by the method. Keep in mind that this list is presented for informational purposes.

|Bank|ID|
|----|--|
|Adam&Company Bank|3481|
|Allied Irish Bank|3491|
|Allied Irish Bank Business|3501|
|Bank Of Ireland|3511|
|Bank of Scotland|3521|
|Barclaycard|3531|
|Barclays|3541|
|Cashplus|3801|
|Chelsea Building Society|3811|
|Coutts|3551|
|Creation|3821|
|Cumberland|3561|
|Cynergy Bank|3831|
|Danske|3571|
|Danske Business|3581|
|First Direct|3591|
|First Trust Bank|3601|
|First Trust Bank Business|3611|
|Halifax|3621|
|HSBC|3631|
|HSBC Business|3641|
|Kleinwort Hambros|3651|
|Lloyds|3661|
|Marks & Spencer|3671|
|MBNA|3841|
|Mettle|3681|
|Mizuho|3691|
|Monzo|3851|
|Nationwide|3701|
|NatWest|3711|
|Revolut|3731|
|Royal Bank of Scotland|3721|
|Sainsbury's Bank|3861|
|Santander|3741|
|Starling|3871|
|Tesco|3751|
|Ulster Bank|3761|
|Ulster Bank Republic Of Ireland|3771|
|Vanquis|3781|
|Yorkshire Building Society|3791|

Since the list of available banks may change over time, it is recommended to send a POST request to the `/v2/info/banks/uk/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "EUR"
  }
}
```

```language-json
[
  {
    "id": 3491, // Bank ID
    "abbr": "AIB", // The service name of the bank in the platform (or its abbreviation)
    "name": "Allied Irish Bank", // International bank name
    "nativeName": "Allied Irish Bank", // Local (national or regional) bank name
    "currencies": [ // Array with information about the currencies supported by the bank
      {
        "id": 826, // Currency ID in the payment platform
        "alpha_3_4217": "GBP", // ISO-4217 alphabetic currency code
        "number_3_4217": "826", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 3541,
    "abbr": "BARCLAYS",
    "name": "Barclays",
    "nativeName": "Barclays",
    "currencies": [
      {
        "id": 826,
        "alpha_3_4217": "GBP",
        "number_3_4217": "826",
        "exponent": 2
      }
    ]
  },
  {
    "id": 3821,
    "abbr": "CREATION",
    "name": "Creation",
    "nativeName": "Creation",
    "currencies": [
      {
        "id": 826,
        "alpha_3_4217": "GBP",
        "number_3_4217": "826",
        "exponent": 2
      }
    ]
  }
]
]
```

If you have any questions about working with banks supported by the Open Banking in the UK methods, refer to your Ecommpay account manager.

### Payment confirmation procedure {#section_yln_qjn_ftb .section}

The workflow of processing purchases made with Open Banking in the UK method implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time\(in some cases up to seven or more days\). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result\(for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa\).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in the UK payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the `reversed` or `decline` status\(to make monitoring and analysing payments more convenient\).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1.  After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface\(Payment Page or the web service\) where they receive the information about payment processing.
2.  A number of actions are performed on the payment platform side:
    1.  The `sale` operation status is set to `success`.
    2.  A callback is sent to the web service about changes in the status of the operation.
    3.  The `payment confirmation` operation is formed.
    4.  The payment is assigned the `awaiting confirmation` status—until the provider receives information about the crediting of funds.
    5.  A callback is sent to the web service about changes in payment status.
3.  On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4.  On the payment platform side, the received information is processed, as a result of which the `payment confirmation` operation and the payment are assigned final statuses and the corresponding callbacks are sent to the web service.

The `payment confirmation` operation can have one of the following final statuses:

-   `success`—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to `success` and the final callback containing the payment information is sent to the web service.
-   `decline`—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period\(which is 7 days by default and can be changed by contacting Ecommpay technical support\).

    In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

    -   The `reversal` operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the `reversed` payment status.
    -   The payment status is set to `decline` and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API \(by receiving responses to payment status requests\), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gateis described in the corresponding sections of this article.If you have any additional questions regarding this procedure, contact the Ecommpay specialists.

## Purchases by using Payment Page {#en_pm_uk_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Open Banking in the UK method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.It should be taken into account that in the process of making a payment, the customer is redirected to the service of the provider or bank and in some cases, taking into account the specifics of the provider processing the payment, the customer may additionally be required to provide consent and certain information.To obtain such consent and information \(when required\), a corresponding [page](pm_uk.md#section_fgt_sdl_ggb) is displayed on Payment Page.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the Payment Page opening option\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_bank_uml_pp.svg "Purchase processing by using Payment Page")

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Open Banking in the UK method and one of the supported banks.
8.  The payment platform receives the request for processing the payment by using the selected method.
9.  The payment platform processes the received request. During this step, the need for additional consent of the customer and additional customer information is identified.
10. Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to Payment Page.
11. A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on Payment Page.
12. The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
13. The information provided by the customer is sent from Payment Page to the payment platform.
14. The information is processed on the payment platform side.
15. The data for redirecting the customer is sent from the payment platform to Payment Page.
16. The customer is redirected to the required to the provider and bank services where payment instructions are displayed.
17. The customer completes all required payment steps on the side of the used service.
18. The purchase is processed on the side of the bank service.
19. The result information is displayed to the customer on the side of the bank service.
20. The customer is redirected to Payment Page.
21. The bank service sends information about the result to the provider service.
22. The provider service sends the payment result information to the payment platform.
23. The payment platform sends the payment result callback to the web service.
24. The payment platform sends the result information to Payment Page.
25. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in the UK method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Special aspects of use in mobile applications {#section_bfg_sc1_qjc .section}

Generally, when a payment form is invoked from a mobile application, it opens in the application's built-in WebView browser. However, using WebView browsers can introduce problems in customer experience and reduce payment acceptance, as redirections from such browsers to and from banking applications may violate the security policies of providers and banks. In such cases, customers may encounter various errors, including the inability to complete required actions on the bank's side and the impossibility of redirection to the final page of the payment form to confirm the payment has been processed.

To avoid such issues, when using mobile applications on the web service side, it is recommended to ensure that the following conditions are met:

-   When invoking a payment form from a merchant application, it should open in the mobile device's default browser, not in a WebView browser.
-   When redirecting from a merchant application to provider and bank services, the mobile applications of these providers and banks installed on the customer's device should be used as the primary option. Only if such applications are unavailable or cannot be opened should browser redirection be used.

The methods for configuring this functionality depend on the specific operating system for which the given application is developed and the specifics of the application itself. However, the following examples can be used as a guide, designed for correct redirections to provider and bank applications and correct redirections from third-party services to the final page of the payment form.

``` {#codeblock_fd1_mxx_1hc}
webView.webViewClient = object : WebViewClient() {
                    override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?
                    ): Boolean {
                    val url = request?.url ?: return false
                    val intent = Intent(Intent.ACTION_VIEW, url)
                    return try {
                    startActivity(intent)
                    true
                    } catch (e: ActivityNotFoundException) {
                    false
                    }
                    }
                    }
```

``` {#codeblock_wn2_y3z_hjc}
    class Coordinator: NSObject, WKNavigationDelegate {
                    init(startHost: String?) {
                    self.startHost = startHost
                    }
                    func webView(_ webView: WKWebView,
                    decidePolicyFor navigationAction: WKNavigationAction,
                    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
                    guard let url = navigationAction.request.url else {
                    decisionHandler(.allow)
                    return
                    }
                    let newHost = url.host
                    if let startHost = startHost,
                    let newHost = newHost,
                    newHost != startHost {
                    UIApplication.shared.open(url)
                    decisionHandler(.cancel)
                    return
                    }
                    decisionHandler(.allow)
                    }
                    }
```

### Method and bank selection scenarios {#section_a1j_211_l3c .section}

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Open Banking in the UK method, additionally select one of the available banks. However, in some situations, other options for choosing a payment method and bank may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank selection page or limit the list of supported banks for a particular payment and display only target bank selection buttons to the customer. And from the web service side, you can control the use of such options.

The specific option of selecting the payment method and bank is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_uk.md#section_vn1_zfd_wbc)\). The following options are available.

![](images/universal/pm/splits/en_open_banking_pp_1.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_open_banking_pp_2.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_open_banking_pp_3.svg "3—Selecting bank among other methods of the specified group")

![](images/universal/pm/splits/en_open_banking_pp_4.svg "4—Selecting bank among all available banks")

![](images/universal/pm/splits/en_open_banking_pp_5.svg "5—Selecting bank among specific banks")

![](images/universal/pm/splits/en_open_banking_pp_6.svg "6—Redirection to the service of the specific bank")

-   1—when the payment form is opened, the tabs for selecting all available methods are displayed. Then the customer selects the method and one of the available banks \(this option is used by default\).
-   2—when the payment form is opened, the tabs for selecting methods of the target group are displayed. Then the customer selects the method and one of the available banks.
-   3—when the payment form is opened, the bank selection items for the target method are displayed. Then the customer selects one of the available banks.
-   4—when the payment form is opened, the tabs for selecting all available methods and the specified bank selection items for the target method are displayed. Then the customer selects one of the specified banks \(the choice is limited only to these banks\).
-   5—when the payment form is opened, the specified bank selection items for the target method are displayed. Then the customer selects one of the specified banks \(the choice is limited only to these banks\).
-   6—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

### Request format {#section_vn1_zfd_wbc .section}

There are several things you need to consider when using the Open Banking in the UK method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—alphabetic payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the first and last names of the customer in the parameters `customer_first_name` and `customer_last_name`. If any of these parameters are missing, the payment form may display input fields for entering the missing values\(details are available in [Submission of additional payment information](en_pp_clarification.md)\).

    Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number \(IBAN\) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment methods this number can only be specified by the customer separately and can't be used in requests.

3.  It is recommended to specify in the request the `merchant_return_url` parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing.
4.  The bank selection options can be defined as follows:

    1.  *Selecting the method among all available methods and then selecting one of the available banks \(1\)*—the default option, applied if the `force_payment_method`, `force_payment_group` and `payment_methods_options` parameters, mentioned in subpoints *2–6* are not used.

        As a result of using this option the tabs for selecting all available methods are displayed, and, after the method is selected, the available bank selection items are displayed.

    2.  *Selecting the method among other methods of the target group and then selecting one of the available banks \(2\)*—this option requires to specify the `openbanking` group code in the `force_payment_group` parameter

        ``` {#codeblock_zgy_zj5_k3c .language-json}
        "force_payment_group": "openbanking"
        ```

        As a result of using this option the tabs for selecting the methods of the target group are displayed, and, after the method is selected, the available bank selection items are displayed.

    3.  *Selecting one of the banks available for the target method \(3\)*—for this option specify the method code of the target method \(`uk`\) in the `force_payment_method` parameter.

        ``` {#codeblock_uqr_jk5_k3c .language-json}
        "force_payment_method": "uk"
        ```

        As a result of using this option the available bank selection items supported by this method are displayed.

    4.  *Selecting a method among all available methods and selecting one of the specified banks \(4\)*—for this option, you need to specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifiers.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).

        ``` {#codeblock_t1g_dgc_h3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}"
        ```

        As a result of using this option the tabs for selecting all available are displayed, and, after the method is selected, the specified bank selection items are displayed \(taking into account which of these banks are available at the time of opening the payment form\) .

    5.  *Selecting one of the banks specified for the target method \(5\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifiers.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).
        -   Specify the selected Open Banking in the UK method code \(`uk`\) in the `force_payment_method` parameter.
        ``` {#codeblock_jpm_5k5_k3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}",
        "force_payment_method": "uk"
        ```

        As a result of using this option the specified bank selection items supported by this method are displayed \(taking into account which of these banks are available at the time of opening the payment form\).

    6.  *Confirming redirection to the service of the specified bank \(6\)*—this option requires the following:

        -   Specify a string object in the value of the `payment_methods_options` parameter, the name of which is the method indicator \(`uk`\), and the value of which is the `banks_id` array containing the specified bank identifier.While specifying such an object, all nested `"` characters \(quotation mark, U+0022\) must be preceded by the `\` escape character \(reverse solidus, U+005C\).
        -   Specify the selected Open Banking in the UK method code \(`uk`\) in the `force_payment_method` parameter.
        ``` {#codeblock_jbz_4l5_k3c .language-json}
        "payment_methods_options": "{\"uk\": \"banks_id\": [3541]}}",
        "force_payment_method": "uk"
        ```

        As a result of using this option, when opening a payment form, a confirmation page is displayed in it to redirect to the service of the specified bank.

5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Open Banking in the UK method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), URL for customer redirection, customer identifier and signature, as well as various optional parameters.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a method among all available methods and selecting one of the specified banks \(4\), the request for opening Payment Page may contain additional data.

``` {#codeblock_nsr_411_l3c .language-json}
{
 // required parameters  
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
 // optional parameters
   ...
   "payment_methods_options": "{\"uk\": \"banks_id\": [3541, 3821]}}"
 // signature
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Open Banking in the UK method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 GBP` purchase made in the `239` project.

```language-json
{
   "project_id":239,
   "payment":{
      "id":"ID_461239",
      "type":"purchase",
      "status":"success",
      "date":"2020-06-15T14:55:23+0000",
      "method":"UK banks",
      "sum":{
         "amount":1000,
         "currency":"GBP"
      },
      "description":"ID_461239"
   },
   "customer":{
      "id":"1"
   },
   "operation":{
      "id":59043000050811,
      "type":"sale",
      "status":"success",
      "date":"2020-06-15T14:55:23+0000",
      "created_date":"2020-06-15T14:51:35+0000",
      "request_id":"929c6911448765aedaf4df...79aa8d4adb6b78dc5-00059044",
      "sum_initial":{
         "amount":1000,
         "currency":"GBP"
      },
      "sum_converted":{
         "amount":1000,
         "currency":"GBP"
      },
      "code":"0",
      "message":"Success",
      "provider":{
         "id":2901,
         "payment_id":"385dc36c-7fac-4bf5-a0e6-6a16ebcc1962",
         "auth_code":"",
         "endpoint_id":"Halifax",
         "date":"2020-06-15T14:51:36+0000"
      }
   },
   "signature":"+KDWbziHMNDBSd2Y04Cc...xRb55AnjtvrZc4XgG6iXkJyLHPa3ZbYw=="
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
   "customer":{
      "id":"1"
   },
   "project_id":10801,
   "payment":{
      "id":"ID_542650",
      "type":"purchase",
      "status":"decline",
      "date":"2020-06-15T11:46:42+0000",
      "method":"UK banks",
      "sum":{
         "amount":100,
         "currency":"GBP"
      },
      "description":"ID_542650"
   },
   "operation":{
      "id":58778000050861,
      "type":"sale",
      "status":"decline",
      "date":"2020-06-15T11:46:42+0000",
      "created_date":"2020-06-15T11:36:39+0000",
      "request_id":"e6cb17dd0699001b813a0...6753e4dca478c7eb6-00058779",
      "sum_initial":{
         "amount":100,
         "currency":"GBP"
      },
      "sum_converted":{
         "amount":100,
         "currency":"GBP"
      },
      "code":"20000",
      "message":"General decline",
      "provider":{
         "id":2901,
         "payment_id":"BARCLAYS-P-10000000420474",
         "auth_code":"",
         "endpoint_id":"Barclays",
         "date":"2020-06-15T11:36:41+0000"
      }
   },
   "signature":"kC6wuur3Q2Dswd7A6R+C...1EaupyvFHs6q/aZ7lW17cUuFhXjHoVWbrTJqQ=="
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Quickstart](en_pp_quickstart.md) and[Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_uk_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using one of the Open Banking in the UK method, the merchant's web service is required to do the following:

1.  Send a requestwith all the required parameters and signature to the Ecommpay URL.
2.  Receive a callback from the payment platform about the need to obtain consent and, if relevant, additional information from the customer.
3.  Obtain consent and additional information from the customer \(if requested\).
4.  Provide information about the customer consent and the provided information\(if requested\) in a request to the payment platform.
5.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
6.  Receive the final callback from the payment platform.

Information about the data formats used to obtain customer consent and perform customer redirection is provided further in this section.

**Warning:** When redirecting to services of providers and banks, the iframe element cannot be used. The pages of these services can be opened in a separate tab or in a modal window\(regardless of the specifics of the web service\).

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_openbanking_uml_gate.svg)

1.  A customer initiates a purchase by using the Open Banking in the UK method and one of the supported banks in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform processes the received request, identifying the need to obtain additional customer consent and additional information about the customer.
7.  Information about the need for additional consent of the customer and additional information \(if needed\) is sent from the payment platform to the web service.
8.  A page with information about the need for customer's consent and additional information \(if needed\) is displayed to the customer on the web service side.
9.  The customer gives their consent and provides the necessary information \(if requested\) and confirms purchase processing.
10. The information provided by the customer is sent from the web service to the payment platform.
11. The request for continuation of payment processing with regard to information provided by the customer is sent to the payment platform.
12. The information is processed on the payment platform side.
13. The payment platform sends the callback with the redirection data to the web service.
14. The customer is redirected to the provider service where payment instructions are displayed.
15. The customer completes all required payment steps.
16. The purchase is processed on the side of the bank service.
17. The result information is displayed to the customer on the side of the bank service.
18. The customer is redirected to the web service.
19. The bank service sends information about the result to the provider service.
20. The provider service sends information about the result to the payment platform.
21. The payment platform sends the payment result callback to the web service.
22. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Open Banking in the UK method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Open Banking in the UK method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/uk/sale` endpoint, which belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—alphabetic payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
    -   Object `account`—customer account information:
        -   `bank_id`—bank identifier
    -   Object `return_url`—URLs for redirecting the customer to the web service:
        -   `return`—URL for redirecting the customer to the web servicewhen working with the service of a provider or bank in cases where the customer refuses to make a payment.
3.  Additionally, it is recommended to specify the first and last names of the customer in the `first_name` and `last_name` parameters of the `customer` object following objects and parameters. If any of these parameters are missing, the payment platform may send the list of missing parameters in a callback requesting additional information submission.

    In addition, in some cases, taking into account the specifics of the bank used, the customer may be required to specify the International Bank Account Number \(IBAN\) on the web service side, while in other cases this number is specified by the customer on the provider side or bank side. At the same time, due to the specifics of the group’s methods, even if the customer account number is indicated in the initial request, it is not taken into account during the initial processing of this request and can be requested separately, by specifying the `account` object including the `number` parameter in a callback requesting additional information submission \(along with indicating other relevant parameters if they were not specified\).

    Details about providing additional parameters are available in the [Submission of additional payment information](en_Gate_Clarification.md) article.

4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Open Banking in the UK method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and IP address, bank identifier, URL for redirection and signature, as well as various optional parameters.

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "GBP"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

```language-json
{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "GBP"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
```

### Formats of the data for obtaining customer's consent {#section_icz_bjm_ppb .section}

When using the Open Banking in the UK payment method it is necessary to obtain additional consent from the customer and, if relevant, additional information about the customer. In such cases an intermediate callback containing the `clarification_fields` object is sent from the payment platform to the web service each time.The nested objects of that object describe the specified objects and parameters necessary to process the payment.

The structure of each object included in the `clarification_fields` object includes:

-   `type` and `description` parameters—information about the object type and its description
-   `properties` parameter—information about the parameters included in the object
-   `required` array—list of the required parameters
-   `errors` array—information on the reasons for requesting the listed parameters

The `properties` object and the `required` array are specified according to the [JSON Schema](https://json-schema.org/specification.html) specification, while the `errors` array contains the `property`, `message` and `constraint` parameters which specify the names, relevant messages and descriptions of reasons.

The text which is required to be displayed to the customer is specified in the `clarification_fields.customer.properties.psu_consent_text.default` parameter.

In general, information about the need to obtain the customer consent and additional information may look like this.

```language-json
{
  "clarification_fields": {
    "customer": {
      "type": "object",
      "description": "Object that contains customer details",
      "properties": {
        "psu_consent": {
          "type": "string",
          "description": "Need to request the users consent to make a payment"
        },
        "psu_consent_text": {
          "type": "string",
          "description": "The PSU consent text to be displayed on Payment Page",
          "default": "This consent text with possibly links to some resources here."
        },
        "first_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 255,
          "description": "Customer last name"
        }
      },
      "required": [
        "psu_consent",
        "psu_consent_text",
        "first_name",
        "last_name"
      ],
      "errors": [
        {
          "property": "customer.psu_consent",
          "message": "The property psu_consent is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.psu_consent_text",
          "message": "The property psu_consent_text is required for the clarification request",
          "constraint": "required"
        },
        {
          "property": "customer.first_name",
          "message": "The property first_name is required",
          "constraint": "required"
        },
        {
          "property": "customer.last_name",
          "message": "The property last_name is required",
          "constraint": "required"
        }
      ]
    },
    "account": {
      "type": "object",
      "description": "Object that contains the details of the customer's bank account for payment performing",
      "properties": {
        "number": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's account number"
        },
        "bank_code": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "Customer's bank code"
        }
      },
      "required": [
        "number",
        "bank_code"
      ],
      "errors": [
        {
          "property": "account.number",
          "message": "The property number is required",
          "constraint": "required"
        },
        {
          "property": "account.bank_code",
          "message": "The property bank_code is required",
          "constraint": "required"
        }
      ]
    }
  }
}
```

After obtaining the customer consent and the requested information on the web service side, it is necessary to send a POST request to continue the payment. Such a request must be sent to the [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) endpoint and must contain the following objects and parameters:

-   `general`—object that contains general request identification information:
    -   `project_id`—the project IDwhich is relevant to the payment
    -   `payment_id`—payment IDwhich is relevant to the data being sent
    -   `signature`—request signaturegenerated after all of the required parameters are specified. For more information about signature generation, see [Signature generation and verification](en_platform_signature.md)
-   `additional_data`—object that contains information about customer's consent for purchase processing \(and additional information, if needed\):
    -   `customer`—object that contains customer information:
        -   `psu_consent`—information about obtainment of customer's consent for purchase processing. If the customer granted their consent for purchase processing, the value for this parameter must be `1`.

            If the customer has not provided consent, then the request to continue the payment may not be sent. In such cases, after30 minutes \(or another time, if this was configured for the project used\) the payment is declined.When sending requests with a `psu_consent` parameter value other than `1`, the customer's consent is requested again.

        -   `psu_consent_text`—the text of the request for customer's consent for purchase processing displayed to the customer. The text specified as the value of this parameter must be exactly the same as the text received in the callback informing the merchant about the necessity of obtaining customer's consent.If the specified text is different, the customer's consent is requested again.
    -   `<additional_parameters>`—parameters which specify the additional requested information about the customer.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer information \(if needed\) and signature, as shown in the following example:

```language-json
{
  "general": {
    "project_id": 10571,
    "payment_id": "1234567890",
    "signature": "=== signature ==="
  },
  "additional_data": {
    "customer": {
      "psu_consent": "1",
      "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
      "first_name": "Firstname",
      "last_name": "Lastname"
    },
    "account": {
      "number": "AB123456789"
    }
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Open Banking in the UK method requires redirection of customers from the merchant's web service to the service of the provider or bank. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body\(taking into account the specifics of a particular method, this object may contain various information\)
-   `method`—parameter specifying the HTTP method for sending the request\(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Open Banking in the UK method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 GBP` purchase made in the `239` project.

```language-json
{
   "project_id":239,
   "payment":{
      "id":"ID_461239",
      "type":"purchase",
      "status":"success",
      "date":"2020-06-15T14:55:23+0000",
      "method":"UK banks",
      "sum":{
         "amount":1000,
         "currency":"GBP"
      },
      "description":"ID_461239"
   },
   "customer":{
      "id":"1"
   },
   "operation":{
      "id":59043000050811,
      "type":"sale",
      "status":"success",
      "date":"2020-06-15T14:55:23+0000",
      "created_date":"2020-06-15T14:51:35+0000",
      "request_id":"929c6911448765aedaf4df...79aa8d4adb6b78dc5-00059044",
      "sum_initial":{
         "amount":1000,
         "currency":"GBP"
      },
      "sum_converted":{
         "amount":1000,
         "currency":"GBP"
      },
      "code":"0",
      "message":"Success",
      "provider":{
         "id":2901,
         "payment_id":"385dc36c-7fac-4bf5-a0e6-6a16ebcc1962",
         "auth_code":"",
         "endpoint_id":"Halifax",
         "date":"2020-06-15T14:51:36+0000"
      }
   },
   "signature":"+KDWbziHMNDBSd2Y04Cc...xRb55AnjtvrZc4XgG6iXkJyLHPa3ZbYw=="
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
   "customer":{
      "id":"1"
   },
   "project_id":10801,
   "payment":{
      "id":"ID_542650",
      "type":"purchase",
      "status":"decline",
      "date":"2020-06-15T11:46:42+0000",
      "method":"UK banks",
      "sum":{
         "amount":100,
         "currency":"GBP"
      },
      "description":"ID_542650"
   },
   "operation":{
      "id":58778000050861,
      "type":"sale",
      "status":"decline",
      "date":"2020-06-15T11:46:42+0000",
      "created_date":"2020-06-15T11:36:39+0000",
      "request_id":"e6cb17dd0699001b813a0...6753e4dca478c7eb6-00058779",
      "sum_initial":{
         "amount":100,
         "currency":"GBP"
      },
      "sum_converted":{
         "amount":100,
         "currency":"GBP"
      },
      "code":"20000",
      "message":"General decline",
      "provider":{
         "id":2901,
         "payment_id":"BARCLAYS-P-10000000420474",
         "auth_code":"",
         "endpoint_id":"Barclays",
         "date":"2020-06-15T11:36:41+0000"
      }
   },
   "signature":"kC6wuur3Q2Dswd7A6R+C...1EaupyvFHs6q/aZ7lW17cUuFhXjHoVWbrTJqQ=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Quickstart](en_gate_quickstart.md) and [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_uk_dash_analysis}

To analyse information about payments made with the Open Banking in the UK method, as well as other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation\([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Payouts to bank accounts in SEPA {#pm_bankpayout_sepa}

An article about the payment method which allows you to process payments in euros by using bank accounts in SEPA countries and supports payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_bankpayout_sepa_overview}

An article about the payment method which allows you to process payments in euros by using bank accounts in SEPA countries and supports payouts.

### Introduction {#section_t5z_rlg_ytb .section}

Payouts to bank accounts in SEPA is a payment method which allows you to process payments in euros by using bank accounts in SEPA countries.This method supports payouts. You can also perform purchases by using the Open Banking complementary payment methods.

This article provides information about working with the Payouts to bank accounts in SEPA method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[AD](references/en/countries/AD.md), [AT](references/en/countries/AT.md), [BE](references/en/countries/BE.md), [BG](references/en/countries/BG.md), [HR](references/en/countries/HR.md), [CY](references/en/countries/CY.md), [CZ](references/en/countries/CZ.md), [DK](references/en/countries/DK.md), [EE](references/en/countries/EE.md), [FI](references/en/countries/FI.md), [FR](references/en/countries/FR.md), [DE](references/en/countries/DE.md), [GR](references/en/countries/GR.md), [HU](references/en/countries/HU.md), [IS](references/en/countries/IS.md), [IE](references/en/countries/IE.md), [IT](references/en/countries/IT.md), [LV](references/en/countries/LV.md), [LI](references/en/countries/LI.md), [LT](references/en/countries/LT.md), [LU](references/en/countries/LU.md), [MT](references/en/countries/MT.md), [MC](references/en/countries/MC.md), [NL](references/en/countries/NL.md), [NO](references/en/countries/NO.md), [PL](references/en/countries/PL.md), [PT](references/en/countries/PT.md), [RO](references/en/countries/RO.md), [SM](references/en/countries/SM.md), [SK](references/en/countries/SK.md), [SI](references/en/countries/SI.md), [ES](references/en/countries/ES.md), [SE](references/en/countries/SE.md), [CH](references/en/countries/CH.md), [GB](references/en/countries/GB.md), [VA](references/en/countries/VA.md)|
|Payment currencies|[EUR](references/en/currencies/EUR.md)|
|Currency conversion|–|
|One-time purchases|–|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Special considerations|-   this method can be used in all SEPA countries as well as in individual ones, refer to your Ecommpay key account manager for more information
-   using this method requires applying the [Verification of Payee](en_verification_of_payee.md) procedure
-   performing purchases is possible with the use of the complementary [Open Banking](pm_openbanking.md) payment methods

|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Payouts to bank accounts in SEPA method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_bankpayout_sepa_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Payouts to bank accounts in SEPA method. Payouts can be processed by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [EUR](references/en/currencies/EUR.md)¹|Times²|
|minimum|maximum|basic|threshold|
|--|------------------------------------------------|------|
|-------|-------|-----|---------|
|Payouts|\*|\*|\*|\*|

**Note:**

1.  Amount limits and processing times depend on banks.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To process a payout by using the Payouts to bank accounts in SEPA method, you need to notify the customer via the web service.

![](images/pm/eng_bankpayout_sepa_interfaces_gate_payout.svg "Payout by using Gate")

## Payouts by using Gate {#en_pm_bankpayout_sepa_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the Payouts to bank accounts in SEPA method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/eng_bankpayout_sepa_uml_gate_payout.svg)

1.  A customer initiates a payout by using the Payouts to bank accounts in SEPA method in the web service.
2.  The web service sends the request for processing the payout by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The payout is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the payout result information from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the Payouts to bank accounts in SEPA method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the Payouts to bank accounts in SEPA method:

1.  To initiate each payout send a separate POST request to the `/v2/payment/bank-transfer/world/payout` endpoint. This endpoint belongs to the group [/v2/payment/bank-transfer/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/bank-transfer/post-v2-payment-bank-transfer-payment-method-payout).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
        -   `description`—payout description
    -   Object `customer`—recipient information:
        -   `id`—recipient identifierunique within the project
        -   `ip_address`—recipient IP addressrelevant for the initiated payout
        -   `first_name`—full name of the recipient or name of the company
    -   Object `account`—recipient account information:
        -   `number`—recipient bank account number \(IBAN\)
3.  When processing the Verification of Payee results on the web service side\([details](en_verification_of_payee.md)\) it is required to specify the identifier of the applicable verification in the `id` parameter of the `vop` object.
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the Payouts to bank accounts in SEPA method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), payment description, recipient identifier, IP address and name, Verification of Payee identifier \(if required\), as well as account number and signature.

``` {#codeblock_l32_psg_w3c .language-json}
 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9XAaq7/Jkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "customer": {
     "id": "customer1",
     "ip_address": "192.0.2.0",
     "first_name": "John Doe"
  },
   "account": {
     "number": "FI1410093000123458"
  },
   "payment": {
     "amount": 10000,
     "currency": "EUR",
     "description": "test payout"
  },
   "vop": {
     "id": 12345
}
```

``` {#codeblock_opg_psg_w3c .language-json}
 {
  "general": {
    "project_id": 3027,
    "payment_id": "payout1",
    "signature": "M1vT4q9XAaq7/Jkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
   "customer": {
     "id": "customer1",
     "ip_address": "192.0.2.0",
     "first_name": "John Doe"
  },
   "account": {
     "number": "FI1410093000123458"
  },
   "payment": {
     "amount": 10000,
     "currency": "EUR",
     "description": "test payout"
  },
   "vop": {
     "id": 12345
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The Payouts to bank accounts in SEPA method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `211.00 EUR` payout made in the `4990` project.

```language-json
{
        "project_id": 4990,
        "payment": {
            "id": "53923_33600681",
            "type": "payout",
            "status": "success",
            "date": "2021-02-22T13:39:45+0000",
            "method": "world",
            "sum": {
                "amount": 21100,
                "currency": "EUR"
            },
            "description": "test description"
        },
        "account": {
            "number": "123456"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 6325000000075,
            "type": "payout",
            "status": "success",
            "date": "2021-02-22T13:39:45+0000",
            "created_date": "2021-02-22T13:39:23+0000",
            "request_id": "9a9c4985044f5927dae77daac4b8e488b2-00006326",
            "sum_initial": {
                "amount": 21100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 21100,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2945,
                "payment_id": "j29vEXRSAd",
                "auth_code": ""
            }
        },
        "signature": "7bxR3Ssoemv3o5mpabmg529+/NkpdYPLMN1sBw=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 4990,
        "payment": {
            "id": "21571027",
            "type": "payout",
            "status": "decline",
            "date": "2021-02-22T13:30:44+0000",
            "method": "world",
            "sum": {
                "amount": 30400,
                "currency": "EUR"
            },
            "description": "test description"
        },
        "account": {
            "number": "1234567"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 9698000000069,
            "type": "payout",
            "status": "decline",
            "date": "2021-02-22T13:30:44+0000",
            "created_date": "2021-02-22T13:30:23+0000",
            "request_id": "3c6027f04491e63df2d67f755e3b45f64-00009699",
            "sum_initial": {
                "amount": 30400,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 30400,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2945,
                "payment_id": "j29KmZH29J",
                "auth_code": ""
            }
        },
        "signature": "KTCGrXiG/cQzANBw2s730kE6toB+EDa619tqB9qQeg=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the Payouts to bank accounts in SEPA method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_bankpayout_sepa.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_bankpayout_sepa_dash_analysis}

To analyse information about payments made with the Payouts to bank accounts in SEPA method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Peru Online Banking {#pm_peru_ob}

An article about the payment method which allows you to process payments in Peruvian sols and US dollars by using bank accounts in Peru and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_peru_ob_overview}

An article about the payment method which allows you to process payments in Peruvian sols and US dollars by using bank accounts in Peru and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Peru Online Banking is a payment method which allows you to process payments in Peruvian sols and US dollars by using bank accounts in Peru.This method supports purchases and refunds.

This article provides information about working with the Peru Online Banking method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|bank accounts|
|Countries and regions|[PE](references/en/countries/PE.md)|
|Payment currencies|[PEN](references/en/currencies/PEN.md), [USD](references/en/currencies/USD.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|full and partial refund is possible within 90 calendar days after the purchase|
|Onboarding and access fee|refer to your Ecommpay account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Peru Online Banking method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/en_peru_ob_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Peru Online Banking method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts¹|Times²|
|minimum|maximum|base|threshold|
|--|--------|------|
|-------|-------|----|---------|
|Purchases|\*|\*|3 minutes|36 hours|
|Refunds|\*|\*|5 minutes|36 hours|

**Note:**

1.  Minimum and maximum payment amounts depend on the banks that the customer can select after redirection to the provider service. The bank will not be available for selection if the payment amount is outside the limits set by the bank.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Peru Online Banking method, you need to redirect the customer to the provider service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/en_peru_ob_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_peru_ob_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/en_peru_ob_interfaces_gate_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_peru_ob_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Peru Online Banking method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_peru_ob_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Peru Online Banking method.
8.  The payment platform receives the request for processing the payment by using the Peru Online Banking method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps on the provider service side.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Peru Online Banking method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Peru Online Banking method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  It is also required to specify the first and last name and the email of the customer in the parameters `customer_first_name`, `customer_last_name` and `customer_email`. To avoid errors during payment processing it is recommended to set the value length of 3 to 100 characters in the parameters `customer_first_name` and `customer_last_name`.
3.  If you need to have the payment form displayed with the Peru Online Banking method selected, set the `force_payment_method` parameter to `online-peru-banks`.
4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Peru Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature, as well as possible additional parameters.

``` {#codeblock_gdb_pts_w2c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_v31_zqx_hgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Peru Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "peru",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },

        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "peru",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_peru_ob_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Peru Online Banking method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the provider service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_peru_ob_uml_gate.svg)

1.  A customer initiates a purchase by using the Peru Online Banking method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps on the provider service side.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Peru Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Peru Online Banking method:

1.  To initiate each purchase, send a separate POST request to the `/v2/payment/banks/peru/sale` endpoint. This endpoint belongs to the group [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
3.  Additionally, it is required to specify the following objects and parameters:
    -   Object `customer`—customer information:
        -   `first_name`— customer first name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `last_name`—customer last name \(to avoid errors during payment processing it is recommended to set the following value length—from 3 to 100 characters\)
        -   `email`—customer email address
4.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Peru Online Banking method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, signature, as well as possible additional parameters.

``` {#codeblock_wwl_c5s_w2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

``` {#codeblock_fp4_1tw_x2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Peru Online Banking method requires redirection of customers from the merchant's web service to the provider service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Final callback format {#section_dpx_2hl_ggb .section}

The Peru Online Banking method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` purchase made by the `1` customer in the `123456` project.

``` {#codeblock_hdb_pts_w2c .language-json}
{
        "project_id": 123456,
        "payment": {
            "id": "24113462",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "method": "peru",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "Test sale TEST_PAYMENT_280425_1"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 3096000012631,
            "type": "sale",
            "status": "success",
            "date": "2025-04-28T12:35:34+0000",
            "created_date": "2025-04-28T12:20:31+0000",
            "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-3c6a0ba271207cb817a0c683cf36e7a33ff2d9b4-00003097",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21463,
                "payment_id": "140347770236",
                "auth_code": ""
            }
        },
        "signature": "vZ8+G9mQFv1lfth8yxvoqn15Q0dM2S+iD5RNQvCeMsG/PmpHnKhIw+5XaZ+Fsd6z/xfTIf6Kl+WjRkHKXE29nw=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

``` {#codeblock_idb_pts_w2c .language-json}
{
        "customer": {
            "id": "1"
        },
        "project_id": 59051,
        "payment": {
            "id": "TEST_PAYMENT_398957",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "method": "peru",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "TEST_PAYMENT_398957"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1139,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16353,
                "payment_id": "140347102975",
                "auth_code": ""
            },
            "id": 5031180010141499,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-21T01:15:28+0000",
            "created_date": "2025-04-14T12:15:04+0000",
            "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181"
        },
        "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases with immediate debiting of funds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Gate {#en_pm_peru_ob_gate_refund}

### General information {#section_lsx_3jl_ggb .section}

To perform a refund through Gate by using the Peru Online Banking method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of refund performing are provided below.

![](images/pm/en_peru_ob_uml_gate_refund.svg)

1.  A customer initiates a refund.
2.  The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The refund is processed on the side of the provider service.
8.  The provider service sends the result notification to the payment platform.
9.  The payment platform sends the result callback to the web service.
10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Peru Online Banking method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending refund requests by using the Peru Online Banking method:

1.  To initiate each refund, send a separate POST request to the [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general refund information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—identifier of the payment that needs to be refunded
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—refund information:
        -   `description`—refund description or comment
        -   `amount`—refund amount in the smallest currency unit \(required for a partial refund\)
        -   `currency`—refund currency codein the ISO-4217 alpha-3 format \(required for a partial refund\)
    -   Object `customer`—customer information:
        -   `ip_address`—customer IP addressrelevant for the initiated refund
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Peru Online Banking method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

``` {#codeblock_fqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

``` {#codeblock_gqj_w1d_t2c .language-json}
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 10000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Peru Online Banking method uses the standard format for callbacks to deliver refund results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100.00 USD` full refund made by the `1` customer in the `433772` project.

``` {#codeblock_pmy_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_265608",
        "type": "purchase",
        "status": "refunded",
        "date": "2025-06-26T06:48:37+0000",
        "method": "peru",
        "sum": {
            "amount": 0,
            "currency": "USD"
        },
        "description": "TEST_PAYMENT_265608"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 7373000014760,
        "type": "refund",
        "status": "success",
        "date": "2025-06-26T06:48:37+0000",
        "created_date": "2025-06-26T06:48:34+0000",
        "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1903,
            "payment_id": "1750920516487",
            "auth_code": ""
        }
    },
    "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ=="
}
```

The following is the example of a callback with information about a declined refund.

``` {#codeblock_iqj_w1d_t2c .language-json}
{
    "project_id": 433772,
    "payment": {
        "id": "test_29.04.25_3",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-29T11:36:34+0000",
        "method": "peru",
        "sum": {
            "amount": 200000,
            "currency": "PEN"
        },
        "description": "test_29.04.25_3"
    },
    "customer": {
        "id": "1"
    },
    "operation": {
        "id": 5557000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-29T11:22:44+0000",
        "created_date": "2024-12-29T11:22:44+0000",
        "request_id": "c717b3de84d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 100000,
            "currency": "PEN"
        },
        "sum_converted": {
            "amount": 28200,
            "currency": "USD"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21514,
            "payment_id": "1418092457",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing refunds via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Purchase refunds](en_Gate_Refund.md)—about performing of refunds by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Refunds by using Dashboard {#en_pm_dash_refund}

When working with Dashboard, you can perform *single* and *mass* refundsby using the Peru Online Banking method.

-   To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
-   To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section. The refund parameters must comply with the [requirements](pm_peru_ob.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More informationabout performing refunds by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_peru_ob_dash_analysis}

To analyse information about payments made with the Peru Online Banking method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Philippines Over the Counter & ATM {#pm_philippines_atm}

An article about the payment method which allows you to process payments in Philippine pesos by using payment cards and cash in the Philippines and supports purchases.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_philippines_atm_overview}

An article about the payment method which allows you to process payments in Philippine pesos by using payment cards and cash in the Philippines and supports purchases.

### Introduction {#section_t5z_rlg_ytb .section}

Philippines Over the Counter & ATM is a payment method which allows you to process payments in Philippine pesos by using payment cards and cash in the Philippines.This method supports purchases.

This article provides information about working with the Philippines Over the Counter & ATM method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|-   cash
-   payments cards

|
|Countries and regions|[PH](references/en/countries/PH.md)|
|Payment currencies|[PHP](references/en/currencies/PHP.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|-   additional parameters can be specified while generating Payment Page
-   full and partial refunds are available only directly from the provider service

|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/atm-philippines/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Philippines Over the Counter & ATM method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

![](images/pm/eng_philippinesover_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Philippines Over the Counter & ATM method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

| |Amounts, [PHP](references/en/currencies/PHP.md)¹|Times²|
|minimum|maximum|basic|threshold|
|--|------------------------------------------------|------|
|-------|-------|-----|---------|
|Purchases|1.00|1,000,000.00|1 day|2 days|
|Refunds|\*|\*|\*|\*|

\* To request a full or partial refund, customer needs to submit [the online refund form](https://www.dragonpay.ph/refund).

**Note:**

1.  Refer to your Ecommpay key account manager for more information.
2.  The base and threshold times are defined as follows:
    -   *The base time* is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour. Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status \([details](en_Gate_payment_status_request.md)\).
    -   *The threshold time* is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the `decline` status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Philippines Over the Counter & ATM method, you need to redirect the customer to the provider service.

![](images/pm/eng_philippinesover_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_philippinesover_interfaces_gate.svg "Purchase by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

At the same time, the specifics of working with the method include the necessity of selecting a bank branch or ATM chain for each payment. When Payment Page is used for payment processing, the customer usually selects a bank branch or ATM chain while already in the payment form. When Payment Page is opened with the method and bank branch or ATM chain preselected as well as when payments are initiated through Gate, the bank branch or ATM chain must be selected on the side of the web service and the identifier of this branch or chain must be specified in requests. Possible options for bank selection when working with Payment Page are described in [Purchases by using Payment Page](pm_philippines_atm.md), ways of using bank identifiers—in the next subsection, [Supported bank branches and ATM chains](pm_philippines_atm.md#section_rqp_zdl_ggb).

### Supported bank branches and ATM chains {#section_rqp_zdl_ggb .section}

The following table lists the names and identifiers of bank branches and ATM chains supported by the Philippines Over the Counter & ATM method. Keep in mind that this list is presented for informational purposes.

|ATMs and physical bank branches|ID|
|-------------------------------|--|
|AUB Online/Cash Payment|485|
|Banco de Oro ATM|2331|
|Banco de Oro Cash Payment|2341|
|BDO Cash Deposit w/ Ref|2351|
|BDO Network Bank \(formerly ONB\) Cash Dep|2361|
|BPI Over-the-Counter|2371|
|BPI Bills Payment|2381|
|Chinabank ATM/Cash Payment|2391|
|EastWest Online/Cash Payment|2411|
|EastWest Bank Over-the-counter|2401|
|Landbank Cash Payment|2421|
|Metrobank Cash Payment|2441|
|Metrobank Over-the-Counter|2431|
|PNB Cash Payment|2471|
|PNB e-Banking Bills Payment|2301|
|PNB Over-the-Counter|2461|
|PNB Remit|2451|
|RCBC Cash Payment|2481|
|RCBC Savings Cash Payment|2511|
|RCBC Over-the-Counter/ATM|2491|
|RobinsonsBank Over-the-Counter|2501|
|SB Regular OTC|2541|
|Security Bank ATM|2521|
|Security Bank Cash Payment|2531|
|UCPB ATM/Cash Payment|2571|
|UCPB Over-the-Counter/ATM|2581|
|Unionbank ATM|2561|
|Unionbank Cash Payment|2551|

Since the list of available bank branches and ATM chains may change over time, it is recommended to send a POST request to the `/v2/info/banks/atm/philippines/sale/list` endpoint to obtain up-to-date information. This endpoint belongs to the [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) group of the Gate API.The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

```language-json
{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP"
  }
}
```

```language-json
[
  {
    "id": 2331, // Bank branch or ATM chain ID
    "abbr": "BDOA", // Bank branch or ATM chain abbreviation (for internal use)
    "name": "Banco de Oro ATM", // International bank branch or ATM chain name
    "nativeName": "Banco de Oro ATM", // Local bank branch or ATM chain name
    "currencies": [ // Array with information about the currencies supported by the bank branch or ATM chain
      {
        "id": 1076, // Currency ID in the payment platform
        "alpha_3_4217": "PHP", // ISO-4217 alphabetic currency code
        "number_3_4217": "608", // ISO-4217 numeric currency code
        "exponent": 2 // The number of decimal units of the currency
      }
    ]
  },
  {
    "id": 2371,
    "abbr": "BPIX",
    "name": "BPI Over-the-Counter",
    "nativeName": "BPI OTC",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2451,
    "abbr": "PNBR",
    "name": "PNB Remit",
    "nativeName": "PNB Remit",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  }
]
```

If you have any questions about working with bank branches and ATM chains supported by the Philippines Over the Counter & ATM method, refer to your Ecommpay account manager.

## Purchases by using Payment Page {#en_pm_philippines_atm_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Philippines Over the Counter & ATM method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_philippinesover_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Philippines Over the Counter & ATM method.
8.  The payment platform receives the request for processing the payment by using the Philippines Over the Counter & ATM method.
9.  The payment platform processes the request and sends it to the provider service.
10. The request is processed on the provider service side.
11. The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the provider service.
14. The customer completes all required payment steps.
15. The purchase is processed in the provider service.
16. The result information is displayed to the customer in the provider service.
17. The customer is redirected to Payment Page.
18. The provider service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Generally, when a customer confirms their intention to pay on the side of the web service, they are redirected to Payment Page where they select the payment method and, in the case of working with the Philippines Over the Counter & ATM method, additionally select one of the available bank branches or ATM chains. However, in some situations, other options for choosing a payment method and bank branch or ATM chain may be relevant. For example, upon opening Payment Page, you can immediately redirect the customer to the bank branch or chain selection page or limit the list of supported branches or chains for a particular payment and display only target branch or chain selection buttons to the customer. The specific option of selecting the payment method and branch or chain is determined depending on the parameters specified in the request for opening Payment Page \([details](pm_philippines_atm.md#section_p5j_fgl_ggb)\). The following options are available:

-   1—when the payment form is opened, it sequentially displays separate pages for selecting a method and a bank. Then the customer selects the method and the bank \(this option is used by default\).
-   2—when the payment form is opened, the buttons for selecting other methods and banks supported by this method are displayed on one page. Then the customer selects one of these banks.
-   3—when the payment form is opened, it displays a page with buttons for selecting all available banks for this method. Then the customer selects one of these banks.
-   4—when the payment form is opened, it displays a page with buttons for selecting only specific banks supported by this method. Then the customer selects one of these banks.
-   5—when the payment form is opened, it displays a page requesting confirmation of redirection to the service of the specific bank. Then the customer confirms the redirection.

![](images/universal/pm/splits/en_asian_banking_pp_1_philippines_atm.svg "1—Selecting method and bank")

![](images/universal/pm/splits/en_asian_banking_pp_2_philippines_atm.svg "2—Selecting bank among other methods")

![](images/universal/pm/splits/en_asian_banking_pp_4_philippines_atm.svg "3—Selecting bank among all available banks")

![](images/universal/pm/splits/en_asian_banking_pp_5_philippines_atm.svg "4—Selecting bank among specific banks")

![](images/universal/pm/splits/en_asian_banking_pp_6_philippines_atm.svg "5—Redirection to the service of the specific bank")

Information about the formats of requests and callbacks used for processing payments by using the Philippines Over the Counter & ATM method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Philippines Over the Counter & ATM method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the email address of the customer in the parameter `customer_email`. If any of this parameter is missing, the payment form may display the input field for entering the missing value \(details are available in [Submission of additional payment information](en_pp_clarification.md)\).
3.  The following are the bank branch and ATM chain selection options:

    1.  *Selecting the method and the branch or chain on Payment Page \(1\)*—the default option, applied if the `force_payment_method` parameter and the `payment_methods_options` object are not used.
    2.  *Selecting a branch or chain among other methods on Payment Page \(2\)*—for this option in the `payment_methods_options` object specify the `philippines_atm` object containing the `split_banks` parameter with the value `true`:

        ```language-json
        "payment_methods_options": "{\"philippines_atm\": {\"split_banks\": true}}"
        
        ```

    3.  *Selecting a branch or chain among all available ones on Payment Page \(3\)*—for this option specify the method code `philippines-atm` in the `force_payment_method` parameter.
    4.  *Selecting a branch or chain among specific ones on Payment Page \(4\)*—for this option specify the following:
        -   the philippines-atm code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `philippines_atm` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target branch or chain identifiers:

            ```language-json
            "payment_methods_options": "{\"philippines_atm\": {\"split_banks\": true, \"banks_id\": [2421, 2371]}}"
            ```

    5.  *Confirming redirection to the service of the specific branch or chain on Payment Page \(5\)*—for this option specify the following:
        -   the philippines-atm code in the `force_payment_method` parameter
        -   the `payment_methods_options` object with the `philippines_atm` object that contains the `split_banks` parameter with the value `true` and a `banks_id` object with an array containing the target branch or chain identifier:

            ```language-json
            "payment_methods_options": "{\"philippines_atm\": {\"split_banks\": true, \"banks_id\": [2421]}}"
            ```

4.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
5.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Philippines Over the Counter & ATM method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier and email address, as well as signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

At the same time, in case of selecting a bank among specific banks \(4\), the request for opening Payment Page may contain additional data.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "force_payment_method": "philippines-atm",
   "payment_methods_options": {"philippines_atm": {"split_banks": true, "banks_id": [2421, 2371]}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Philippines Over the Counter & ATM method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PHP` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines atm",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines atm",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_philippines_atm_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Philippines Over the Counter & ATM method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Philippines Over the Counter & ATM service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_philippinesover_uml_gate.svg)

1.  A customer initiates a purchase by using the Philippines Over the Counter & ATM method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the provider service.
7.  The request is processed on the provider service side.
8.  The provider service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the provider service.
11. The customer completes all required payment steps.
12. The purchase is processed in the provider service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The provider service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Philippines Over the Counter & ATM method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Philippines Over the Counter & ATM method:

1.  To initiate each purchase, send a separate POST request to the `v2/payment/atm/philippines/sale` endpoint. This endpoint belongs to the group [/v2/payment/atm/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/atm/post-v2-payment-atm-payment-method-sale).
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturegenerated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `id`—customer identifierunique within the project
        -   `ip_address`—customer IP addressrelevant for the initiated payment
        -   `email`—email address
    -   Object `account`—information on the physical bank branch or ATM chain:
        -   `bank_id`—identifier of the physical bank branch or ATM chain
    -   Object `return_url`—contains the URLs to which customer is redirected during or after payment processing:
        -   `success`—URL for redirecting a customer after a performed purchase
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Philippines Over the Counter & ATM method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer identifier, IP and email addresses, identifier of a bank branch or ATM chain, URL for redirection, as well as signature.

```language-json
{
    "general": {
        "project_id": 580,
        "payment_id": "test_atm_sale",
        "signature": "pgwRHcfv2O08nMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "id": "customer123"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}
```

```language-json
{
    "general": {
        "project_id": 580,
        "payment_id": "test_atm_sale",
        "signature": "pgwRHcfv2O08nMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "id": "customer123"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the Philippines Over the Counter & ATM method requires redirection of customers from the merchant's web service to the Philippines Over the Counter & ATM service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

```language-json
"redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
  }
```

### Final callback format {#section_wsx_3jl_ggb .section}

The Philippines Over the Counter & ATM method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `10.00 PHP` purchase made in the `239` project.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines atm",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}
```

The following is the example of a callback with information about a declined purchase.

```language-json
 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines atm",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—about the interaction with the payment platform by using Gate.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Analysis of payments results {#en_pm_philippines_atm_dash_analysis}

To analyse information about payments made with the Philippines Over the Counter & ATM method and other methods, you can use:

-   Dashboardinterface toolkitwith various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface.

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# PIX {#pm_pix}

An article about the payment method which allows to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and payouts.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_pix_overview}

An article about the payment method which allows to process payments in Brazilian reals and US dollars by using bank accounts in Brazil and supports purchases and payouts.

### Introduction {#section_owc_rzc_cvb .section}

PIX is a payment method which allows process payments in Brazilian reals and US dollars by using bank accounts in Brazil. This method supports purchases and payouts.

This article provides information about working with the PIX method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instrument|bank accounts|
|Countries and regions|[BR](references/en/countries/BR.md)|
|Payment currencies|[BRL](references/en/currencies/BRL.md)|
|Currency conversion|on Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|–|
|Partial refunds|–|
|Payouts|+|
|Chargebacks|–|
|Notes|–|
|Obtaining access to the payment method and access fee|refer to your Ecommpay key account manager|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the PIX method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the PIX service.

![](images/pm/eng_pix_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the PIX method. Purchases can be processed by using Payment Page, Gate and Dashboard\(using payment links\), payouts—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable to all operations.

| |Amounts, [BRL](references/en/currencies/BRL.md) ¹|
|minimum|maximum|
|--|-------------------------------------------------|
|-------|-------|
|Purchases|–|50,000.00|
|Payouts|–|–|

**Note:**

1.  Depending on the PIX service, the total value of purchases and payouts made by and to the customer per month, can be limited. Refer to Ecommpay technical support in case of such problems.

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the PIX method, you need to redirect customer to the PIX service, while to initiate a payout, you need to notify the customer via the web service.

General scenarios of processing purchases can be presented as follows.

![](images/mglwallet/pm/en_pix_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/en_pix_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/eng_pix_interfaces_gate_payout.svg "Payout by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_pix_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the PIX method, the merchant web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/mglwallet/pm/en_pix_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the PIX method.
8.  The payment platform receives the request for processing the payment by using the PIX method.
9.  The payment platform processes the request and sends it to the PIX service.
10. The request is processed on the PIX service side.
11. The data for redirecting the customer to the PIX service is sent from the PIX service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the PIX service.
14. The customer completes all required payment steps.
15. The purchase is processed in the PIX service.
16. The result information is displayed to the customer in the PIX service.
17. The customer is redirected to Payment Page.
18. The PIX service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the PIX method via Payment Page is presented further in this section. General information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the PIX method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  Additionally, it is recommended to specify the following parameters:
    -   `customer_first_name`—first name of the customer
    -   `customer_last_name`—last name of the customer
    -   `customer_email` —customer email address \(can be omitted if the `customer_phone` parameter is specified\)
    -   `customer_phone` —customer phone number \(can be omitted if the `customer_email` parameter is specified\)
    -   `identify_doc_number`—CPF \(Cadastro de Pessoas Físicas, taxpayer identification number assigned to an individual; 11 digits\) or CNPJ \(Cadastro Nacional da Pessoa Jurídica, taxpayer identification number assigned to a legal entity; 14 digits\)
3.  If you need to have payment form displayed with the PIX method selected, set the `force_payment_method` parameter to `pix`.
4.  Additionally, any other parameters available for working with Payment Page can be used. See [Payment Page API specification](en_PP_Parameters.md) for information on all available parameters.
5.  After all target parameters are specified, create a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the PIX method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information and signature.

``` {#codeblock_ayl_fcb_v3c .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "BRL",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johnson@example.com,
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

``` {#codeblock_ewy_vdx_xgc .language-json}
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "BRL",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johnson@example.com,
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The PIX method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `100.00 BRL` purchase in the `312` project.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "9582",
            "type": "purchase",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "created_date": "2021-11-03T08:10:13+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "9583",
            "type": "purchase",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "created_date": "2021-11-03T08:15:43+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025d",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—how to organise interaction with the payment platform by using Payment Page
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_pix_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the PIX method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the PIX service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/en_pix_uml_gate.svg)

1.  A customer initiates a purchase by using the PIX method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the PIX service.
7.  The request is processed on the PIX service side.
8.  The PIX service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the PIX service.
11. The customer completes all required payment steps on the PIX service side.
12. The purchase is processed in the PIX service.
13. The result is displayed to the customer.
14. The customer is redirected to the web service.
15. The PIX service sends the payment result notification to the payment platform.
16. The payment platform sends the payment result callback to the web service.
17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the PIX method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending purchase requests by using the PIX method:

1.  To initiate each purchase, send a POST request to the [/v2/payment/pix/sale](https://api-developers.ecommpay.com/api-specification/pix/post-v2-payment-pix-sale) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general purchase information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturecreated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payment amount in the smallest currency unit
        -   `currency`—payment currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `ip_address`—IP addressrelevant for the initiated payment
        -   `first_name`—customer first name
        -   `last_name`—customer last name
        -   `email`—customer email \(can be omitted if the `phone` parameter is specified\)
        -   `phone`—customer phone number \(can be omitted if the `email` parameter is specified\)
        -   `id`—customer identifierunique within the project
        -   `identify`—information about the document which establishes identity:
            -   `doc_number`—CPF \(Cadastro de Pessoas Físicas, taxpayer identification number assigned to an individual; 11 digits\) or CNPJ \(Cadastro Nacional da Pessoa Jurídica, taxpayer identification number assigned to a legal entity; 14 digits\)
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the PIX method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information as well as signature.

```language-json
{
    "general": {
        "project_id": 312,
        "payment_id": "9582",
        "signature": "3zjYFq8JuRey87Q4OyuWF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    }
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "identify": {
            "doc_number": "12345678901"
        }
    }
}
```

``` {#codeblock_cgb_3yw_v3c .language-json}
{
    "general": {
        "project_id": 312,
        "payment_id": "9582",
        "signature": "3zjYFq8JuRey87Q4OyuWF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    }
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "identify": {
            "doc_number": "12345678901"
        }
    }
}
```

### Formats of intermediate callbacks for customer redirection {#section_nxg_hmn_zgb .section}

Each payment made with the PIX method requires redirection of customers from the merchant's web service to the PIX service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the `redirect_data` object. The format of such callbacks is standard \([details](en_platform_callbacks.md)\), and the following objects and parameters are included in the `redirect_data` object:

-   `body`—object with data to be sent in the request body
-   `method`—parameter specifying the HTTP method for sending the request \(`GET` or `POST`\)
-   `url`—parameter containing a link for redirection

``` {#codeblock_czz_fdb_1fc .language-json}
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }
```

### Callback format {#section_wsx_3jl_ggb .section}

The PIX method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `100.00 BRL` purchase in the `312` project.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "9582",
            "type": "purchase",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "created_date": "2021-11-03T08:10:13+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "9583",
            "type": "purchase",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "created_date": "2021-11-03T08:15:43+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025dd8e-00000001",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing purchases via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—how to organise interaction with the payment platform by using Gate
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Gate {#en_pm_pix_gate_payout}

### General information {#section_lsx_3jl_ggb .section}

To process a payout through Gateby using the PIX method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of payout processing are provided below.

![](images/pm/eng_pix_uml_gate_payout.svg)

1.  A customer orders a payout through the PIX system.
2.  Merchant's web service sends the request for the payout processing by using Gate to the appropriate Ecommpay URL.
3.  The Gate redirects the request to the Ecommpay payment platform.
4.  The payment platform performs all the necessary checks and processes the request.
5.  The reply with the request processing results is sent to the merchant's web service. For more information, see [Response format](en_gate_interaction_organisation.md).
6.  The payment platform redirects the payout request to the PIX service.
7.  The payout is processed on the PIX side.
8.  PIX sends the result notification to the payment platform.
9.  The payment platform sends a callback with the payment result to the web service.
10. The customer receives the notification about the payout result from the web service.

Information about the formats of requests and callbacks used for processing payouts by using the PIX method via Gate is presented further in this section. General information about working with the Gate API is presented in [Interaction concepts](en_gate_interaction_organisation.md).

### Request format {#section_osx_3jl_ggb .section}

There are several things you need to consider when sending payout requests by using the PIX method:

1.  To initiate each payout send a POST request to the [/v2/payment/pix/payout](https://api-developers.ecommpay.com/api-specification/pix/post-v2-payment-pix-payout) endpoint.
2.  Each request must include the following objects and parameters:
    -   Object `general`—general payout information:
        -   `project_id`—project identifierobtained from Ecommpay during integration
        -   `payment_id`—payment identifierunique within the project
        -   `signature`—request signaturecreated after all required parameters are specified \(details—in the [Signature generation and verification](en_platform_signature.md)\)
    -   Object `payment`—payment information:
        -   `amount`—payout amount in the smallest currency unit
        -   `currency`—payout currency codein the ISO-4217 alpha-3 format
    -   Object `customer`—customer information:
        -   `ip_address`—IP addressrelevant for the initiated payout
        -   `first_name`—first name
        -   `last_name`—last name
        -   `email`—customer email \(can be omitted if the `phone` parameter is specified\)
        -   `phone`—customer phone number \(can be omitted if the `email` parameter is specified\)
        -   `country`—customer country code in ISO 3166-1 alpha-2 format
        -   `day_of_birth`—date of birth in the format DD-MM-YYYY
        -   `id`—customer identifierunique within the project
        -   `identify`—information about the document which establishes identity:
            -   `doc_number`—CPF \(Cadastro de Pessoas Físicas, taxpayer identification number assigned to an individual; 11 digits\) or CNPJ \(Cadastro Nacional da Pessoa Jurídica, taxpayer identification number assigned to a legal entity; 14 digits\)
    -   Object `account`—customer account information:
        -   `number`—customer account number
3.  Additionally, any other parameters included in the specification can be used.

Thus, a correct payout request by using the PIX method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, as well as signature.

``` {#codeblock_bgq_jqz_djc .language-json}
{
    "general": {
        "project_id": 312,
        "payment_id": "f8827",
        "signature": "3zjYFq8JuRey87Q4OyuWs1KaaWIHaNUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    },
    "customer": {
        "ip_address": "127.0.0.1",
        "first_name": "John",
        "last_name": "Doe",
        "country": "BR",
        "email": "example@xmpl.com",
        "day_of_birth": "22-11-2000",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    },
    "account": {
        "number": "S0Pkonh1Lr2E"
  }
}
```

### Callback format {#section_wsx_3jl_ggb .section}

The PIX method uses the standard format for callbacks to deliver payout results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with an information about successful `100.00 BRL` payout in the `312` project.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "306081845",
            "type": "payout",
            "status": "success",
            "date": "2021-11-03T08:19:26+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 142,
            "type": "payout",
            "status": "success",
            "date": "2021-11-03T08:19:26+0000",
            "created_date": "2021-11-03T08:18:46+0000",
            "request_id": "efe84ccebf77b57dd76f43970",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909",
                "auth_code": ""
            }
        },
        "signature": "lW9TpyiTQBMVa5dRBGC4geg5wneA=="
    }
```

The following is the example of a callback with information about a declined payout.

```language-json
{
        "project_id": 312,
        "payment": {
            "id": "306082355",
            "type": "payout",
            "status": "decline",
            "date": "2021-11-03T08:24:33+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 143,
            "type": "payout",
            "status": "decline",
            "date": "2021-11-03T08:24:33+0000",
            "created_date": "2021-11-03T08:23:56+0000",
            "request_id": "a767d408f85ee594048bbe",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909877",
                "auth_code": ""
            }
        },
        "signature": "J55CcQzHzjl2hvtoPvwfdKHLfUCmX52swTo/0ZljkMsxw=="
    }
```

### Useful links {#section_xsx_3jl_ggb .section}

The following articles can be useful when implementing payouts via Gate:

-   [Interaction concepts](en_gate_interaction_organisation.md)—how to organise interaction with the payment platform by using Gate
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of creating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [Payouts](en_Gate_payout.md)—about processing of payouts by using Gate.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Payouts by using Dashboard {#en_pm_dash_payout}

When working with Dashboard, you can process *single* and *mass* payoutsby using the PIX method.

-   To process a single payout, open the payout form, specify all required parameters \(including the payment method\), send a request and verify that the payout has been processed.
-   To process a mass payout, prepare and upload a file with information about all target payouts, send a batch request, and verify that the payouts have been processed.

    Use a CSV file structured according to the requirements presented in the [Mass payments data](en_dbl_payments.md) section.The payout parameters must comply with the [requirements](pm_pix.md) \(you do not have to generate a signature because it is specified by Dashboard\).


More information about processing payouts by using Dashboard is presented in a [separate section](en_dbl_payments.md).

## Analysis of payments results {#en_pm_pix_dash_analysis}

To analyse information about payments made with the PIX method as well as other methods, you can use:

-   Dashboard interface toolkit with various lists and analytic panels.
-   Reports in CSV file format, available via the **Reports** section \(one-time and periodically\).
-   Data in JSON format, sent by program requests to a specified URL by using the Data API interface \([details](en_dbl_api_protocol.md)\).

If you have any questions, refer to the documentation \([Dashboard](en_dbl_about.md) and [Using Data API](en_dbl_api_protocol.md)\) and Ecommpay technical support.



---

# Przelewy24 {#pm_przelewy}

An article about the payment method which allows you to process payments in euros and zlotys by using bank accounts and payment cards in Poland and supports purchases and refunds.

**Parent topic:**[Bank payments](en_pm_bankpayments.md)

## Overview {#en_pm_przelewy_overview}

An article about the payment method which allows you to process payments in euros and zlotys by using bank accounts and payment cards in Poland and supports purchases and refunds.

### Introduction {#section_t5z_rlg_ytb .section}

Przelewy24 is a payment method which allows you to process payments in euros and zlotys by using bank accounts and payment cards in Poland.This method supports purchasesand refunds.

This article provides information about working with the Przelewy24 method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

### General information {#section_tbf_2zk_ggb .section}

|Payment method type|bank payments|
|Payment instruments|-   bank accounts
-   payments cards

|
|Countries and regions|[PL](references/en/countries/PL.md)|
|Payment currencies|[PLN](references/en/currencies/PLN.md), [EUR](references/en/currencies/EUR.md)|
|Currency conversion|on the Ecommpay side|
|One-time purchases|+|
|Credential-on-file purchases|–|
|Full refunds|+|
|Partial refunds|+|
|Payouts|–|
|Chargebacks|–|
|Notes|–|
|Onboarding and access fee|refer to your Ecommpay key account manager; additional information is available in [ecommshop](https://ecommpay.com/shop/payment-methods/przelewy24/)|

### Interaction diagram {#section_tsp_gzk_ggb .section}

Payment processing by using the Przelewy24 method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the Przelewy24 service.

![](images/pm/eng_przelewy24_functional.svg)

### Operations support {#section_rnx_4cl_ggb .section}

Various platform interfaces can be used to process payments and perform operations using the Przelewy24 method. Purchases can be processed by using Payment Page, Gate and Dashboard \(using payment links\), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following limitations are applicable.

| |Amounts [EUR](references/en/currencies/EUR.md)/[PLN](references/en/currencies/PLN.md)|
|minimum|maximum|
|--|-------------------------------------------------------------------------------------|
|-------|-------|
|Purchases|1.00|55,000.00|
|Refunds|–|–|

### Processing scenarios {#section_fgt_sdl_ggb .section}

To perform a purchase by using the Przelewy24 method, you need to redirect the customer to the Przelewy24 service, while to make a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service.

![](images/pm/eng_przelewy24_interfaces_pp.svg "Purchase by using Payment Page")

![](images/pm/eng_przelewy24_interfaces_gate.svg "Purchase by using Gate")

![](images/pm/eng_przelewy24_interfaces_refund.svg "Refund by using Gate")

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features \(such as payment links\) are used, scenarios for performing operations also correspond to the specifics of those features.

## Purchases by using Payment Page {#en_pm_przelewy_pp_purchase}

### General information {#section_gtg_vxk_m2b .section}

To process a purchase through Payment Pageby using the Przelewy24 method, the merchant's web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result.The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_przelewy24_uml_pp.svg)

1.  A customer initiates a purchase in the web service.
2.  The web service sends the request for opening Payment Page to the specified Ecommpay URL.
3.  The request for opening Payment Page is sent to the payment platform.
4.  The payment platform receives the request and validates the required parameters and signature.
5.  Payment Page is generated based on the project and request parameters.
6.  Payment Page is displayed to the customer.
7.  The customer selects the Przelewy24 method.
8.  The payment platform receives the request for processing the payment by using the Przelewy24 method.
9.  The payment platform processes the request and sends it to the Przelewy24 service.
10. The request is processed on the Przelewy24 service side.
11. The data for redirecting the customer to the Przelewy24 service is sent from the Przelewy24 service to the payment platform.
12. The data for redirecting the customer is sent from the payment platform to Payment Page.
13. The customer is redirected to the Przelewy24 service.
14. The customer completes all required payment steps.
15. The purchase is processed in the Przelewy24 service.
16. The result information is displayed to the customer in the Przelewy24 service.
17. The customer is redirected to Payment Page.
18. The Przelewy24 service sends a notification about the result to the payment platform.
19. The payment platform sends the payment result callback to the web service.
20. The payment platform sends the result information to Payment Page.
21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Przelewy24 method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in [Interaction concepts](en_pp_interaction_organisation.md).

### Request format {#section_p5j_fgl_ggb .section}

There are several things you need to consider when sending purchase requests by using the Przelewy24 method:

1.  The following parameters required for any payment must be specified:
    -   `project_id`—project identifier obtained from Ecommpay during integration
    -   `payment_id`—payment identifier unique within the project
    -   `payment_currency`—payment currency code in the ISO-4217 alpha-3 format
    -   `payment_amount`—payment amount in the smallest currency unit
    -   `customer_id`—customer identifier unique within the project
2.  To open Payment Page, specify the language code in the `language_code` parameter in the request for opening. For more information, see [Interface language support](en_PP_WigetLanguages.md).
3.  These parameters also must be specified:
    -   `customer_email`—customer email address
    -   `customer_first_name`—customer first name
    -   `customer_last_name`—customer last name
4.  If you need to have the payment form displayed with the Przelewy24 method selected, set the `force_payment_method` parameter to `przelewy24`.
5.  Additionally, any other parameters available for working with Payment Page can be used \([details](en_PP_Parameters.md)\).
6.  After all target parameters are specified, generate a signature \([details](en_platform_signature.md)\).

Thus, a correct request for opening the payment form using the Przelewy24 method must contain the project identifier, basic payment information \(identifier, amount, and currency code\), customer information, language code and signature.

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "customer_email": "john@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "language_code": "en",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

```language-json
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PLN",
   "customer_id": "customer1",
   "customer_email": "john@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Johnson",
   "language_code": "en",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
```

### Callback format {#section_dpx_2hl_ggb .section}

The Przelewy24 method uses the standard format for callbacks to deliver purchase results. For more information, see [Handling callbacks](en_platform_callbacks.md).

The following is the example of a callback with information about a `100,00 PLN` purchase made in the `238` project.

```language-json
 {
        "project_id": 238,
        "payment": {
            "id": "test__02",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "method": "przelewy24",
            "sum": {
                "amount": 10000,
                "currency": "PLN"
            },
            "description": "payment_02"
        },
        "account": {
            "number": "2626324568"
        },
        "operation": {
            "id": 14153000003282,
            "type": "sale",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "created_date": "2019-02-19T14:25:24+0000",
            "request_id": "9d11b2ca618ec3bad2913b488"
                "amount": 10000,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "PLN"
            },
            "provider": {
                "id": 1169,
                "payment_id": "105887607",
                "date": "2019-02-19T14:25:24+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "of8k9xerK0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
    }
```

The following is the example of a callback with information about a declined purchase.

```language-json
{
        "project_id": 238,
        "payment": {
            "id": "TEST_154996862174000",
            "type": "purchase",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "method": "przelewy24",
            "sum": {
                "amount": 100,
                "currency": "PLN"
            },
            "description": "TEST_154996862174000"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 9172000003183,
            "type": "sale",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "created_date": "2019-02-12T10:56:18+0000",
            "request_id": "11d4aabf869cb74c0681927ad7",
            "sum_initial": {
                "amount": 100,
                "currency": "PLN"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "PLN"
            },
            "provider": {
                "id": 1169,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "dfgfds1oVdS/mE0AlVOJRrqn7HiBOEIObz2tN5SLw=="
    }
}
```

### Useful links {#section_xpz_thl_ggb .section}

The following articles can be useful when implementing purchases via Payment Page:

-   [Interaction concepts](en_pp_interaction_organisation.md)—about the interaction with the payment platform by using Payment Page.
-   [Signature generation and verification](en_platform_signature.md)—about the procedure of generating and verifying signatures in requests and callbacks.
-   [Payment processing](en_platform_payment_model.md)—about the types, processing models, and possible statuses of supported payments and operations.
-   [One-time one-step purchase](en_platform_sms_model.md)—about processing of one-time one-step purchases by using Payment Page.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—about error and response codes that are used in the payment platform to record information about performing of operations.

## Purchases by using Gate {#en_pm_przelewy_gate_purchase}

### General information {#section_lsx_3jl_ggb .section}

To process a purchase through Gate by using the Przelewy24 method, the merchant's web service is required to do the following:

1.  Send a request with all the required parameters and signature to the Ecommpay URL.
2.  Receive an intermediate callback from the payment platform and redirect the customer to the Przelewy24 service.
3.  Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

![](images/pm/eng_przelewy24_uml_gate.svg)

1.  A customer initiates a purchase by using the Przelewy24 method in the web service.
2.  The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
3.  The payment platform receives the request.
4.  The payment platform validates the required parameters and signature in the request.
5.  The payment platform sends the response to the web service with information about the receipt of the request and its validity \([details](en_gate_interaction_organisation.md)\).
6.  The payment platform performs further processing of the request \(with parameter consistency check\) and sends it to the Przelewy24 service.
7.  The request is processed on the Przelewy24 service side.
8.  The Przelewy24 service sends the redirection data to the payment platform.
9.  The payment platform sends the callback with the redirection data to the web service.
10. The customer is redirected to the Przelewy24 service.
11. The cust