Package: pyconiq
UnofficialasyncPython module to interface with the payment processorPayconiq.Introduction[!WARNING]
This is an initial PoC and integration of the module. The API will most likely change in future releases.InstallationThe module can be directly installed through pip:pipinstallpyconiqFor development purposes, and once the project cloned or the codespace ready,
you can install the project
dependencies. You can use thedevextra to install the development
dependencies.poetryinstall--with=devOr using pip:pipinstall-e.[dev]Getting startedBefore you can integrate your application withPayconiq,
you need access to a so-calledMerchantprofile. The process of onboarding with
Payconiq, both for their development (EXT) and production (PROD) environment
involves opening a support ticket (e-mail) and exchanging some information to setup
your account. In particular, your mobile phone number, address, Tax ID (if availablef),
and company name amongst others. The onboarding procedure is outlinedhere.[!IMPORTANT]
You will have to provide adefaultcallback URL to the support team that Payconiq will use to send updates regarding payment requests and transactions.Once onboarded by the support team, you'll most likely have access to theEXTinfrastructure. This means you have access to the necessary API keys and unique
merchant identifier. In the wild, the most common integration a consumer will experience
(we think) is theStatic QRcode integration. This QR code is uniquely tied to a
specificPoint of Sale(PoS) of a merchant. Meaning, a Point of Sale is uniquely
identified by the tuple (Merchant ID and PoS ID), the latter is inyourcontrol.Environment variablespyconiqsupports to inject several runtime defaults through environment variables.
This is especially useful when targetting theEXTinfrastructure compared to thedefaultPRODinfrastructure.VariableDefaultContextPYCONIQ_BASEhttps://payconiq.comBase endpoint of Payconiq.com.PYCONIQ_API_BASEhttps://api.payconiq.comThe primary API endpoint of Payconiq (or some mock service). By default this variable will target the Payconiq production environment. For theEXTenvironment this variable should be set tohttps://api.ext.payconiq.com. Note that setting this environment variable is not necessary. It can be defined in the codebase when allocating specific integrations.PYCONIQ_DEFAULT_MERCHANTNoneDefault Merchant ID that will be used when allocating merchants.PYCONIQ_API_KEY_STATICNoneDefault API key for the Static QR code integration.PYCONIQ_API_KEY_INVOICENoneDefault API key for the Invoice integration whenever no key is manually specified.PYCONIQ_API_KEY_RECEIPTNoneDefault API key for the Receipt integration whenever no key is manually specified.PYCONIQ_API_KEY_APP2APPNoneDefault API key for the App2App integration whenever no key is manually specified.PYCONIQ_PAYMENT_PROFILE_STATICNonePayment profile identifier of the Static QR code integrationExampleFirst, before you use theStatic QRintegration, you need a QR code for your customers to scan. You can obtain this QR
code through Payconiq's API. However,pyconiqprovides a utility to generate
this on the fly for you, with various error correction levels and customization options.
This functionality is powered by the awesomeqrcodemodule.[!TIP]
Note, the default merchant identifier and the default payment profile for the static can be set through thePYCONIQ_DEFAULT_MERCHANTandPYCONIQ_PAYMENT_PROFILE_STATICenvironment variables respectively.importpyconiq.qr# Assign a unique identifier to your point of sale.# This is managed by us, the merchant.point_of_sale_id="test"# Set your merchant configuration, this will implicetly use the# `PYCONIQ_DEFAULT_MERCHANT` environment variable for populating# the merchant identifier.merchant=pyconiq.merchant()# Alternatively, the merchant can be generated as.merchant=pyconiq.merchant(merchant_id="YourMerchantIdentifier")integration=StaticIntegration(merchant=merchant,profile="YourPaymentProfileId)# Second, we need a QR code that is associated with our PoS (point of sale).# In this case, the identifier of the PoS is `test`.qr=pyconiq.qr.static(integration=integration,pos=point_of_sale_id)# Show the QR code in the terminal.qr.print_ascii(tty=True)this produces the following QR code (in your terminal) for our test Merchant;█▀▀▀▀▀▀▀██▀██▀█▀███▀█▀█▀▀▀▀▀▀▀██ █▀▀▀█ █▀▀ ▄ █▀ ▄███▀█ █▀▀▀█ ██ █   █ ██▄ ▄█▄ ██▄  ▄█ █   █ ██ ▀▀▀▀▀ █▀▄▀█▀▄▀▄▀▄▀▄▀█ ▀▀▀▀▀ ██▀▀▀█▀▀▀▀ ▄ ▀▄▄▀▀█ ▄ █▀▀███▀██████▄▀ ▀▀▀█▀▄▄█▀██ █ ▄▄▄▄█▄██ ▀██▄▀   ▄▀█ ██▄▀██▄ ▄▀ ▀▄█▀█ █▀▀█████▄█▀▀█▄▄▀  ▄▀█▀█   ▀███▀   ██  █▀▀▄▀▄▀▀▀▀▄▄ ▀▄█▀ ▄▀█▄█▀ ▄▄██▀▄▀█▀█▀▀▀  ▄█▀▄▄  █▄█▄▄  █▀▄▄██▀▄▀  ▀▀▀▀ █▄▀██ █  ▄ ▀▀▀ ███▀██▀▀▀▀▀▀▀█ ▄▄  ▄▀▀ █▀█ █▀█ ▀▄█ ██ █▀▀▀█ █ ▄▀▀▄▄ █▀▄█  ▀▀▀ █ █▄██ █   █ █▀ ▀▄█▀▄▄ █▄▀  ██ ▄▀█▀██ ▀▀▀▀▀ █ █▀▄▀██▀▀▄█▄██ █▀▀ ▄ █▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀Once the QR code has been generated, we can now create payment requests (which we
call transactions internally). Such requests are allocated through "Integrations".
For this particular type, we're using aStaticIntegration, which corresponds to the
integration supported the previously generated static QR code.# Initiate a payment request with a static QR integration.transaction=awaitintegration.create(amount=2000,# IMPORTANT: Amount is in Eurocentpos=point_of_sale_id,reference="PYCONIQ TEST",# Reference that will appear as a reference in the bank log.)[!TIP]
You can specify custom Callback URL's using thecallbackparameter when creating transactions.At this point, the transaction has been allocated and is currently in aPENDINGstate.
For the Static QR integration, transactions remain in aPENDINGstate for about 2
minutes before expiring. Updates regarding payment information will be provided through
the callback URL. However, if you're simply testing locally, you can poll the status
of the transaction like this:#Just scan the QR code now.whilenottransaction.terminal():# Is the transaction in a `terminal` state?awaitasyncio.sleep(1)awaittransaction.update()iftransaction.expired():print("Failed to pay on time :(")eliftransaction.succeeded():print("Paid!")eliftransaction.cancelled():print("The transaction was cancelled!")else:print("Some other status :/")[!IMPORTANT]
The infrastructure supporting the External build is switched off each day from 21h30(CET) to 6h00 (CET) and during the weekends from Friday 21h30 (CET) until Monday 6h00 (CET).Detailed information regarding the Payconiq's API specification can be foundhere.RoadmapCurrently, only theStatic QRcode integration is supported.
In the near future,
we intent to support theInvoiceintegration.