Integration

Payment Card Industry Data Security Standard (PCI DSS) is a standard for the proper protection of payment card data. It is developed by the PCI Security Standards Council (PCI SSC) and sets requirements for all companies involved in processing, storing, or transmitting payment card data. Complying with the PCI DSS requirements is absolutely mandatory: no parties involved in processing card payments are allowed to process such payments otherwise.

To prove the compliance with the PCI DSS requirements and be allowed to process card payments, merchants are required to provide the corresponding documents to payment systems (such as Visa, Mastercard, and Amex) in time, directly or through providers. Depending on a payment system, there can be different requirements to such documents with regards to the data breach incidents and other cases. Therefore, the necessity for a particular merchant to provide certain documents is considered on a case-by-case basis.

In the case of the Visa and Mastercard payment systems, the PCI DSS compliance documents should be provided to ecommpay. Thus the following documents are required:

• From all merchants—the ASV scan report.

  The 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, have the scanning procedure performed by the ecommpay partner. To have the scanning service 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, SAQ.

  With questions on completing the questionnaire, contact the ecommpay key account manager.

After all required documents have been checked, the merchant can start processing card payments—the merchant is informed about this (as well as about the expiration of the documents validity period) by the ecommpay key account manager.

In the case of other payment systems, the PCI DSS compliance documents usually should be provided directly to these payment systems, however, the merchants can consult with the key account manager about the necessity of providing these documents to ecommpay.

As a rule, during the integration process, merchants get access first to the test environment to try essential workflows without processing real payments, then to the production environment in order to deploy customised and tested solutions.

For these purposes, the ecommpay technical support specialists create and configure two projects of interaction with the merchants' web services—a test project and a production project—with specific identifiers for each of them (project_id). Changing a project ID in requests turns the test environment into the real one. Since sets of parameters and addresses for receiving requests in the two environments are identical, it is important not to confuse the project IDs and handle them properly. By default, the technical support specialists provide merchants with a single test project, but it is possible to create additional projects on request.

Note that the test environment has a limited number of available payment methods and scenarios. For more information, see the corresponding sections on testing via direct use of payment cards (Test cards) and alternative payment methods (for example, testing Google Pay).

All test payments are processed in the platform like the ones in the production environment: they are registered in the platform with the information about them displayed in the Dashboard interface, and the details of payment instruments are processed and protected without actual debiting taking place. Therefore, testing provides you with a complete picture of the work process when you can use real data of payment cards, wallets, and other instruments without running risks of payment information misuse.

The environment in each of these cases can be defined as a set of internal software components in the platform that emulate payments in test mode and actually process payments in production mode.

Each of the ecommpay payment platform interfaces uses its own base URL.

This is important to keep in mind, for example, when you use Payment Page and Gate for different actions: you can generate a token via Payment Page and then make a payout with this token via Gate. In this case, you use two different URLs: https://paymentpage.ecommpay.com and https://api.ecommpay.com for Payment Page and Gate respectively. To request balance information about this payout via Data API, you can use the third base URL: https://data.ecommpay.com/v1. Even with such an abundance of URLs, we still hope you find it quite comprehensible.

Information about the base URLs, request structures, and other features of the interfaces is provided in sections with the descriptions of these interfaces. The URLs for program and customer actions are listed below:

• https://api.ecommpay.com is for interaction via Gate. For example, the URL for a payment status request is https://api.ecommpay.com/v2/payment/status. For more information about working with the Gate API requests, see Request format.
• https://paymentpage.ecommpay.com is for interaction via Payment Page. For example, a GET payment request is GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&... HTTP/1.1 Host: https://paymentpage.ecommpay.com. For more information about working with the Payment Page API requests, see Request format.
• https://data.ecommpay.com/v1 is for interaction via Data API. For example, the URL for an account balances request is https://data.ecommpay.com/v1/balance/get. For more information about working with the Data API requests, see Using Data API.
• dashboard.ecommpay.com is for merchant employees to access the Dashboard web interface.

