Payconiq API Reference Guide

The Payconiq Developer Guide serves as the primary technical reference document for merchants, partners and other stakeholders using the Integration APIs to accept Payments via the Payconiq platform.

Payconiq simplifies mobile payments in stores, online and between friends in a world that has become increasingly digital. Payconiq is committed to digitizing and simplifying the payment landscape. Payconiq is able to execute payments quickly and effectively because it maintains a relationship with both the consumer (the app user) and the merchant or partner.

This video provides more information about What Payconiq is.

W3Schools

For more information on the Payconiq privacy & cookies statement please click here.

Why Payconiq

  • Payconiq is easy to use for everyone.
  • Payconiq offers an omni-channel payments solution for merchants, partners and consumers with valued added services where applicable.
  • Payconiq is safe to use by adhering to and implementing the latest security standards.
  • Payconiq is usable in multiple European countries – One app & one integration for multiple countries.

Payconiq Product Overview

Payconiq is a payment solution where customers scan branded Payconiq QR codes with the Payconiq app and confirm or authorize transactions. A QR code is a machine-readable code consisting of an array of black and white squares, typically used for storing URLs or other information for reading by the camera on a smartphone. The QR codes maybe static or dynamic and can be displayed in the store (Payconiq Instore), online (Payconiq Online) and/or on an invoice (Payconiq Invoice).

For the purposes of this document, we shall be focusing on solutions that are integrated and available. The following implementation options will be the focus of this API document:

  • Payconiq Instore (On a terminal or on a display).
  • Payconiq Online (Widget, App2App, Custom on a website check-out page).

Payconiq Instore

This type of solution is suitable for merchants with physical presence in one or more locations and want to offer the Payconiq payment option to its customers. The Payconiq QR code may be displayed on a terminal or on a display (customer facing) for customers to scan and confirm a payment with the Pacyoniq app. Amounts and descriptions of the purchase are passed automatically to the Payconiq App and the user simply confirms the payment with a pin, fingerprint or face id if supported. The merchant can fetch the status of the payment or is automatically notified of the status to complete the purchase.

Payconiq Online

This type of solution is suitable for merchants with online presence where they offer goods and services to their customers. The Payconiq QR code can be integrated via the Payconiq widget, custom web implementation (on a website or any web interfacing application) or App to App via a shareable link. Once implemented, customers can scan a Payconiq QR code and confirm a payment using the Pacyoniq App. Amounts and descriptions of the purchase are passed automatically to the Payconiq App and the user simply confirms the payment with a pin, fingerprint or face id if supported. The merchant can fetch the status of the payment or is automatically notified of the status to complete the purchase.


Getting Started

In order to get started, the following activities and necessary access will be arranged.

Merchant Onboarding

This is the process of setting up merchants on the Payconiq platform in order to interact with the API endpoints. As part of the onboarding process, you will receive a generated unique Merchant Identifier and an API key which will be used when interacting with the Payconiq endpoints. This will be shared via mail.


Environments

There are two environments where merchants and partners are exposed to. The External Environment (EXT) and the Production Environment (PROD).

External Environment

This is a pre-production environment where all tests and integration work are carried out. We recommend a sign off is granted on this environment before moving to the production environment. All tests performed with the test accounts never hit the production or real banking environment.

Production Environment

This is the environment where real transactions take place. Once onboarded and transactions take place, please note that app user accounts will be debited, and merchant accounts will be credited.


Merchant Portal

Once the merchant has been onboarded, the merchant is able to view all transactions on the Payconiq merchant portal with the following URLs.

EXT Merchant Portal: https://portal.ext.payconiq.com/login
PROD Merchant Portal: https://portal.payconiq.com/login

Note: It might be that access to the merchant portal on EXT is blocked for security reasons. This is because Payconiq is not active in the country from which the merchant is requesting access. A VPN connection may be setup to be able to access the EXT merchant portal.


Payconiq Apps for Testing

Once integration is completed, test apps for Android and iOS can be downloaded and setup in order to perform test transactions and to validate the integration end to end.

Please note that there are two test apps. One for EXT and another for PROD. The App you use has to correspond to the environment on which you created the QR code.

The EXT Payconiq app is available on request from your Payconiq account manager.

The PROD Payconiq app can be downloaded via the Apple App Store and via the Google Play Store.

Some steps to follow and potential issues that might occur when you try to install the Payconiq EXT App are as follows:

  • Trust the app – you can do this via the settings on your mobile phone.
  • You have to open the link to your Payconiq app on your mobile phone for the OS system requested.
  • While setting up, if you do not receive the verification SMS for EXT, you can always use 99999 on EXT. This is the default code.
  • Use a random IBAN and manually enter it in your app. You CANNOT link it to your bank app on EXT.
  • You have to have an address and IBAN of a country we are active in.

You may also contact us on devsupport@payconiq.com for further assistance.


Payconiq Settlement and Remittance

To receive settlements for Payconiq payments, Payconiq pays out all payments to the IBAN specified during the onboarding process. These payouts are always via SEPA Credit transfers and are comprised of only consumer payments.

When you start accepting live Payconiq payments, you receive payouts if the status of a payment is SUCCEEDED. You can view all SUCCEEDED payments from the Merchant Portal or via the API endpoint that can list all the payments.

Bank Statement Description

Please note the following points that apply to the bank statement of the merchant and consumer.

  • The description field of the Create Transaction API can be used to populate the remittance information for reconciliation or customer information.
  • For the Widget implementation, the webhookId can be used to populate the remittance information for reconciliation or customer information.
  • The total number of characters for remittance information is 140 characters. The remittance information is shown on the bank statements of the merchant and consumer.
  • Payconiq prepends the following details to your remittance information:

    By Payconiq " or "Van: {ConsumerFirstName}: "

    ConsumerFirstName has a maximum limit of 40 characters.

  • For consumers onboarded via a Payconiq Partner bank (SCT):

    "By Payconiq " is prepended to the description or webhookId.

  • For consumers onboarded via a SEPA Direct Debit mandate (SDD):

    "Van: {ConsumerFirstName}: " is prepended to the description or webhookId.


The Payconiq QR Code

The Payconiq QR code is branded with our mark. The branding gives trust and makes it easy for our users to see where they can pay with Payconiq. Instead of black we use our darkest shade of magenta for the QR-code to match our primary colour but still keeping the contrast.

The Payconiq QR code can be rendered in a web view container for quick scanning. A link is returned anytime a payment is created and can be easily rendered in a web view. This url makes use of Payconiq’s QR code generation service. By default, the Payconiq QR code is returned as a PNG with a small (S) size.


Sample Payconiq QR Code QR Code

Payconiq QR Code Sizes and Scan Distances.

  • Payconiq recommends the following Payconiq QR Code sizes and scanning distances when displaying the Payconiq QR Code.
  • Take note of the scanning distance in order to use the correct Payconiq QR Code size.
Recommend Size Pixels Scanning Distance
Small (S) 180x180 pixels 15 cm
Medium (M) 250x250 pixels 20 cm
Large (L) 400x400 pixels 30 cm
Extra Large (XL) 800x800 pixels 40 cm


The Payconiq Pay Button

There are two ways to display a Payconiq payment button on a payment/check-out page for an online payment.

1. Preferably, the complete logo.

Payconiq Logo

Minimum height: 20 pixels (40 retina pixels)
Minimum width: 120 pixels (242 retina pixels)
Minimum height: 4 mm

Description Image Format
Payconiq Logo 363 x 60 pixels PNG
Payconiq Logo 242 x 40 pixels PNG
Payconiq Logo 182 x 30 pixels PNG
Payconiq Logo 120 x 20 pixels PNG
Payconiq Logo SVG


2. If you have limited space available for the payment button, you can show only the Payconiq mark. Make sure to add the word 'Payconiq' next to it then.
Below is an example of how it is used.

Payconiq Mark

Minimum height: 14 pixels (40 retina pixels)
Minimum width: 31 pixels (242 retina pixels)
Minimum height: 3 mm

