FAQ

General

• How does the payleven API work?

  Our API allows you to integrate payments within your iOS, Android or mobile web application. Once integrated, you can remotely open the payleven app from your own app to initiate a payment. You can also print or send a receipt for the respective transaction via an email within the payleven app. Once the transaction has been processed the payleven app switches back to the calling app which then displays the result of the payment. More information is available in the general section of our developer page.
  
For a better understanding of how the payleven API works, we recommend you to take a look at our example integration. As soon as you have installed the example app on your mobile device you can run through the entire payment flow under the same or similar conditions as your personal integration.

  Please pay attention to the preconditions for using the payleven API solutions in order to ensure that you experience a smooth integration.

• How much does payleven cost?

  Please refer to the FAQ, "Cost" section.


  You can find the pricing of the Chip & PIN terminal also on our cost page
.

  The payleven apps (available in the google play store and the apple app store) and the APIs are free.

• Why is payleven better than the other options I'm considering?

  Thank you for asking! Here are some reasons why others have chosen payleven:

  • Highest number of active integrations in the mPOS market.
  • The elegant, powerful API makes it quick and easy to integrate with payleven.
  • Competitive, pay-as-you-go pricing.
  • Download the payleven apps and the SDKs for free.
  • Highest confidentiality and security when handling sensitive transaction data, and ensured PCI compliance.
  • Fast replies from our support team. Contact us for immediate assistance from developers with personal responses.

• What countries does payleven support?

  With payleven and our Chip & PIN terminal, you can accept payments from almost any credit and debit card, no matter where your point of sale is. 
In order to accept payments with payleven, however, you or your business must be based in one of the countries that payleven is operating in. A list of countries which are supported by payleven can be found here: https://payleven.com.

• Which cards and payment types can I accept with payleven?

  Please find information about accepted card types in the FAQ “Accepting Payments” section.
  You can accept debit and credit card payments from most common providers with our Chip & PIN terminal. Beyond that, you can also accept cash payments with the payleven app so that you can store and list both your cash and card payments in one accounting system. For cash payments no fees are charged by payleven, but you are able to record the transaction and then print or send the receipt to your customer through the app.

• Can I accept card payments with the Chip & PIN terminal without integrating the API or using the payleven app?

  In order to ensure the highest security standards and PCI compliance the communication between the Chip & PIN terminal and the card only works through the payleven app or the API whereby the payleven app opens up. Therefore the payleven app must be installed on the iOS or Android device which is used for accepting payments.

• Can I accept card payments with payleven without internet connection?

  No, an internet connection is required. To avoid issues due to unstable or slow internet access, we recommend 3G, LTE or Wi-Fi as a minimum connection.

• Where can I find new versions of the payleven API?

  The latest version of each API is always available under libraries.

• Do I have to register for each API or can I receive all packages at once?

  For each API, one separate registration is required. The main reason for this is that you need 3 different API keys in order to integrate with payleven on 3 different platforms (iOS, Android and mobile web API). Of course you can login to the payleven app using the same payleven merchant account for all integrations.

• I have multiple apps on the same platform (iOS, Android or Web). Do I need to register for each app?

  The API key is dependent on the data that you enter during the registration such as the package name, bundle ID, callback URL scheme etc. If this data varies among the apps then you will need to request an API key by registering on our sign up form, for API packages for each app.

• Do I (as an integrator) or my client (merchant who accepts card payments) need to be PCI compliant?

  Neither party has to worry about PCI compliance as payleven takes care of this for you. This is also why you receive only masked card data in order to provide comprehensive fraud protection.

• Is there a “Powered by payleven” image or badge that I can use on my checkout?

  Yes – we have a logo that you can put in your app.

• Do you provide logos for the credit card types we can accept?

  In case you are looking for logos from card types you can accept with payleven, you can find official images provided by Visa and MasterCard.

• I’m not a programmer. Can I still use payleven?

  The integration is simple, however some basic understanding about app development is recommended.
  If you would like to accept card payments, but you don't host your own application and you don't want to write any code, just sign up as a regular payleven merchant in one of the countries we operate.

Integration of payleven API – How it works

• What are the preconditions for integrating the payleven API?

  • You or your client is operating in one of the countries supported by payleven
  • You are registered as a regular payleven user in a payleven country
  • You are registered as an integrator on the developer page for an individual API key
  • The payleven app is installed on the mobile device you want to use for accepting card payments
  • Internet connection and geo location is available in your general use-case