Payment within the platform is a comprehensive record of one settlement between a merchant and a customer. A single payment may include a one-time cash flow—from the customer to the merchant (purchase) or vice versa (payout)—or a repeated cash flow—for example, a purchase followed by a refund or a series of debiting payments. The payment is considered completed upon settlement between the merchant and the customer as part of the service provided by the merchant (which includes the corresponding payment request initiated by the merchant). Like in everyday life, the purchase can change its final state—it can be completed with the status of success and subsequently get the status of partially refunded.

Operation within the platform is a single action with funds performed during a payment. An operation can include placing a hold on funds for their consequent debiting, the debiting itself, refund, or payout. Processing a single payment may require one or more operations. Such a division is helpful in terms of controlling settlements at the level of payments and specific operations.

Each payment in the platform has its identifier (payment_id) that is unique within a project. Such IDs can include numbers, Latin letters, and other characters in the UTF-8 encoding, and their length must not exceed 255 characters—for example, payment-123 or cosmoshop.sale_456. If a request is valid, the payment is registered in the platform and the appropriate operation is initiated for this payment. Each operation gets an identifier (operation_id) that is unique within the platform. These IDs are passed in callbacks, and you can use them in the Dashboard interface.

Note that a payment and the operations within the payment can have different statuses. For example, a payment with the refunded status includes the refund operation with the success status. For more information about the differences and features of these concepts, see Payment models and statuses.

• Purchase is a payment with a transfer of money from a customer to a merchant. It can include payments for goods and services, booking or reservation prepayments, subscription payments, and so on. A purchase can be a one-time or recurring payment, and it can also be refunded in certain cases.
• Refund is the operation of returning the money from a merchant to a customer after a purchase. This can refer to cancelling reservations or returning goods. Along with that, refunds can be full (the customer gets the entire amount) and partial (the customer gets a part of the previously paid amount).
• Payout is a payment with a transfer of money from a merchant to a customer. This can refer to receiving prize money, bonuses, or compensation for expenses.

Purchases can be made using all interfaces of the platform. Payouts and refunds are initiated through the Gate API and Dashboard. While these features are supported for the card payment methods, some of them may be unavailable for alternative payment methods. For up-to-date information about individual payment methods, see their descriptions in the corresponding sections.

In short, the choice between one-step or two-step purchases depends on how quickly funds are debited and how quickly and easily they can be partially or fully returned after a payment is made.

A one-step purchase implies debiting funds without delay—as quickly as it is done in the payment systems. This is a good option when it comes to paying for goods or actually provided services and the amount of payment is fixed and can not be changed. To return the funds to the customer upon completing a one-step purchase, you need to issue a full or partial refund. One-step purchases are supported for different payment methods and can be used for loan repayment to microfinance organisations. For more information about this type of payment, see One-step purchase.

A two-step purchase includes two stages: placing a hold on funds, and after confirmation, debiting or returning them to the customer. The total amount of money that is to be eventually debited or returned can change from the previously held amount. This is a good option for different types of booking and renting services, services with prepayments and insurance premiums, and others. In such cases, the held funds can be debited upon the merchant's confirmation request or after a specified period of time. If the funds have not been debited, you can return them to the customer by releasing the hold on funds. If the funds have been debited, you can issue a refund (the same way it is done with one-step purchases). Two-step purchases are currently supported only for payment cards. For more information about this type of payment, see Two-step purchase.

You can always consult the ecommpay key account managers on choosing the most suitable option for your business sphere in particular regions.

Payment methods within the ecommpay platform are ways of making payments characterised by supported operations, currencies, payment instruments, and user scenarios. The availability of these methods varies on a regional basis. For example, purchases made in Indonesian rupiah through online banking systems and purchases in the same currency by using e-wallets are two different payment methods. Thus, such characteristics specific to different regions and business spheres give relevance to the plethora of payment methods available within the platform. The ecommpay key account managers can provide you with deeper insights into specific payment methods and differences between them and help you select methods most suitable for your business activities.