Description Image Format
Payconiq Mark 93 x 42 pixels PNG
Payconiq Mark 62 x 28 pixels PNG
Payconiq Mark 47 x 21 pixels PNG
Payconiq Mark 31 x 14 pixels PNG
Payconiq Mark SVG

You can request a white Payconiq logo for pages with backgrounds in dark colours via devsupport@payconiq.com.

Note:

  • If the resolution is lower than the screen resolution please use the SVG instead of the PNG to keep a sharp image.
  • In case any of these sizes are not compatible with your setup please get in touch via devsupport@payconiq.com for further assistance.


The Payconiq API

The Payconiq API is organized around REST and uses HTTP response codes to indicate API errors. The standard HTTP features such as header authentication and HTTP verbs which are understood by off the shelf HTTP clients across all the programming languages. JSON is returns by all API responses, including errors. The code snippets on the right sidebar are designed to guide developers and work as is.

Authentication

All requests to the Payconiq payment system are authenticated by including your API keys. Your API key grants extensive access rights, so please make sure to keep them secure. Do not share your API keys in public areas such as online sites or client-side code.

The API key is set in the header of the URL requests via HTTP Authorization header. You do not need to provide a password. All API requests must be made over Https. Any calls made over unencrypted Http will fail. Wrong API keys or API requests without API keys will also fail.

To receive an API key, a formal request has to be raised with a Payconiq account manager who will ensure that the correct access is provided.


Merchant Callback

Each merchant needs to define a specific URL to their backend via which Payconiq notifies you of the status of a payment. The URL may contain a webhookId which makes it easy for you to further identify the callback in order to process. An example would look like this: (e.g., www.merchantbackend.com/pqtransaction.php?webhookId=123456).

The use of callbacks allows the merchant’s backend to react to the payment and process the data (mark the transaction in database, update the product count number, send an email to the customer, etc).

Since callbacks are asynchronous, their order is not guaranteed. Since anyone can theoretically POST an HTTPS payload to an endpoint, Payconiq signs the request and sends it over a HTTPS (SSL/TLS) connection to the endpoints.

Event headers of the callbacks contain the generated asymmetric signature and information that you can use to validate the signature. The JSON-formatted POST notification contains callback information. When the merchant endpoint receives the notification message, it must respond with a HTTP 200 status code.

If the endpoint is unavailable or takes too long to acknowledge receipt of the notification, Payconiq cancels the call and tries to resend the notification message up to two times per transaction. This is done in 5 and 7 second intervals.

When the callback is received, the merchant endpoint must verify that:

  • Callback message originated from Payconiq were not altered or corrupted during transmission.
  • Callback message is sent to the intended target endpoint.
  • Callback message contains a valid signature.


Callback headers





X-Security-Signature: uSmNARMiW/Ds4Q7n+uk9K+u4GRVoSENopIhTrmpEowu8ENZ/jYXI+WLIs+Zit6TALdzmNj2HFW93aaK3/CfTR8oX2bnrNsOH0GqInu+ND3zHfUuSbsGIoOOqLTW1AG5e9Qyujj2HB95SdYLVLyGSVitVOgzCFzx/I0vjIywc9Zv9aoyzUGnppsQxanCNwB0XBI3ODWKQlzakqv9IB+nXFHTrGquyPwuqUj0kbGQfIJn4OwTqtZVf/USsb4aEX7RyLqEOjc2xpFTZJU4FikRbed12Sz42awa4VdtbjnG5Rmyfg0Fk1kFuW0RQRRqECQuygGtbA0Ma90Hr9dmTd/bz+Q==



X-Security-Key: https://dev.payconiq.com



X-Security-Timestamp: 2018-05-15T15:31:35.241Z



X-Security-Algorithm: SHA256WithRSA



User-Agent: Payconiq



Content-Type: application/json

The signature can be validated by using the information in event headers which are made up of the following:

Attributes Description
X- Security -Signature
[string]
The Payconiq-generated asymmetric signature using the algorithm specified with the X-Security-Algorithm.
X-Security-Timestamp
[string]
When the request/event was generated.
X-Security-Key
[string]
The X509 public key certificate from Payconiq. It is used to verify the signature (this will be different for the different EXT and PROD environments.
X-Security-Algorithm
[string]
The algorithm that Payconiq uses to generate the signature and that you can use to verify the signature.
User-Agent
[string]
The User-Agent request header contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.
Content-Type
[string]
The Content-Type entity header is used to indicate the media type of the resource.

To generate the signature, Payconiq concatenates and separates these items with the pipe (|) character. You can validate a signature through this input string: merchantId|timestamp|crc32 crc32 – is Cyclic Redundancy. Check the checksum for the body of the HTTP payload.


Callback body







{"_id":"5afafd466a940213568928ad","status":"SUCCEEDED"}

The body is in JSON format with two additional fields: Payconiq’s unique transaction ID and the transaction status. A transaction ID is represented by a 24-character hex string. It contains no empty spaces.

Attributes Description Comment/Format
_id
[string]
Payconiq’s unique transaction ID. 5afafd466a940213568928ad
status
[string]
The status of the transaction. PENDING,
CONFIRMED,
SUCCEEDED,
CANCELED,
CANCELED_BY_MERCHANT,
FAILED,
TIMEDOUT,
CREATION
externalRefId
[string, optional]
The external reference id of the transaction.


Transaction Status

Below is the list of status’s that can be returned in the body of the callback request to the merchant or integrator.

Status Name Status Description
PENDING The transaction is waiting for confirmation from the user.
SUCCEEDED A transaction was confirmed by the user and approved by the user’s bank.
CONFIRMED The transaction gets confirmed once the Payconiq validation has been successfully finalized. You may consider the transaction as successful with this status.
CANCELED When the user cancels a transaction after scanning it.
CANCELED_BY_MERCHANT When the merchant cancels the transaction.
FAILED Something went wrong during the payment process (Eg: wrong PIN provided by a user or insufficient balance).
TIMEDOUT If the user for some reason still has not paid after 2 minutes.
CREATION The Payconiq payment flow has been initiated.

The main status names that are most important to the implementation are as follows and have been described above.

  • SUCCEEDED
  • FAILED
  • TIMEDOUT
  • CANCELED

Other status names that can also be returned when the transaction status is obtained are as follows.

  • CREATION
  • PENDING
  • CONFIRMED
  • CANCELED_BY_MERCHANT


Validating Callback Signatures

Command:

openssl s_client -connect dev.payconiq.com:443 -showcerts | openssl x509 -text

Public key command for the certificates for the EXT and PROD environments.

EXT: dev.payconiq.com:443

PROD: api.payconiq.com:443

To prove that Payconiq generated the callback to the merchant, the Payconiq API sends additional header information which contains the signature of the callback. The Payconiq API uses its own certificate (private key) to sign the callback. The certificates can be retrieved using the command to the right.

Payconiq recommends programmatically fetching the certificate to validate the signature. You should check the X-Security-Key value in the header of the callback in order to identify which url to download the certificate from.

To validate the signature, the public certificate is used and only when successful is the callback response processed. Code snippets for different programming languages on how to validate the signatures can be found on the following link: https://github.com/payconiq

It is important to confirm that the signature is valid before processing the callback. This is to ensure that the payment data returned has not been tampered with and has been processed by Payconiq.


Rotating Payconiq Certificates

Payconiq reserves the right to rotate the certificates used to generate the callback signature. In view of this, Payconiq recommends programmatically checking for a new certificate anytime your callback validation fails as a first step.

Subesequently if the callback signature validation continues to fail, you should GET the transaction details to know the status of the transaction. Please refer to the API implementation here to see how this can be done.

You should check the X-Security-Key value in order to identify which url to download the certificate from.

For example the X-Security-Key for the Dev environment callback has value https://dev.payconiq.com. While using the openSSL command to extract the certificate key, the host to connect becomes dev.payconiq.com:443.


See below current certificates and their corresponding expiry dates.

Certificate Environment Expiry Date
Prod Certificate
api.payconiq.com:443
17th April 2019
Dev Certificate
dev.payconiq.com:443
16th February 2021


Errors

The Payconiq API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate malformed client request (e.g., a required parameter was omitted, a charge failed, etc.) and codes in the 5xx range indicate an error with our servers.

Some 4xx errors that could be handled programmatically (e.g., a transaction decline) include an error code and a description that briefly explains the error reported.

HTTP Status Codes

Below are the status codes and descriptions returned as part of the callback response.

Status Code Status Code Description
200 - OK When transaction request is processed successfully, and everything works as expected
201 – Created When a request was successfully processed, and a transaction was created
400 – Bad Request This occurs while trying to create an entity without providing all the required fields
500 – Server Errors Internal server error


Error Object

Below contains the body of the JSON error returned.

Attribute Description
code
[string]
An error code used to identify the error
message
[string]
Error message describing the error
params
[string, optional]
Parameters involved in the error


Error Codes and Descriptions

Below is the list of possible errors as well as the messages sent along with the code.

Error Code Description
R002 Transaction field 'currency' only supports EUR, currently
R003 Transaction field 'amount' is null or not a decimal number
R004 Transaction field 'currency' must be provided
R013 Transaction 'originId' is unknown by the system
R017 Transaction amount must be greater than 0
R200 The origin IBAN is the same as the target IBAN
R201 Transaction origin user does not possess transaction origin IBAN
R203 Transaction origin user bank account is blocked and cannot be used
R204 Transaction target user does not possess transaction target IBAN
R205 Transaction target user bank account is not validated yet and cannot be used
R221 Transaction target user bank account is blocked, it cannot be used
R602 Authentication token is expired
R918 Token not found
R934 Only a PENDING transaction can be canceled
R957 Blocked account
R967 API endpoint call with wrong method
R969 API endpoint call with wrong Content-Type
R981 Security exception
R979 Security exception : missing or unknown token
R999 Internal Server Error


Handling Errors

The Payconiq API libraries send back error statuses for many reasons such as failed charge, invalid parameters, authentication errors, timeouts etcetera. We recommend writing code that gracefully handles all possible API errors.


Payconiq API Implementation

The Payconiq API can be implemented in the following implementation options.

Payconiq Instore - Terminal or Display

The Payconiq QR code can be displayed on a payment terminal, on a customer facing display or online via web checkout. Merchants and partners integrate with Payconiq API’s in order to facilitate payments. The following process flow will be followed in order to complete the implementation.


Process Flow

Involved Parties:

  • Payconiq App – Payconiq consumer application.
  • Merchant Frontend – POS terminal or Customer facing display.
  • Merchant Backend – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

Instore Process Flow W3Schools


Step by step transaction flow

  • Merchant frontend sends transaction creation details to Merchant’s backend. This will contain at least the transaction amount.
  • Merchant backend sends a REST request to the Payconiq backend to create a transaction. The parameters passed in this request are the transaction amount, transaction currency, transaction description and a callback url.
  • Payconiq backend sends a create transaction response with the Payconiq transaction id to the Merchant backend.
  • The Merchant backend sends the transaction id to the Merchant frontend to display the payment as a QR code.
  • Payconiq App scans the QR code in order to start the payment for the amount displayed. A request for transaction details is sent to the Payconiq backend for the transaction.
  • Payconiq backend sends the transaction details to the Payconiq App which would contain the name of the merchant and the amount to pay.
  • The user confirms the payment by entering his/her pin. A payment transaction request is sent to the Payconiq Backend for authorization.
  • A payment transaction response with the details is sent back to the Payconiq App indicating a success or failure of the transaction.
  • Payconiq backend sends a payment transaction notification to the Merchant backend with the transaction details via the callbackURL. The details of the notification will either contain success or failure details.

NB: The order of consumer and merchant notification is not sequential. One may arrive before the other depending on internet and network connections.

Prerequisites

Before implementing the above process flow, you should have received the following information from Payconiq and provided a callback url:

  • API Key – This is used to secure the request between the merchant’s backend and Payconiq’s backend. Do not share your API keys in public areas such as online sites or client-side code.
  • Merchant CallbackUrl – This URL will be called by Payconiq’s backend servers in order to send the status of the transaction to the merchant. See above full requirements of the Merchant Callback.

If the required information is not available, please send us an email on devsupport@payconiq.com for assistance.


Implementation

Please follow the below steps to successfully implement the Payconiq API in your payment terminal or customer facing display.


Create Transaction

In order to begin a transaction, a merchant needs to create a transaction from its backend via the Payconiq backend through an Https Post request. A transaction id is valid for two minutes after which it cannot be used. If a payment does not take place within these two minutes, a new transaction id has to be requested.

EXT URL Definition: https://dev.payconiq.com/v2/transactions

PROD URL Definition: https://api.payconiq.com/v2/transactions

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json






Example Request:
curl -X POST \
  https://dev.payconiq.com/v2/transactions \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
               "amount" : "1",
               "currency" : "EUR",
               "callbackUrl": "https://prd/dummy.network/api/v1/orders/payconiq?webhookId=123456",
               "description": "Test transaction 12345",
               "externalRefId": "12345"
}'


Request Body

Attribute Description Comment/ Format
amount
[string, required]
Transaction amount in Euro cents Ex: 1 – 1 cent
100 – 1 Euro
currency
[string, required]
Currency of the transaction. EUR
callbackUrl
[string, optional]
Callback where Payconiq needs to send the confirmation status.
A webhookId should be passed as part of the callbackUrl
description
[string, optional]
Custom description of the transaction. For reconciliation purposes, details in description field will reflect on the bank statement.
externalRefId
[string, optional]
External reference number of calling party























Example Response:
HTTP/1.1 201 Created
{"transactionId" : "5ae70fc51481ec588ad1ff9d",
"qrUrl":"https://portal.payconiq.com/qrcode?c=https://payconiq.com/pay/1/5ae70fc51481ec588ad1ff9d"}


Response Header

Attribute Description Comment/ Format
Http Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


Response Body

Attribute Description Comment/ Format
transactionId
[string]
Unique Payconiq transaction id. 24 hexadecimal value.
qrUrl
[string]
URL which automatically generates a Payconiq QR code once invoked. url


The Payconiq QR Code

The QR Code can be displayed using the following method.


The Payconiq QR code can be rendered in a web view container for quick scanning. A parameter with name qrUrl returns a link that can be easily rendered in a web view. This url makes use of Payconiq’s QR code generation service. By default, the Payconiq QR code is returned as a PNG with a small (S) size.

Parameter Description Comment/ Format
f
[string]
Image format SVG, PNG
s
[string]
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
S, M, L, XL
This only applies to PNG format

Sample formatted URL

Size: (L) Large

Image Format: PNG

Formatted Url: https://portal.payconiq.com/qrcode?c=https://payconiq.com/pay/1/5c1b589a296e9a3330aebbe0&s=L&f=PNG

Sample QR Code Image QR Code


Payconiq QR Code Sizes and Scan Distances.

  • Payconiq recommends the following Payconiq QR Code sizes and scanning distances when displaying the Payconiq QR Code.
  • Take note of the scanning distance in order to use the correct Payconiq QR Code size.
Recommended Size Pixels Scanning Distance
Small (S) 180x180 pixels 15 cm
Medium (M) 250x250 pixels 20 cm
Large (L) 400x400 pixels 30 cm
Extra Large (XL) 800x800 pixels 40 cm

Note:

  • If the resolution is lower than the screen resolution please use the SVG instead of the PNG to keep a sharp image.
  • In case any of these sizes are not compatible with your setup please get in touch via devsupport@payconiq.com for further assistance.


Processing the Response

Transaction Callback with Webhooks