• Is it possible to integrate payleven into a web application or does it work only through native apps on iOS and android devices?

  It’s possible to open the payleven app - either iOS or Android - through your web application running in a browser of your mobile device (phone or tablet). Once implemented the native payleven app will open. This can be either the iOS or Android app, depending on where your browser is running on.

  Please keep in mind that the payleven app must be installed on your mobile device (iOS or Android) in order to login and start accepting card payments.

• What kind of data has to be passed from the integrator app to the payleven app?

  In order to start a transaction you would need to define an amount (in Cents, Pence or Groszy), a currency and a unique order ID. If relevant, a description for the respective transaction, an image of the product or service about to be sold can also be defined. 
As soon as you reached the payment screen in the payleven app, the passed data cannot be overwritten or reconfigured.


• Is it possible to transfer the price directly to the payleven app without manual insert via keypad?

  The transaction amount is passed via API and is not configurable within the payleven app anymore. For this reason, the keypad won't show up either.

• Can I integrate payleven into my Windows application?

  At the moment our app is available on iOS as well as on Android and is accessible through a native and a web API. Depending on the development of the windows platform we might also migrate 
to windows.

  
Please contact us with the following e-mail address developer@payleven.com and use “Windows API” as the subject. In addition, we would ask you to send us the device brand, type and the OS version you wish to use the payleven app on. We will get back to you.

• Do you also offer a headless SDK that allows integration of the payment service into my own app without the need of payleven app being installed?

  We do not offer this to avoid you being involved in PCI or other certifications. In addition, the app switch is very quick. Once you are logged in you won’t need to login again for further transactions. You are directly navigated to the payment screen, making the app switch seamless.
Moreover, all relevant payment information (e.g. price, description etc.) can be passed via the API and will be prefilled in the payleven app so there is no need to enter payment information multiple times.

• Is it possible to send the request for a payment via Bluetooth to the Chip & PIN terminal and get the result back?

  No. Connecting to the Chip & PIN terminal and accepting card payments is only possible through the payleven app particularly because of security and compliance reasons. For security reasons, it is indispensable having the payleven app installed on your mobile device.

• Which features of the normal payleven app are working via the API?

  All features of the payment flow that the user interacts with during a transaction are working via the API as well.

  When payment is initiated from your app, you cannot navigate within the payleven app to other pages in the account. The payment flow as such has to be finished first, before you can change settings in your account.

iOS

• What OS version is needed to integrate the payleven API?

  The minimum requirement for the payleven app is iOS 7. Physical device (iOS phone or tablet) has to be in place for integration and running the apps. Simulator is not enough!

• What is the bundle identifier?

  Every app has a unique bundle identifier (e.g com.yourcompany.app-name) and is assigned by the developers of the app.
 For more information about the bundle identifier, please have a look at the Apple documentation.

  

Please note that it is important that you enter during the registration on the developer page your final bundle identifier under your app which will be published to the app store – this is specified in your Xcode project – because the API key you'll receive is tied to that bundle identifier. Otherwise you'll get the “API Key not found” error.

• What is the Callback URL scheme and why do I have to provide it during the registration?

  For the communication between the payleven app and the integrator app, the payleven app needs to be able to call the integrator app via the URL scheme.  Whenever the integrator app calls the payleven app, it will be notified with the result of the action via the callback.
  Therefore your application needs to have a custom URL scheme registered that payleven can use to notify your app. For more information about implementing a custom URL scheme for your app see the Implementing Custom URL Schemes section in the Apple documentation.

• I received an API key after I registered on the developer page. What is it for?

  It is a unique ID, granting your application access to payleven’s API.
  For the actual integration within your app please use the API key (more than 30 digit long) we have sent you via mail in combination with the Bundle ID and the Callback URL scheme you entered during the registration.
  
Please keep in mind that you shouldn’t use the API key (ending with *****cff195b) provided in the example app of the API package for the actual integration of your own app.

• Is there a method in the API for querying the payleven app in order to check whether the Chip & PIN terminal is ready for accepting payments?

  No, due to the way in which the communication between apps work, there is no feasible way to provide this information.
  Before you initiate a card payment with the Chip & PIN terminal please make sure that the terminal is reactivated from the suspend mode and properly paired with the iOS device that you wish to use for accepting the card payment.
  If you need any help connecting the Chip & PIN terminal to your device please have a look at our online manual or contact our customer service.

• Can I cancel an ongoing transaction through the API with an extra call?

  No, a transaction can only be cancelled within the payleven app. Once a transaction has started, it can be cancelled while processing by pressing the red “X” button on the Chip & PIN terminal. A transaction is automatically cancelled if the transaction process takes too long, is stuck at one point or if the payleven app is forced to shut down.

  Once a transaction has been processed it can no longer be cancelled but a refund can be issued; as long as the transaction is cancellable the payleven app is shown. Therefore it is not required to be able to cancel a transaction from the integrator app.

