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. As a merchant or partner the Payconiq payments will be received in the same way as existing payments are received for payment terminals.

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. As a merchant or partner the Payconiq payments will be received in the same way as existing payments are received for online integrations.


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.

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.

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 (Webhooks)

Each merchant needs to define a specific URL containing a webhook ID to their backend (e.g., www.merchantbackend.com/pqtransaction.php?webhookId=123456). This URL will be used by Payconiq’s backend servers in order to send transaction status updates to the merchant. This 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 webhooks are asynchronous, their order is not guaranteed. Idempotency might lead to a duplicate notification of the same type of event. When such an event occurs, Payconiq issues an HTTPS POST notification message to the merchant’s backend through the webhook listener URL which the merchant has defined in their merchant callback (see Prerequisites). 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 for notification messages contain the generated asymmetric signature and information that you can use to validate the signature. The JSON-formatted POST notification contains event information. 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 three times per transaction. The endpoint must verify that:

  • Notification messages originated from Payconiq were not altered or corrupted during transmission.
  • Notification messages are sent to the intended target endpoint (webhookId).
  • Notification messages contain a valid signature.

When the endpoint receives the notification message, it must respond with a HTTP 200-level status code. If the app responds with any other status code, Payconiq tries to resend the notification message up to three times per transaction.


Validating the Callback Signature

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.

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.


Webhook 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.


Webhook 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. 57dbc67db595282f
status
[string]
The status of the transaction.
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 webhook request to the merchant or integrator.

Status Name Status Description
PENDING The transaction is waiting for confirmation from the user
CONFIRMED The payment gets confirmed once the Payconiq validation has been successfully finalized
SUCCEEDED A transaction was confirmed by the user and approved by the user’s bank.
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.
BLOCKED Payconiq blocks the payment from execution; this is a status that can also occur after the SUCCEEDED state.
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
  • BLOCKED
  • CANCELED_BY_MERCHANT


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 webhook 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 Instore Flow Diagram


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.


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 (Webhook) – 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
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
transactionId
[string]
Unique Payconiq transaction id. 24 hexadecimal value.
qrUrl
[string]
URL which automatically generates a Payconiq QR code once invoked. url


Generating the QR Code

The QR Code can be generated and displayed in one of two ways.

Method 1

After successfully creating a transaction, a QR code needs to be generated and displayed for customer scanning. The use of any QR code generating api or website may be used by passing the following Payconiq url and transaction id as a parameter:

URL to generate QR Code: https://payconiq.com/pay/1/xxxx

Where xxxx is the transaction id that was created. The resulting QR code generated is scanned with the Payconiq app of the corresponding environment.

Method 2

Alternatively, you can render the qrUrl in a web view container which will display the QR code for quick scanning.


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 and information that 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 and contains a valid 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 three times per 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, BLOCKED, 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 Online Widget Flow Diagram


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");})
    .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.)

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.
callbackOnCanceled 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 and information that 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 and contains a valid 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 three times per 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.

Note: The return url must be a valid http(s) URL.


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).

  • 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/". For Android, the returnUrl is not needed therefore the complete URL is "https://payconiq.com/pay/1/{transactionId} ".

The setup is almost the same as for App to App linking. In addition, the web page in the browser contains 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.

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 = "payconiq.ext://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 = "intent://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 Online Custom Flow Diagram


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 webhook id. Note: You should use a dynamic webhook id as a 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.


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 (Webhook) – 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


Generating the QR Code

The QR Code can be generated and displayed in one of two ways.

Method 1

After successfully creating a transaction, a QR code needs to be generated and displayed for customer scanning. The use of any QR code generating api or website may be used by passing the following Payconiq url and transaction id as a parameter:

URL to generate QR Code: https://payconiq.com/pay/1/xxxx

Where xxxx is the transaction id that was created. The resulting QR code generated is scanned with the Payconiq app of the corresponding environment.

Method 2

Alternatively, you can render the qrUrl in a web view container which will display the QR code for quick scanning.


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 and information that 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 and contains a valid 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 three times per 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, BLOCKED, 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:

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

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