In order to process a Payconiq callback request, an endpoint has to be provided as described in detail above. This endpoint is provided while creating a Payconiq transaction. The status of the transaction as well as header information will be passed to the merchant backend as a notification. If supplied, a webhook id will be used as a query string parameter and echoed back to the merchant backend.

Event headers for notification messages contain the generated asymmetric signature which should be validated. The JSON-formatted POST request contains event information.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature. This is described with more details above.

The backend must respond with an HTTP 200 OK status code to confirm receipt of the notification. If the merchant backend is unavailable or takes too long to respond or responds with a different status code, Payconiq cancels the call and tries to resend the notification message up to two times per transaction.


Callback Not Received or Signature Validation Fails

In the event where you don't receive the callback or the callback validation fails, you should Get the Transaction Details as described below. Getting the details of a transaction is another sure way to know the status in order to complete the transaction.


Get Transaction Details

Transaction details of an existing transaction may be obtained. A unique transaction id is passed from a transaction creation request and Payconiq will return the corresponding transaction information.

Note: It is recommended to implement this as a fallback option to obtaining the response via the callback URL.

EXT URL Definition: https://dev.payconiq.com/v2/transactions/{transactionId}

PROD URL Definition: https://api.payconiq.com/v2/transactions/{transactionId}

HTTP Verb: GET

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.




Example Request:
curl -X GET \
  https://dev.payconiq.com/v2/transactions/{transactionId} \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \



Request Parameters

Attribute Description Comment/ Format
transactionId
[string, required]
This is passed in the URL of the endpoint. A unique transaction id is passed from a transaction creation request.

Response Header

Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
   "_id": "5ae714d95fa9ad4771cf2624",
   "originIBAN": "NL88RABO8934720099",
   "targetIBAN": "NL39RABO0120295940",
   "targetId": "5ae073975fa9ad4771cf221d",
   "amount": "1000",
   "currency": "EUR",
   "description": "1526309130949",
   "callbackUrl": "https://www.facebook.com/?webhookId=1526309130949",
   "originUser":    {
      "firstName": "Kennedy"
   },
   "targetUser":    {
      "_id": "5ae073975fa9ad4771cf221d",
      "companyName": "Test Merchant",
   },
   "creationDate": 1525093593036,
   "status": "SUCCEEDED",
   "origin": "DIRECT_PAY",
   "endToEndId":"5ae714d95fa9ad4771cf2624"
}



Response Body

Attribute Description
_id
Unique identifier of the transaction
originIBAN
IBAN from which amount is deducted for payment.
targetIBAN
IBAN to which amount is credited.
targetId
Unique identifier of the merchant
amount
Transaction amount in Euro cents
currency
Transaction currency
description
Description of the transaction
callbackUrl
Callback url of the transaction
originUser
firstName
First name of consumer
targetUser
_id
Unique identifier of the merchant
companyName
Name of company
creationDate
Date when transaction was created.(Epoch time)
status
Status of a transaction.
origin
The origin of the transaction. Indicates the type of transaction performed.
endToEndId
The end to end Id of the transaction. This field is the same Id which is present on the bank statement of the merchant or partner for reconciliation purposes.


Get Transaction List

This returns a list of existing transactions sent to the merchant’s account. The list of transactions returned are returned in a sorted order with the most recent transactions appearing first.

EXT URL Definition: https://dev.payconiq.com/v2/transactions/search?limit=2&offset=0

PROD URL Definition: https://api.payconiq.com/v2/transactions/search?limit=2&offset=0

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json









Example Request:
curl -X POST \
  'https://dev.payconiq.com/v2/transactions/search?limit=100&offset=0' \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
     "from": "2018-03-01T00:00:00.254Z",
     "to": "2018-04-29T23:59:59.254Z"
}'




Request Parameters

Attribute Description Comment/ Format
limit
[int, required]
The limit is used to set the number of results returned. 1 - 100
offset
[int, required]
The offset is used in combination with the limit to filter the results to a particular record count. 1-100


Request Body

Attribute Description Comment/ Format
from
[string, optional]
Starting point of the date and time range YYYY-MM-DDTHH:MM:SS.254Z
to
[string, optional]
Ending point of the date and time range YYYY-MM-DDTHH:MM:SS.254Z
status
[string, optional]
Transaction status Allowed values:
PENDING, CONFIRMED, SUCCEEDED, CANCELED, CANCELED_BY_MERCHANT, FAILED, TIMEDOUT, CREATION
userId
[string, optional]
Origin Id or target id of a payment Eg: 5afd91dc2505451d4650d827
externalRefId
[string, optional]
External Reference Id of the payment


Response Header

Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


An array of transaction objects is returned depending on the parameters passed in the transaction request.

If there are no transactions, an empty array is returned.









Example Response
HTTP/1.1 200 OK
Content-Type: application/json
[{
   "_id": "5ae714d95fa9ad4771cf2624",
   "originIBAN": "NL88RABO8934720099",
   "targetIBAN": "NL39RABO0120295940",
   "targetId": "5ae073975fa9ad4771cf221d",
   "amount": "1000",
   "currency": "EUR",
   "description": "1526309130949",
   "callbackUrl": "https://www.facebook.com/?webhookId=1526309130949",
   "originUser":    {
      "firstName": "Kennedy"
   },
   "targetUser":    {
      "_id": "5ae073975fa9ad4771cf221d",
      "companyName": "Test Merchant",
   },
   "creationDate": 1525093593036,
   "status": "SUCCEEDED",
   "origin": "DIRECT_PAY",
   "endToEndId":"5ae714d95fa9ad4771cf2624"
   },
 {…},
 {…}
]



Response Body

Attribute Description
_id
Unique identifier of the transaction
originIBAN
IBAN from which amount is deducted for payment.
targetIBAN
IBAN to which amount is credited.
targetId
Unique identifier of the merchant
amount
Transaction amount in Euro cents
currency
Transaction currency
description
Description of the transaction
callbackUrl
Callback url of the transaction
originUser
firstName
First name of consumer
targetUser
_id
Unique identifier of the merchant
companyName
Name of company
creationDate
Date when transaction was created.(Epoch time)
status
Status of a transaction.
origin
The origin of the transaction. Indicates the type of transaction performed.
endToEndId
The end to end Id of the transaction. This field is the same Id which is present on the bank statement of the merchant or partner for reconciliation purposes.


Cancel Transaction

Canceling a transaction implies that either the customer or merchant does not want to go ahead with a transaction. A transaction can online be canceled if it is in a PENDING state i.e. the transaction is waiting for confirmation from the user.

Once a transaction is canceled, the status reflects a canceled state

EXT URL Definition: https://dev.payconiq.com/v2/transactions/{transactionId}/cancel

PROD URL Definition: https://api.payconiq.com/v2/transactions/{transactionId}/cancel

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json









Example Request:
curl -X POST \
  https://dev.payconiq.com/v2/transactions/5ae872a91481ec5f80534c46/cancel \
  -H 'Authorization: APIKey' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \



Request Parameters

Attribute Description Comment/ Format
transactionId
[string, required]
This is passed in the URL of the endpoint. A unique transaction id is passed from a transaction creation request.
Content-type Content type of the data application/json


Request Body

Attribute Description Comment/ Format


Response Header





Example Response
    HTTP/1.1 200 OK
Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


Response Body

Attribute Description Comment/ Format

Refund Transaction

A refund is part of a return process for goods and services purchased. The consumer returns goods to the merchant and the merchant refunds the consumer. A refund can be performed via the consumer IBAN which is provided in the payment details via a GET Transaction Details API call.

Payconiq Online - Widget

The widget implementation of the Payconiq API is a quick and easy way to integrate your online shop or where applicable with the use of a client-side JavaScript widget. This library focusses on security, effectiveness and aims to work with little configuration. Anyone can access the library, but in order to set-up successful payments, you will need to setup and configure the widget with details provided in the prerequisites section below.


Process Flow