Android

• What OS version is needed at least to integrate the payleven API?

  OS version of the android device has to be at least version 2.3 or higher. Physical device (Android phone or tablet) has to be in place for integration and running the apps. Simulator is not enough!
  Please ensure that the android device that you plan to use has GPS and Bluetooth connection. Otherwise you won’t be able to download and use the payleven app.

• What kind of permissions does the payleven app request in order to download it from the google play store?

  The payleven app requires only permissions which are essential for using the app and its contained features. For instance network communication, GPS location and Bluetooth.
  You can see a list of permissions when you click on “Install” the payleven app in the google play store.

• What is a package name?

  The package name serves as a unique identifier for the application.
  Please go to your android manifest where you can find the following attribute.
      <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                package="your_package_name"
          . . .
          . . .
          . . .
          . . .>
      </manifest>
  When registering for the API key as an integrator you should enter what you find in place of your_package_name.
  In the case that your package name has changed since you have registered you will need to register again. In this case please remember to use your latest API key.

• I received an API key after I registered on the developer page. What is it for?

  It is a unique ID granting your application access to payleven’s API. 
Call PaylevenApi.configure(API_KEY) before doing any other calls to the API. For example, call this in the onCreate method of your launcher activity.
  For the actual integration within your app please use the API key (more than 30 digit long) that we have sent you via mail, in combination with the package name you entered during the registration.
Please mind that you shouldn’t use the API key (ending with ******ba62869) provided in the example app of the API package for the actual integration of your own app.

• Is there a method in the API for querying the payleven app in order to check whether the Chip & PIN terminal is ready for accepting payments?

  No, due to the way in which the communication between apps work, there is no feasible way to provide this information.
  Before you initiate a card payment with the Chip & PIN terminal please make sure that the terminal is reactivated from the suspend mode and properly paired with the iOS device that you wish to use for accepting the card payments.
  If you need any help connecting the Chip & PIN terminal to your device please have a look at our online manual or contact our customer service.

• Can I cancel an ongoing transaction through the API with an extra call?

  No, a transaction can only be cancelled within the payleven app. Once a transaction is started, it can be cancelled while processing by pressing the red “X” button on the Chip & PIN terminal. A transaction is automatically cancelled if the transaction process takes too long,is stuck at one point or if the payleven app is forced to shut down.

  Once a transaction has been processed it can no longer be cancelled but a refund can be issued. Hence, as long as the transaction is cancellable the payleven app is shown. Therefore it is not required to be able to cancel a transaction from the integrator app.

• I can’t process transactions when the developer setting “Mock-location” is activated. Why?

  For security reasons we do not allow you to start the payleven application if the mock location is “On”. Once you have turned it off, you should be able to login the payleven app again.

• Is it possible to connect the Chip & PIN terminal to an android tablet equipped with a phone chip?

  Yes. The phone chip is a non-discriminatory criterion.

Web

• How does the web API work?

  The payleven app can be opened through your web application running in a browser on your mobile device (iOS or Android). It can be either the iOS or Android payleven app, depending on where your browser is running on. It is important that the payleven app is installed on the same mobile device where the payment is initiated so that you can login and are able to start accept card payments. As soon as the transaction is finished the user returns to your web application with the result of the respective payment.

• Which programming languages / frameworks can I use to integrate payleven mobile web API?

  In general you can use any language / framework you want as long as you generate a URL call as the payleven PHP example app does. The example app can be found in the API package which you will receive after your registration on the payleven developer page.

