Home - khpos/Payment-gateway_EN GitHub Wiki
Welcome to the new K&H Payment Services online payment gateway!
:arrow_right: Please use the navigation on the right
K&H Payment Services is introducing a new online payment solution that significantly expands your options for convenient payment collection from your clients in your e-shops as well as mobile commerce applications. The new payment gateway fully replaces the existing K&H Payment Service online offer, introduces new merchant API as well as new payment methods.
New payment gateway API
The new API allows you to manage the online payment transaction from its initiation up to a refund. You can choose which API methods to implement, based on your business needs. New payment methods can be easily added to your implementation if you decide to start only with basic card payment. The new API also minimizes the impact of PSD2 online payment authentication on merchants, simplifying to the largest extent possible.
Please check out the list of API methods provided by the payment gateway. For the very basic implementation, you will need to use payment/init for transaction initiation, payment/process for actual start of the payment process and payment/status for transaction status inquiries. Additional payment methods (such as direct integration of Apple Pay and Google Pay buttons to your e-shop front-ends require additional API methods).
The communication on the API is signed for security reasons. Please read the full documentation on how to sign the request and validate the signature of the response.
Available payment methods
Card Payment
Payment at the payment gateway is the basic and easiest way to pay at K&H Payment Services online payment gateway. After redirecting the customer to the payment gateway, the payment gateway will take care of the entire payment process and the merchant will only wait for the customer to return (by redirection) back to the e-shop. The universally accepted card brands are Visa, Visa Electron, VPay, MasterCard, MasterCard Debit and Maestro.
OneClick – stored card credentials for quick checkouts
OneClick Payment allows regular customers to pay significantly more conveniently and faster. At the first (registration) payment, the customer gives permission to webshop to store card data on the payment gateway and perform subsequent payments with stored card data (when user choose this option). The payment is completed in the standard way (webshop redirection to the payment gateway, entering the card number, validity, CVC, payment authentication using 3D Secure) WEbshop task is to store Payid at the registered user data, to be able to offer quick checkout by usage of stored card. With each subsequent payment, the customer just says that they want to use the card from the previous purchase (if registered user store more card data, it is useful to name the card by the time of storage at webshop). In case of OneClick usage the communication with the payment gateway takes place in the background without the need to re-enter the card number.
Apple Pay
img/shared/apple-pay/apple_pay_logo.png
Apple Pay is known for contactless payments at payment terminals where you can pay by your phone or Apple Watch. Cards that users download to their iPhone, iPad and Apple Watch can also be used for online payments. K&H Payment Services online payment gateway is now ready to process Apple Pay online payments. The payment can take place directly in the e-shop (in a browser or in the native mobile iOS application) – your customer will not be redirected to the payment gateway, which further simplifies and speeds up the Apple Pay payment.
Google Pay
img/shared/google-pay/google-pay-logo.png
Google Pay™ is a comfortable way of paying for goods and services in your e-shop or Android mobile app. Your clients can pay with the same cards they use on contactless terminals in shops. Your clients do not need to retype the card number and the payment is authenticated directly on the Android phone, without the need to further authenticate the payment in 3D Secure. These two features make Google Pay one of the most convenient payment methods.
Transaction management
All successful payments will be paid out to your bank account on the next working day. Detailed transaction statements can be used for payment reconciliation. The format of these statements does not change with the introduction of the new payment gateway.
Any payment can be refunded by the payment/refund operation (also partially, multiple times up to the amount of the original payment) within the next 12 months following the successful payment authorization.
The payment gateway also allows you to charge charge the customer a lower amount than the amount authorized and authenticated at the time of payment. The authorized amount is blocked on the customer's account for 7 days, i.e. payment is guaranteed for the merchant for this period. You will typically use a settlement of a lower amount in situations where the exact amount of the purchase is not known in advance. This may apply, for example, to online grocery shopping at a time when weighted goods are a part of the purchase.
Supported API versions
The new API is the present and the future of the communication between the merchant and the payment gateway. Before integrating the payment gateway into your e-shop or mobile application, please see the complete eAPI documentation between the e-shop and the payment gateway, see how to simulate different transaction states and what test cards to use.
Supported version is currently 1.0. The old API of the payment gateway integration, offered by K&H Payment Services between November 2020 and July 2022 is still working, but it will be decommissioned in the near future. We recommend always using the latest API version.
| eAPI version | Introduced | Not recommended | Deprecated | New features and changes |
|---|---|---|---|---|
| 1.0 | 07/2022 | n/a | n/a | New online payment gateway. |
For a new implementation, we recommend that you always choose the latest available API version.
| Function | Call | 1.0 |
|---|---|---|
| Basic payment | payment/init |
✔️ |
| OneClick payment | oneclick/init |
✔️ |
| Apple Pay | applepay/init |
✔️ |
| Google Pay | googlepay/init |
✔️ |
| Check payment status | payment/status |
✔️ |
| Transaction reversal | payment/reverse |
✔️ |
| Manually send the transaction to clearing & Collect partial payment | payment/close |
✔️ |
| Transaction refund | payment/refund |
✔️ |
| Checking the gateway availability | echo |
✔️ |
Documentation updates and improvements
| Date | Changes |
|---|---|
| 13.10.2022 | Removed unused/not-needed echo/customer operation and customerId and customerCode parameters |