Involved Parties:

  • Customer – Customer involved in the transaction
  • Merchant Website – Merchant website where the widget is implemented.
  • Merchant Backend – Backend of the merchant integrates and interacts with Payconiq.
  • Payconiq Widget – JavaScript application installed and executed with a webpage provided by Payconiq
  • Payconiq App - Payconiq consumer application.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

Online Widget Process Flow W3Schools


Step by Step Transaction Flow

  • Customer visits the merchant website adds items to the cart and chooses to checkout.
  • Various payment options are shown to the customer.
  • Customer chooses the Payconiq payment option.
  • Merchant website sends a request to the merchant backend to create a signature using a symmetric key.
  • Merchant backend responds with the signature to the merchant website.
  • Merchant website loads the widget using the required parameters.
  • Payconiq widget sends a request to the Payconiq backend to create a transaction.
  • Payconiq backend returns the created transaction with the transaction id to the Payconiq widget.
  • The Payconiq widget displays the QR code on the Merchant’s website for the customer to scan and pay.
  • Customer sees the QR code and scans it using the Payconiq App.
  • The Payconiq App requests for the transaction details from the Payconiq Backend and displays it for customer confirmation.
  • The customer confirms the transaction by entering the PIN and the Payconiq App sends a request to the Payconiq Backend to process the confirmation.
  • The status of the transaction is passed to both the Payconiq widget and the Merchant Backend using the callbackURL with the webhook id.
  • Payconiq app is updated with the status of the transaction
  • The Payconiq widget returns a success or failed status to the Merchant website.


Prerequisites

Before implementing the above process flow, you should have received the following information from Payconiq and provided the callback url.

  • Merchant Id – A unique identifier for the online merchant within the Payconiq platform. This would have been shared during the onboarding process of the merchant.
  • Secret Key – This is used to secure the request between the merchant’s backend and Payconiq’s backend. Do not share your secret keys in public areas such as online sites or client-side code.

Note: The secret key cannot be used to access the REST API endpoints.

  • API Key – This is used to securely access the Payconiq API endpoints. Do not share your API keys in public areas such as online sites or client-side code.
  • Merchant Callback URL – An endpoint exposed to Payconiq to send back the status of each transaction. This should be provided during the onboarding stage and an HTTPS Url.

If the above required information is not available, please send us an email on devsupport@payconiq.com for assistance.


Implementation

Please follow the below steps to successfully include the Payconiq online payment widget in your website.


1. Add the script

EXT Java Script Library:
<script data-payconiq-script="bootstrap"
  src="https://dev.payconiq.com/v2/online/static/widget.js"
    charset="utf-8">
</script>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PROD JavaScript Library:
<script data-payconiq-script="bootstrap"
    src="https://api.payconiq.com/v2/online/static/widget.js"
    charset="utf-8">
</script>

First of all, you will need to include our JavaScript library. This library is tested, compatible with all modern browsers and should work straight ‘out of the box’.

If you do face any issues, don’t hesitate to contact us on devsupport@payconiq.com.

You can add the snippet on the right in your payment page. It can be added in the header as well as in the body, depending on your website implementation/platform. The library will automatically add a global method called ‘payconiq’ to the window. This means it can be accessible from anywhere in your JavaScript files. Somewhere on your page you should see a button allowing users to make a payment using Payconiq. When the user clicks on this button, the ‘payconiq’ library will be called.


2. Generate a signature

In order to secure the transaction, a signature is generated using the secret key asigned to the merchant. The designated secret key must be kept secure as it is used to authenticate the transaction by the Payconiq API. The following formula is used to generate the signature:

base64(sha256(merchantId, webhookId, currency, amount, secretKey))

Sample implementations for different programming languages are provided to generate a signature in the following github page: https://github.com/payconiq.

When the customer checks out with his products, the final amount in addition to the webhookId, currency, and secret key is used to generate a signature with the above function. Once generated, the signature is sent to Payconiq to validate the transaction request. Only when both sides recognize the same symmetric signature, a transaction will be considered as valid and will be processed. The signature can be calculated and transferred to the frontend when the page loads or using AJAX, depending on your environment.

We strongly recommend that the signature should be generated at the backend of the merchant shop and then passed to the Payconiq widget located in the frontend of the merchant website. This is to prevent any fraud from taking place.


3. Implement the Payconiq Pay Button


  <button onclick="start_payment()">Pay with Payconiq</button>
  <script type="text/javascript">
  start_payment = function() {
    payconiq({
      widgetType: 'popup',
      transactionData: {
        webhookId: '123',
        signature: 'io+eRjK6B9yO4fzijU0p4CCtdol3XCypPXoluKErM0E=',
        merchantId: '569ce80387f09909a6c9406d',
        amount: '30',
        currency: 'EUR',
        returnUrl: 'https://www.example.com'
      }
    })
    .on("success", function() { alert("success");})
    .on("error", function()   { alert("error");})
    .on("failed", function()  { alert("failed");})
    .on("timeout", function() { alert("timeout");})
    .on("canceled", function() { alert("user cancels from app");})
    .load();
  }
</script>

The Pay Button contains the logic to send the transaction request to the Payconiq backend systems. It requires specific parameters which if not provided could lead to errors with the payment.

On the right is a sample implementation of the Payconiq Pay Button for the popup flavor.

Parameters

Attribute Description
widgetType
[string, required]
denotes dialog type, either popup or inline
transactionData
[string, required]
This is an object which contains the transaction parameters
transactionData.webhookId
[string, required]
A unique ID, provided by the merchant, which describes a specific product, etc. This same unique ID will be included in Payconiq’s response to identify the current payment for the specific product.
transactionData.signature
[string, required]
A string with a unique value that is used to sign the current payment
transactionData.merchantId
[string, required]
Unique identifier of merchant with Payconiq system
transactionData.amount
[string, required]
amount due to be charged for the product by Payconiq on behalf of merchant. This is a Euro cent value
transactionData.currency
[string, required]
The currency in which the payment should be charged. At the moment only EUR is accepted.
returnUrl
[string, required]
Another callback link to process Payconiq’s response to your frontend environment (you don’t need to refresh the page or redirect the user, this is especially convenient for a single page application.)

Widget Callbacks

In order to ensure communication of the transaction between Payconiq and the merchant website, the following callbacks can be used.

Callback Name Description
callbackOnSuccess Notifies when there’s a successful transaction.
callbackOnTimeout Notifies when there’s a timeout error between Payconiq widget and Payconiq backend
callbackOnCreated Notifies when there’s a successful start of a transaction.
callbackOnFailed Notifies when there’s a failure for a transaction.
callbackOnCanceled Notifies when there’s a cancelled transaction.
callbackOnError Notifies when there’s an error initiating the transaction.

Processing the Response - Transaction Callback with Webhooks

A callback endpoint has to be provided as described in detail above. The status of the transaction as well as header information will be passed to the merchant backend as a notification. The webhook id will be used as a query string parameter and echoed back to the merchant backend.

Event headers for notification messages contain the generated asymmetric signature which should be validated. The JSON-formatted POST request contains event information.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature. This is described with more details above.

The backend must respond with an HTTP 200 OK status code to confirm receipt of the notification. If the merchant backend is unavailable or takes too long to respond or responds with a different status code, Payconiq cancels the call and tries to resend the notification message up to two times per transaction.


Callback Not Received or Signature Validation Fails

In the event where you don't receive the callback or the callback validation fails, you should Get the Transaction Details using the Payconiq APIs. Getting the details of a transaction is another sure way to know the status in order to complete the transaction.


Payconiq Online - App2App Linking

Payconiq uses universal links to identify, address and transport users to specific to the Payconiq app. With our solution, the customer can easily complete a transaction in a few simple clicks. With the use of universal links, the various Payconiq Apps(iOS and Android) will be opened. In the event where the app is not installed, the user will be redirected to the Play or App Store.


Implementation Options

There are two ways in which we offer App linking:

  • App to App Linking
  • Browser to App Linking


App to App Linking (App2App)