• What is the callback path and the domain?

  The URL callback path is your own website and can be configured in the API. Please enter the path that is used to receive the response from payleven.

  For example the path for the URL "http://example.payleven.com/exampleforapi/result.php" would be "exampleforapi/result.php" and the domain would be example.payleven.com (without http://).

• Is there a method in the API for querying the payleven app in order to check whether the Chip & PIN terminal is ready for accepting payments?

  Please refer to the same question in the respective section - iOS or Android - depending on what kind of device you are using.
  If you need any help connecting the Chip & PIN terminal to your device please have a look at our online manual or contact our customer service.

• Can I cancel an ongoing transaction through the API with an extra call?

  No, a transaction can only be cancelled within the payleven app. Once a transaction is started, it can be cancelled while processing by pressing the red “X” button on the Chip & PIN terminal. A transaction is automatically cancelled if the transaction process takes too long, is stuck at one point or if the payleven app is forced to shut down.
  
Once a transaction has been processed it can no longer be cancelled but a refund can be issued; as long as the transaction is cancellable the payleven app is shown. Therefore it is not required to be able to cancel a transaction from the integrator app.

Printing receipts & refunds

• Does payleven offer email receipts and can I integrate them into my app?

  For every transaction (and any payment method) you can provide your customer with an electronic receipt via email. Once you have finished the transaction with payleven simply choose to send the receipt and ask your customer to provide his/her email address. There’s no need for extra integration here, you have this feature right away once the payleven API is integrated.

  Even customers who completed transactions months ago can have their receipt resent. Just call the payleven app with openTransactionDetails .

• Can I print receipts with the API?

  Printing receipts is not a problem at all. Either you can print them directly in the payleven app right after the transaction has been processed or in the transaction history of the payleven app. 
Compatibilities to which printer the payleven app can be connected can be found in the FAQ in the Receipts and Printers section.

• Can I skip the receipt screen after the transaction has been finished and return to my app immediately?

  The receipt screen cannot be skipped at the moment.

• Can I refund transactions with the payleven API?

  Refunds via the API are possible for all platforms: iOS, Android and Web. 
In order to start a refund, you have to call the respective method of the payleven API. 


  • openTransactionDetails -  For Android
  • openTransactionDetailsForRefund - For iOS
  • getRefundURI – Web

  
  The app will not immediately start a refund but will open up a detail view of the transaction instead. The user must then confirm the refund by explicitly pressing the refund button. To authorise the refund, the merchant has to enter then his four digit PIN that must be set within his merchant account prior to the refund. Depending on your customer's bank, he or she will receive the refund in their bank account within a couple of days after the refund has been initiated.

• Is it possible to disable the refund feature, either in the app or at the authorization stage?

  If you are not interested in refunds you can simply ignore the implementation of the respective method of the payleven API. This way users of your app cannot trigger a refund in your app.
  
Alternatively you can switch off the refund privilege for subaccounts so that they cannot process refunds. You can configure this either in the app or in your web account.

• Can I cancel a refund?

  Refunds cannot be cancelled. Because of the explicit action required to trigger a refund and the requirement of authorizing it via PIN code, it shouldn’t be necessary to cancel a refund.

  In case you still need to cancel a refund you would need to make a new transaction and charge your customer again.

Testing

• Is there a sandbox mode so that I can try out the solution?

  Currently the API does not provide a sandbox mode. Although, once you have obtained the API you can try out the payleven API with an example app which is part of the package.

  
Please note that:

  • The payleven app has to be installed on your mobile device (iOS or Android) in order to test the example app.
  • You need to be a regular payleven user in a country that payleven operates in.
  • Do not change the API key that is used in the example app. For integrating your own app you will need to use the API key that you received after your registration for a developer account.

• How can I test my integration of the payleven API?

  In order to test your integration, please pay attention to the following points:

  • Install the payleven app on your mobile (iOS or Android) device.
  • Make sure that you are using your own payleven API key which has been provided after your registration on the payleven developer page.
  • Create a payleven merchant account which you can use to login in to the payleven app. 
See the list of countries which are supported by payleven and register for the respective one which pertains to your location.
  • Make sure that you have entered and verified your bank details in your payleven web-account.
  • If you choose Chip & PIN for payment method please remember to activate your Chip & PIN terminal in your web-account if you have bought it in a retail store.

• Is it necessary to purchase a Chip & PIN terminal for a first test run of the integration or the example app?

  No, you can use payment methods that don’t need a Chip & PIN terminal, e.g. cash payments don’t require any hardware. With this payment method you can go through the transaction flow similar to a card payment process. Furthermore, you can check all calls provided by the API and check for proper results.
  
However, please keep in mind that for a valid and thorough test, a Chip & PIN terminal is indispensable.

• How can I test my integration or the example app without my card being charged?

  There are various ways available to avoid your card being charged permanently.

  1. Even if you are doing a complete credit or debit card transaction, you are still able to refund the transaction amount afterwards, so you are not spending money. This is possible in the app, API and your payleven web account. Note that the transaction fees cannot be refunded.
  2. Alternatively, we would recommend cash payment for testing purposes. All steps are basically the same as per credit card, only the activities on the Chip & PIN reader are not involved.
  3. You can also use an old/expired card which doesn't work anymore, enter the PIN and you will receive a transaction declined message. This way you can run an end-to-end test of your integration.
  4. A similar result can be achieved by starting a Chip & PIN transaction and cancelling it before entering the PIN or signature. Note that your bank will reserve the entered amount for a couple of days.

• Why do I have to provide my bank details?

  This is required to activate your payleven merchant account. Once activated in your payleven web account, you can accept card payments after which, the tendered amount is transferred to your provided bank account. Please note that you also need to confirm your bank details in order to process a test transaction. For this purpose, payleven has transferred a monetary deposit into your bank account, which should be entered with the transfer reference that comes with it in your web account to verify the bank details that you have already provided.

  The amount and the transfer reference should be visible on your bank statement, the reference code will start with "PL" followed by 8 characters, like “PLJ7N3QD8Z”. To quickly identify the transfer you should search for a reference starting with “PL”.

• Is it necessary to provide my bank account details in my user account so that I can test my integration or the example app?

  For the example app which is part of the API package, it is not required at all.
 For the integrated API it is not necessarily required since the payleven app also allows you to accept cash payments. With this payment method you can go through the transaction flow similar to a card payment process. Furthermore, you can oversee all calls provided by the API and check for proper results.
  
However, it is highly recommended that you run a full test with real card payments as well. For this purpose your bank details would be required.

Errors & troubleshooting

• I can’t login to the payleven app. What can I do?

  • Have you registered as a regular user on one of the payleven country pages which pertains to your location? In case you’ve only registered on the developer page, please sign up on one of the payleven pages corresponding to the country where you or your business is based in.
  • Ensure that you have a stable internet connection.
  • Make sure that there is no ongoing transaction initiated from your own app.
  • For android, make sure that “Mock-location” is turned off in your phone settings.
  • Reset Password in case the login data seems to be wrong.
  • Contact our customer service.

• I receive the error “API_KEY_NOT_FOUND”. What should I do?

  • Please make sure that you use your own API key received via mail after the registration on our developer page and not the one which is provided in the example app of the downloaded API package. For the example app you should have the example API key unchanged.
  • Note that one API key can be used only for one application. Please register with the full amount of apps you would like to integrate payleven with on our developer page.
  • Make sure that your unique API key is correctly combined with your
-
    • bundle-ID for iOS 

    • package name for Android 
    • domain for the mobile web API.

• I get an error message “Signature invalid (102)”. What is wrong?

  This is related to the combination of your unique API key and the associated bundle ID, package name or domain, depending for what platform you’ve registered (iOS, Android or mobile web). In case this error comes up the API key and/or the other detail or both is incorrect.

• PaylevenApiDemo displays: "Payment could not be started check your input values. “ What should I do?

  If this error shows up, it is for one of the following reasons:

  • The payleven app is not installed
  • The given payment amount is zero or contains characters other than numbers
  • You have an unfinished payment waiting in the payleven app, which should be finalized first
  • Your description or order ID cannot be converted into UTF-8

• I received an error “PAYMENT_ALREADY_EXISTS” in PaymentCompletedStatus. What should I do?

  This error means that a payment with the same order ID has already been made. You have to ensure that you provide unique order IDs when starting a transaction.
If a transaction is cancelled during the card authorization phase, for example by pressing the cancel button, removing the card too soon or any other scenario, you won’t be able to re-use the same order ID because the payleven app rejects it with the PAYMENT_ALREADY_EXISTS error.  You can avoid this error by adding a suffix to the original order ID.

• I cannot pair my Chip & PIN terminal with my device. What can I do?

  Please refer to the payleven manual page or contact our customer service.

• I receive an error – “Required fields missing in response (hmac)” - after doing the payment and coming back to my website. What should I do?

  Please check whether you’ve entered all your data and if the variable hmac is in the URL on the respective page.
  Take a look at our example and documentation. In order to ensure a successful integration you need to fill in your values in the file Library/paylevenWebAppApi. example.conf.
  
  APP_RETURN_SCHEME = https
  APP_RETURN_DOMAIN = example.payleven.com
  APP_RETURN_PAGE = "/external/return_pin_payment.php"
  APP_TOKEN = YourApiKEY
  APP_DISPLAY_NAME = YourWebsiteName
  
  If you then start a payment through the payleven app as in our example (take a look at Example/index.html and Example/paylevenPaymentExample.php) it generates a correct HMAC, calls the payleven app and after the transaction opens your return page (as specified above).

• The payleven app shows the “payment is in progress” and I can’t start another payment. What should I do?

  The payleven app doesn’t allow multiple transactions in parallel no matter where the transaction has been initiated; the integrator app or the normal payleven app. You must finish a payment completely before starting a new one. This means that you need to cancel the transaction, print/send a receipt, return to the integrator app or continue to the "New payment" screen.

Didn't find the right answer?

We're always happy to help out with your integration or any other questions you might have related to the payleven API. Learn more.
In case your question is more general about the payleven product have a look on our general merchant faq or contact our customer support.