From any app to the Payconiq app (App2App), and back users will be able to make Payconiq payments. For example, a native app may have a "Pay with Payconiq button", which redirects the user to the Payconiq app, and goes back to the original app after the transaction is processed. A custom Payconiq URL is used to achieve this.

The URL will start with https://payconiq.com and will be followed by parameters determined by Payconiq.

For now, the url is followed by /pay/1/{transactionId} and can change in future. Please be prepared to handle this change.


iOS Implementation Steps

  • Using credentials provided after onboarding, generate a transaction id.
  • Using the transaction id and other parameters(returnUrl etc), construct a Payconiq URL.
  • Execute or fire off the constructed URL to switch to the Payconiq application.
  • After transaction has been finalized by the customer in the Payconiq App, the calling application is opened using the specified return url.
  • The transaction status must be fetched by the calling application in order to determine the status of the transaction.

In order to start a Payconiq transaction, the following details must be present.

  • Return Url – This must be a valid https URL encoded web or link. The return Url will be fired in the case of a successful or unsuccessful payment(This excludes special error cases). Your URL must be a universal link in order for Payconiq to return to your app after finishing a payment. Universal links provides users with a seamless integrated mobile experience.

  • To implement universal links in your iOS app, please follow this link.

  • Payconiq Transaction ID – This is the id to be passed after a request is made to fetch a transaction id via an HTTPs REST service call. You may follow the example with the required parameters to generate a transaction id here.


iOS Universal Link Integration

if let url = URL("https://payconiq.com/pay/1/5ae859ed2457480179a7b98e?returnUrl=https://example.com") {
    if #available(iOS 10.0, *) {
        // Pass custom options if needed
        UIApplication.shared.open(url, options: [:], completionHandler: { result in
            //Handle result
        })
    }else {
        let result = UIApplication.shared.openURL(url)
        //Handle result
    }
}

If you don't want to check manually if the Payconiq app is installed on a device, you can use a universal link. In this case, if the Payconiq app is not installed, a web page will be opened which will ask user to install Payconiq app. See sample implementation using the Universal Link.







Android Implementation

















Sample Implementation

// Generate a transaction id
String transactionId = generatePqTransactionId();

// Construct the linking url
String returnUrl = "https://example.com/";
String link = String.format("https://payconiq.com/1/%s/?returnUrl=%s", transactionId, returnUrl);

// Start the payconiq application
startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(link)));

  • Using credentials provided after onboarding, generate a transaction id.
  • Using the transaction id and other parameters(returnUrl etc), construct a Payconiq URL.
  • Execute or fire off the constructed URL to switch to the Payconiq application.
  • After transaction has been finalized by the customer in the Payconiq App, the calling application is opened using the specified return url.
  • The transaction status must be fetched by the calling application in order to determine the status of the transaction.

The Android App to App link integration can be achieved using intents with the following Payconiq url "https://payconiq.com/ ".

The first time a Payconiq URL is clicked, the user is asked whether he wants to open this link using a browser or the Payconiq App.

When the user sees this "choice" dialog, he has the option to select "Never ask me again". When that is clicked, the user's preference will be saved, and the user won't be given the browser vs. Payconiq app choice again.

In order to start a Payconiq transaction, the following details must be present.

  • Return Url – This must be a valid URL encoded web or link. The return Url will be fired in the case of a successful or unsuccessful payment(This excludes special error cases). Your URL must be a universal link in order for Payconiq to return to your app after finishing a payment. Universal links provides users with a seamless integrated mobile experience.

  • To implement universal links in your Android app, please follow this link.

  • Payconiq Transaction ID – This is the id to be passed after a request is made to fetch a transaction id via an HTTPs REST service call. You may follow the example with the required parameters to generate a transaction id here.


Browser to App Linking

For the browser to app linking custom Payconiq URLs are used such as "https://payconiq.com/".

A return url is needed in order to return to the page from where the Payconiq App was called. The complete url will look like this: "https://payconiq.com/pay/1/{transactionId}?returnUrl={returnUrl}"

The setup is almost the same as for App to App linking. In addition, the web page in the browser should contain logic to determine the host OS of the phone and fires a Payconiq URL for iOS and and an intent with the Payconiq URL for Android. If the Payconiq app is not installed, the user is redirected to the Apple App store or Google Play store to download the Payconiq Application.

Note:

  • For EXT testing, you must install only the EXT app on your phone in order to test successfully.
  • Having the EXT and PROD app installed on the phone while testing in the EXT environment will not work.

General Implementation Steps

  • Using credentials provided after onboarding, generate a transaction id.
  • Using the transaction id and other parameters(returnUrl etc), construct a Payconiq URL.
  • Execute or fire off the constructed URL to switch to the Payconiq application.
  • After transaction has been finalized by the customer in the Payconiq App, the calling website is opened using the specified return url.
  • The transaction status must be fetched by the calling application in order to determine the status of the transaction.


iOS Implementation

function isIOS(){
  if (/iphone|XBLWP7/i.test(navigator.userAgent.toLowerCase())) {
    return true;
  }
  else
    return false;
}

In order to execute this flow, the following javascript sample code is implemented in the web page for iOS devices.

This function is used to identify an iOS device.


PROD - iOS Browser2App Linking
<button>
    <a href = "https://payconiq.com/pay/1/{transactionId}?returnUrl=www.example.com">
        Pay PROD Transaction iOS
    </a>
</button>


EXT - iOS Browser2App Linking
<button>
        <a href = "https://payconiq.com/pay/1/{transactionId}?returnUrl=www.example.com">
            Pay EXT Transaction iOS
        </a>
    </button>



The code sample to the right triggers the Payconiq App. You may place this behind a “Pay with Payconiq” button. Please use the EXT Payconiq app for EXT environment testing and the PROD Payconiq application for the production environment testing.









Android Implementation

 function isAndroid(){
   if (/android|XBLWP7/i.test(navigator.userAgent.toLowerCase())) {
     return true;
   }
   else
     return false;
 }


The following javascript sample code is implemented in the web page for Android devices.

This function is used to identify an Android device.




PROD - Android Browser2App Linking
<button>
  <a href = "https://payconiq.com/pay/1/{transactionId}#Intent;scheme=payconiq;package=com.payconiq.customers;end">
    Pay PROD Transaction Android
  </a>
</button>


EXT - Android Browser2App Linking
<button>
  <a href = "https://payconiq.com/pay/1/{transactionId}#Intent;scheme=payconiq;package=com.payconiq.customers.external;end">
    Pay EXT Transaction Android
  </a>
</button>





The code sample to the right triggers the Payconiq Android App. You may place this behind a “Pay with Payconiq” button. Please use the EXT Payconiq app for EXT environment testing and the PROD Payconiq application for the production environment testing.

Payconiq Online - Custom Online

The Payconiq QR code can be displayed online via web checkout. Merchants and partners integrate with Payconiq API’s in order to facilitate payments. The following process flow will be followed in order to complete the implementation.


Process Flow

Involved Parties:

  • Payconiq App – Payconiq consumer application.
  • Merchant Frontend – Website checkout page.
  • Merchant Backend – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

Online Custom Process Flow W3Schools


Step by step transaction flow

  • Merchant frontend sends transaction creation details to Merchant’s backend. This will contain at least the transaction amount.
  • Merchant backend sends a REST request to the Payconiq backend to create a transaction. The parameters passed in this request are the transaction amount, transaction currency, transaction description and a callbackUrl containing a webhookId. Note: You should use a dynamic webhookId in the callbakUrl.
  • Payconiq backend sends a create transaction response with the transaction id to the Merchant backend.
  • The Merchant backend sends the transaction id to the Merchant frontend to display the payment as a QR code.
  • Payconiq App scans the QR code in order to start the payment for the amount displayed. A request for transaction details is sent to the Payconiq backend for the transaction.
  • Payconiq backend sends the transaction details to the Payconiq App which would contain the name of the merchant and the amount to pay.
  • The user confirms the payment by entering his/her pin. A payment transaction request is sent to the Payconiq Backend for authorization.
  • A payment transaction response with the details is sent back to the Payconiq App indicating a success or failure of the transaction.
  • Payconiq backend sends a payment transaction notification to the Merchant backend with the transaction details via the callbackUrl. The details of the notification will either contain success or failure details.

NB: The order of consumer and merchant notification is not sequential. One may arrive before the other depending on internet and network connections.

Prerequisites

Before implementing the above process flow, you should have received the following information from Payconiq and provided a callback url:

  • API Key – This is used to secure the request between the merchant’s backend and Payconiq’s backend. Do not share your API keys in public areas such as online sites or client-side code.
  • Merchant CallbackUrl – This URL will be called by Payconiq’s backend servers in order to send the status of the transaction to the merchant. See above full requirements if the Merchant Callback.

If the required information is not available, please send us an email on devsupport@payconiq.com for assistance.


Implementation

Please follow the below steps to successfully implement the Payconiq API website checkout page.


Create Transaction

In order to begin a transaction, a merchant needs to create a transaction from its backend via the Payconiq backend through an Https Post request. A transaction id is valid for two minutes after which it cannot be used. If a payment does not take place within these two minutes, a new transaction id has to be requested.

EXT URL Definition: https://dev.payconiq.com/v2/transactions

PROD URL Definition: https://api.payconiq.com/v2/transactions

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json






Example Request:
curl -X POST \
  https://dev.payconiq.com/v2/transactions \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
               "amount" : "1",
               "currency" : "EUR",
               "callbackUrl": "https://prd/dummy.network/api/v1/orders/payconiq?webhookId=123456",
               "description": "Test transaction 12345",
               "externalRefId": "12345"
}'


Request Body

Attribute Description Comment/ Format
amount
[string, required]
Transaction amount in Euro cents Ex: 1 – 1 cent
100 – 1 Euro
currency
[string, required]
Currency of the transaction. EUR
callbackUrl
[string, optional]
Callback where Payconiq needs to send the confirmation status.
A webhookId should be passed as part of the callbackUrl
description
[string, optional]
Custom description of the transaction. For reconciliation purposes, details in description field will reflect on the bank statement.
externalRefId
[string, optional]
External reference number of calling party

























Example Response:
HTTP/1.1 201 Created
{"transactionId" : "5ae70fc51481ec588ad1ff9d",
"qrUrl":"https://portal.payconiq.com/qrcode?c=https://payconiq.com/pay/1/5ae70fc51481ec588ad1ff9d"}


Response Header

Attribute Description Comment/ Format
Http Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


Response Body

Attribute Description Comment/ Format
transactionId
[string]
Unique Payconiq transaction id. 24 hexadecimal value.
qrUrl
[string]
URL which automatically generates a Payconiq QR code once invoked. url


The Payconiq QR Code

The QR Code can be displayed using the following method.

The Payconiq QR code can be rendered in a web view container for quick scanning. A parameter with name qrUrl returns a link that can be easily rendered in a web view. This url makes use of Payconiq’s QR code generation service. By default, the Payconiq QR code is returned as a PNG with a small (S) size.

Parameter Description Comment/ Format
f
[string]
Image format SVG, PNG
s
[string]
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
S, M, L, XL
This only applies to PNG format

Sample formatted URL

Size: (L) Large

Image Format: PNG

Formatted Url: https://portal.payconiq.com/qrcode?c=https://payconiq.com/pay/1/5c1b589a296e9a3330aebbe0&s=L&f=PNG

Sample QR Code Image QR Code


Payconiq QR Code Sizes and Scan Distances.

  • Payconiq recommends the following Payconiq QR Code sizes and scanning distances when displaying the Payconiq QR Code.
  • Take note of the scanning distance in order to use the correct Payconiq QR Code size.
Recommend Size Pixels Scanning Distance
Small (S) 180x180 pixels 15 cm
Medium (M) 250x250 pixels 20 cm
Large (L) 400x400 pixels 30 cm
Extra Large (XL) 800x800 pixels 40 cm

Note:

  • If the resolution is lower than the screen resolution please use the SVG instead of the PNG to keep a sharp image.
  • In case any of these sizes are not compatible with your setup please get in touch via devsupport@payconiq.com for further assistance.


Processing the Response

Transaction Callback with Webhooks

In order to process a Payconiq callback request, an endpoint has to be provided as described in detail above. This endpoint is provided while creating a Payconiq transaction. The status of the transaction as well as header information will be passed to the merchant backend as a notification. If supplied, a webhook id will be used as a query string parameter and echoed back to the merchant backend.

Event headers for notification messages contain the generated asymmetric signature which should be validated. The JSON-formatted POST request contains event information.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature. This is described with more details above.

The backend must respond with an HTTP 200 OK status code to confirm receipt of the notification. If the merchant backend is unavailable or takes too long to respond or responds with a different status code, Payconiq cancels the call and tries to resend the notification message up to two times per transaction.


Callback Not Received or Signature Validation Fails

In the event where you don't receive the callback or the callback validation fails, you should Get the Transaction Details as described below. Getting the details of a transaction is another sure way to know the status in order to complete the transaction.


Get Transaction Details

Transaction details of an existing transaction may be obtained. A unique transaction id is passed from a transaction creation request and Payconiq will return the corresponding transaction information.

Note: It is recommended to implement this as a fallback option to obtaining the response via the callback URL.

EXT URL Definition: https://dev.payconiq.com/v2/transactions/{transactionId}

PROD URL Definition: https://api.payconiq.com/v2/transactions/{transactionId}

HTTP Verb: GET

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.




Example Request:
curl -X GET \
  https://dev.payconiq.com/v2/transactions/{transactionId} \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \



Request Parameters

Attribute Description Comment/ Format
transactionId
[string, required]
This is passed in the URL of the endpoint. A unique transaction id is passed from a transaction creation request.

Response Header

Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
   "_id": "5ae714d95fa9ad4771cf2624",
   "originIBAN": "NL88RABO8934720099",
   "targetIBAN": "NL39RABO0120295940",
   "targetId": "5ae073975fa9ad4771cf221d",
   "amount": "1000",
   "currency": "EUR",
   "description": "1526309130949",
   "callbackUrl": "https://www.facebook.com/?webhookId=1526309130949",
   "originUser":    {
      "firstName": "Kennedy"
   },
   "targetUser":    {
      "_id": "5ae073975fa9ad4771cf221d",
      "companyName": "Test Merchant",
   },
   "creationDate": 1525093593036,
   "status": "SUCCEEDED",
   "origin": "DIRECT_PAY",
   "endToEndId":"5ae714d95fa9ad4771cf2624"
}



Response Body

Attribute Description
_id
Unique identifier of the transaction
originIBAN
IBAN from which amount is deducted for payment.
targetIBAN
IBAN to which amount is credited.
targetId
Unique identifier of the merchant
amount
Transaction amount in Euro cents
currency
Transaction currency
description
Description of the transaction
callbackUrl
Callback url of the transaction
originUser
firstName
First name of consumer
targetUser
_id
Unique identifier of the merchant
companyName
Name of company
creationDate
Date when transaction was created.(Epoch time)
status
Status of a transaction.
origin
The origin of the transaction. Indicates the type of transaction performed.
endToEndId
The end to end Id of the transaction. This field is the same Id which is present on the bank statement of the merchant or partner for reconciliation purposes.


Get Transaction List

This returns a list of existing transactions sent to the merchant’s account. The list of transactions returned are returned in a sorted order with the most recent transactions appearing first.

EXT URL Definition: https://dev.payconiq.com/v2/transactions/search?limit=2&offset=0

PROD URL Definition: https://api.payconiq.com/v2/transactions/search?limit=2&offset=0

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json









Example Request:
curl -X POST \
  'https://dev.payconiq.com/v2/transactions/search?limit=100&offset=0' \
  -H 'Authorization: <APIKey>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
     "from": "2018-03-01T00:00:00.254Z",
     "to": "2018-04-29T23:59:59.254Z"
}'




Request Parameters

Attribute Description Comment/ Format
limit
[int, required]
The limit is used to set the number of results returned. 1 - 100
offset
[int, required]
The offset is used in combination with the limit to filter the results to a particular record count. 1 - 100


Request Body

Attribute Description Comment/ Format
from
[string, optional]
Starting point of the date and time range YYYY-MM-DDTHH:MM:SS.254Z
to
[string, optional]
Ending point of the date and time range YYYY-MM-DDTHH:MM:SS.254Z
status
[string, optional]
Transaction status Allowed values:
PENDING, CONFIRMED, SUCCEEDED, CANCELED, CANCELED_BY_MERCHANT, FAILED, TIMEDOUT, CREATION
userId
[string, optional]
Origin Id or target id of a payment Eg: 5afd91dc2505451d4650d827
externalRefId
[string, optional]
External Reference Id of the payment


Response Header

Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


An array of transaction objects is returned depending on the parameters passed in the transaction request.

If there are no transactions, an empty array is returned.









Example Response
HTTP/1.1 200 OK
Content-Type: application/json
[{
   "_id": "5ae714d95fa9ad4771cf2624",
   "originIBAN": "NL88RABO8934720099",
   "targetIBAN": "NL39RABO0120295940",
   "targetId": "5ae073975fa9ad4771cf221d",
   "amount": "1000",
   "currency": "EUR",
   "description": "1526309130949",
   "callbackUrl": "https://www.facebook.com/?webhookId=1526309130949",
   "originUser":    {
      "firstName": "Kennedy"
   },
   "targetUser":    {
      "_id": "5ae073975fa9ad4771cf221d",
      "companyName": "Test Merchant",
   },
   "creationDate": 1525093593036,
   "status": "SUCCEEDED",
   "origin": "DIRECT_PAY",
   "endToEndId":"5ae714d95fa9ad4771cf2624"
   },
 {…},
 {…}
]



Response Body

Attribute Description
_id
Unique identifier of the transaction
originIBAN
IBAN from which amount is deducted for payment.
targetIBAN
IBAN to which amount is credited.
targetId
Unique identifier of the merchant
amount
Transaction amount in Euro cents
currency
Transaction currency
description
Description of the transaction
callbackUrl
Callback url of the transaction
originUser
firstName
First name of consumer
targetUser
_id
Unique identifier of the merchant
companyName
Name of company
creationDate
Date when transaction was created.(Epoch time)
status
Status of a transaction.
origin
The origin of the transaction. Indicates the type of transaction performed.
endToEndId
The end to end Id of the transaction. This field is the same Id which is present on the bank statement of the merchant or partner for reconciliation purposes.


Cancel Transaction

Canceling a transaction implies that either the customer or merchant does not want to go ahead with a transaction. A transaction can online be canceled if it is in a PENDING state i.e. the transaction is waiting for confirmation from the user.

Once a transaction is canceled, the status reflects a canceled state

EXT URL Definition: https://dev.payconiq.com/v2/transactions/{transactionId}/cancel

PROD URL Definition: https://api.payconiq.com/v2/transactions/{transactionId}/cancel

HTTP Verb: POST

Arguments


Request Header

Attribute Description Comment/ Format
Authorization APIKey
[string, required]
Authorization which contains the APIKey. APIKey shared with merchant/integrator as part of initial deliverables.
Content-type Content type of the data application/json









Example Request:
curl -X POST \
  https://dev.payconiq.com/v2/transactions/5ae872a91481ec5f80534c46/cancel \
  -H 'Authorization: APIKey' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \



Request Parameters

Attribute Description Comment/ Format
transactionId
[string, required]
This is passed in the URL of the endpoint. A unique transaction id is passed from a transaction creation request.
Content-type Content type of the data application/json


Request Body

Attribute Description Comment/ Format


Response Header





Example Response
    HTTP/1.1 200 OK
Attribute Description Comment/ Format
Https Status Code
[int]
Status code of the HTTP POST response. 2xx – Indicates success
4xx – Indicates malformed client request
5xx – Indicates errors with Payconiq servers
Content-type
[string]
Content type of the data application/json


Response Body

Attribute Description Comment/ Format

Refund Transaction

A refund is part of a return process for goods and services purchased. The consumer returns goods to the merchant and the merchant refunds the consumer. A refund can be performed via the consumer IBAN which is provided in the payment details via a GET Transaction Details API call.

FAQs

Additional information

How can I confirm my test payment transaction?

You can confirm your test payment by using our EXT Payconiq App. First off, you need to onboard as a test customer. After this, you scan the QR code and confirm the transaction using your pin code. Don’t worry, it won’t cost you a thing since you’re in the test environment.

How can I generate and check the signature?

Here is the link to our code snippets in different languages showing how to generate and check the signature: Payconiq Github.

For our EXT/dev environments, are we required to use a real IBAN?

No. As long as you are using the EXT app, feel free to use a randomly generated IBAN. Payconiq recommends using http://randomiban.com to generate test IBANs.

Multiple credentials for different environments.

We are planning on using multiple environments for test, development and QA. Do we need to use the same credentials for each environment?

No. We are happy to generate multiple test merchants in order to facilitate multiple environments. However, once you are ready for production, we will need to verify that the necessary contracts are in place before issuing any production keys.

Can I use the same email to set up an additional merchant account?

No. Your email address must be a unique identifier.

Can I use dummy email addresses to set up an environment?

No. You will receive various emails containing information necessary to access the Merchant Portal

How does my callback URL need to be structured?

Your callback URL needs to be https://

Do I need to specify my callback URL?

If you are using our widget solution and online, we will need to register a callback URL. If you are doing your own test integration with no need for a callback, you can use an unspecified callback; this callback can be dynamic.

How long is a transactionID valid?

A transaction ID is valid for two (2) minutes before it times out.

Downloading Certificate Keys

Command to download the x509 Certificate:
openssl s_client -connect dev.payconiq.com:443 -showcerts | openssl x509 -text

Command to fetch the PEM Public Key:
openssl s_client -connect dev.payconiq.com:443 -showcerts | openssl x509 -pubkey -outform PEM -out payconiqdev.pem

Public key command for the certificates for the EXT and PROD environments.

PROD: api.payconiq.com:443

EXT: dev.payconiq.com:443

How long are the Certificate Keys valid for?

The certificate public keys expire after given periods of time. It is important that you have a mechanism to always fetch the latest public key when they expire.

Certificate Environment Expiry Date
Prod Certificate
api.payconiq.com:443
17th April 2019
Dev Certificate
dev.payconiq.com:443
16th February 2021

Payconiq callback signature validation fails?

If the callback signature validation continues to fail, you should GET the transaction details to know the status of the transaction. Please refer to the API implementation here to see how this can be done.

How can I redirect the Payconiq app to my application after completing a payment in the Payconiq app?

In order to redirect to your application from the Payconiq app, your app needs to support universal links just as we have with the Payconiq app.

Please see links for Android and iOS links that would provide some guidance on how to implement universal links. The universal links will be set as the “returnUrl” prior to calling the Payconiq app.

Can I setup a dedicated VPN connection to the Payconiq Backend?

At this point Payconiq does not establish VPN’s between sites.

How can I reconcile Payconiq transactions on my bank statement?

For every successful Payconiq transaction, there is an endToEndId field when the transaction details for a transaction is retrieved by the merchant. The response contains the endToEndId field which matches a field similar to the "End-to-end reference" on the CAMT file of the bank statement of the merchant. This field can be used to reconcile transactions since it matches what is present on the bank statement.

If you have trouble finding the endToEndId on your bank statement or in the API call, you may contact Support.

Support

If you would like to get in touch with our support team, please send an email to devsupport@payconiq.com

Our privacy statement and terms & conditions are below

Privacy statement

Terms & conditions