Payconiq Merchant API 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 Payconiq 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 Payconiq 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 Invoice (V3)

The Payconiq Invoice solution is suitable for merchants with who would like to receive payments via Payconiq by issuing invoices to their consumers. The Payconiq QR is printed on a paper invoice or embedded in a PDF invoice. Once implemented, consumers scan a Payconiq QR code and confirm a payment using the Payconiq App. Amounts and descriptions of the purchase are passed automatically to the Payconiq App and the consumer simply confirms the payment with a pin, fingerprint or face id if supported. The merchant is automatically notified of the status of the payment.


Latest Payconiq Version

  • The current version of the Payconiq APIs is V3.


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 [email protected] for further assistance.


Payconiq Bulking

Bulking of payments refers to the process of aggregating individual consumer payments in batches. In order to have your successful transactions bulked, the bulking service has to be enabled for your merchant. Please check with your local Payconiq Organisation in order to have the feature enabled.

The bulking of transactions can be done in two ways:

  • Bulking based on your bulk identifier. With this method all successful transactions are aggregated based on a unique bulk identifier that is provided while creating a payment.
  • Bulking based on your bank account. With this method all payments are aggregated based on your bank account number (IBAN). This applies when no bulk identifier has been provided.

Bulking Notes

  • Successful Transactions are bulked over the course of a day from 00:00 to 23:59:59. Transactions executed over multiple days cannot be aggregated together.
  • After the transactions have been aggregated, there is a payout from Payconiq to your bank account the working day after. For transactions done on Friday, Saturday and Sunday you will receive three payouts in your bank statement on Monday.
  • Your account will be credited either two to three days after the transactions are bulked.
  • The bulk identifier and a bulk end to end identifier will be provided in the remittance information field of your bank statement so that you can do your reconciliation.
  • The bulk end to end identifier will also be in the End-to-end reference field of your bank statement.
  • Payconiq will create daily reconciliation report(s). Each reconciliation file contains all payments that were aggregated together.


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 Frames

Payconiq provides a branding frame consisting of a magenta border and a Payconiq logo. The Payconiq QR code should be embedded in this frame and presented to the customer when scanning a Payconiq QR code on terminal and consumer facing displays.

The frames are in both PNG and SVG formats.

An example frame before QR code is overlaid for consumer scanning.

QR Code

Below is an example of the final implementation of the Payconiq QR code and Payconiq frame there is a 10% border around the QR code (bottom and sides).

QR Code


Below are the frame formats that are available.

Description Format
Frame - Small PNG
Frame - Medium PNG
Frame - Large PNG
Frame - Extra Large PNG
Frame - Small SVG
Frame - Medium SVG
Frame - Large SVG
Frame - Extra Large SVG


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 [email protected].

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 [email protected] for further assistance.


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

V3 Remittance Information

A successful Payment results in a credit transfer from the consumer’s (payer) payment account (held with the consumer’s bank) to the Merchant's/Partner's payment bank account. There are 2 exemptions to this:

  1. If the consumer onboarded via a SEPA Direct Debit (SDD) eMandate then Payconiq will credit Merchant's/Partner's payment account.

  2. If the Merchant/Partner makes use of the Payconiq Bulking Service, then Payconiq will credit Merchant's/Partner’s payment account via aggregated amounts in a batched fashion in an agreed timetable.


Bank Statement Description

When a Payment reaches the final status “SUCCEEDED”, the Payconiq backend initiates a credit transfer (or direct debit) from the consumer’s payment account to the Merchant's/Partner’s payment account or Payconiq's payment account. The remittance information provided with the credit transfer has a maximum length of 140 characters (as standardized by the European Payments Council / EPC). These 140 characters will be encoded per default as concatenated string values, separated by spaces, in accordance with the table below. Banks provide this remittance information in online banking environments and/or paper bank statements.





Sample Remittance Information


"Payconiq f60454fd52e429d71964745d Online Kassa            4zyeYIKOw54Ybc9yenL5                Mars Bars                          "


Field Name Description Format
Issuer The entity that facilitates Payconiq Payment String
[Max Length: 8]
Delimiter Field separator String: Space
[Max Length: 1]
Payment Identifier A unique identifier representing a Payconiq Payment Transaction
Delimiter Field separator String: Space
[Max Length: 1]
Sub Merchant Name The name of the merchant where the Payconiq Payment Transaction takes place. Field is padded with spaces if the max length is not reached String
[Max Length: 23]
Delimiter Field separator String: Space
[Max Length: 1]
Reference A unique identifier referencing a Payconiq Payment Transaction in the Partner's system. Field is padded with spaces if the max length is not reached. String
[Max Length: 35]
Delimiter Field separator String: Space
[Max Length: 1]
Description A description linked to a Payconiq Payment Transaction. Field is padded with spaces if the max length is not reached. String
[Max Length: 46]

An example of the remittance information entry is as follows for the sample values provided in the table above.

“Payconiq f60454fd52e429d71964745d Online Kassa            4zyeYIKOw54Ybc9yenL5                Mars Bars                          ”

Remark: The above does not apply to the bulked Payconiq Payments.


V2 Remittance Information

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.


API Version 3 (V3) - Latest - Merchant

The Payconiq API is organized around REST and uses HTTP response codes to indicate API errors. In addition, standard HTTP features such as header authentication and HTTP verbs which are understood by off the shelf HTTP clients across all the programming languages are also used. JSON bodies are used in requests and returned in relevant API responses, including errors.


Authentication

All requests to the Payconiq payment system are authenticated using API keys. API keys grant extensive access rights to the Payconiq payment system therefore ensure they are kept safe. 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 requests via HTTP Authorization header.

All requests are encrypted using TLS 1.2 or TLS 1.3.

All API requests must be made over Https. Any calls made over unencrypted Http will fail. Wrong API keys or API requests without an 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 or Partner may define a specific URL (callback URL) that Payconiq will use to notify the status of a payment. This allows the merchant’s or partner’s backend to react to the payment and process the data (mark the payment in database, update the product count number, send an email to the consumer, etc). The callbacks are asynchronous therefore the order in which they arrive is not guaranteed. The callbacks are issued via HTTP POST requests and encrypted using TLS.


Callback Headers

The callback consists of headers of which some are informational and others used to verify the signature of the callback. The parameters in the header are made up of the following:

Name Description
signature This represents a Payconiq digitally signed content using JSON data structures and base64url encoding which makes up the JSON Web Signature (JWS).
user-agent 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 The Content-Type entity header is used to indicate the media type of the resource.


Callback Body

The body of the callback is JSON formatted with fields indicating the status of the payment. The values in the body can be used to update the payment in the merchant’s system.

Once the signature has been verified, the values in the body can be used to update the payment in the merchant’s system.

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


The Callback Signature

To prove that Payconiq generated the callback to the merchant, the Payconiq API sends a detached JSON Web Signature(JWS) which includes the signed base64UrlEncoded header and request body. The signature is signed using a publicly hosted certificate. A JWS represents these logical values separated by dots(.):

The signature will be generated as per following instructions:

jws = base64URLEncode(JOSE Header)..base64URLEncode(alg(base64URLEncode(JOSE Header).base64URLEncode(Request Body)))


Terminologies

Name Description
JSON Web Signature (JWS) A data structure representing a digitally signed message.
JSON Object Signing and Encryption (JOSE) Header JSON object containing the parameters describing the cryptographic operations and parameters employed.
JSON Web Key (JWK) A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.
JSON Web Key Set (JWKS) A JSON object that represents a set of JWKs.


The JOSE Header setup by Payconiq consists of the following:

{

"typ": "jose+json",

"kid": "JWK kid",

"alg": "ES256",

"crit": ["https://payconiq.com/sub", "https://payconiq.com/iss", "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path"],

"https://payconiq.com/sub" : "{merchantProfileId}",

"https://payconiq.com/iss" : "Payconiq",

"https://payconiq.com/iat" : "{Current creation date time in [ISODateTime format], expressed in UTC time format(YYYY-MM-DDThh:mm:ss.sssZ)},

"https://payconiq.com/jti" : "{Unique-request-identifier}",

"https://payconiq.com/path": "callback request path ex. https://www.merchantcallback.com/payconiqpayment"

}

JOSE Header Fields

Header Parameter Description
typ - Type The "typ" (type) Header Parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of this complete JWS.
kid - Key ID The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS
alg - Algorithm The "alg" (algorithm) Header Parameter identifies the cryptographic algorithm used to secure the JWS.
crit - Critical The "crit" (critical) Header Parameter indicates that extensions to this specification and/or [JWA] are being used that MUST be understood and processed.

Verifying the Callback Signature

The merchant or Partner must verify the signature in order to obtain cryptographic proof regarding the integrity and authenticity of the message.

To verify the JWS, refer to the JWS documentation which provides extensive guidelines.

Alternatively, the following steps can be performed to verify the signature. If any of the listed steps fails, then the signature cannot be verified.


Notes

  • Prior to verifying the signature, you can cache the full JWKS. This ensures that the JWKS is not always downloaded via the URL to verify the signature.
  • To know which JWK to use in verifying the signature, retrieve the JWK whose key id matches with the key id in the JOSE Header of the signature.
  • The JWKS can be downloaded and re-cached whenever the key id in the JOSE Header does not match what was previously cached.
  • The ES256 signature algorithm is whitelisted. The algorithm of the JWK.


Steps

  • This assumes that the JWKS has been cached.
  1. Extract the "kid" field from the JOSE Header of the signature.
  2. Compare the extracted "kid" with the cached "kid" in the JWKS. If there is a match, jump to step 3. If they do not match, jump to step 4.
  3. Use the cached JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".

  4. Refresh the JWKS cached by downloading the latest JWKS.

  5. Extract the "kid" field from the JOSE Header of the signature to retrieve the corresponding JWK.
  6. Used the cached JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".


  • This assumes that the public key certificate has not been cached.
  1. Extract the "kid" field from the JOSE Header of the signature.
  2. Download the JWK which matches the key id ("kid") field in the JOSE Header of the signature.
  3. Use the downloaded JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".

Code snippets for Java and PHP programming languages on how to verify 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.


The Payconiq Certificates

The certificate is hosted in a JSON Web Key (JWK) format as a JSON Web Key Set (JWKS). They can be found using the following links:

EXT Path to JWK: https://ext.payconiq.com/certificates

PROD Path to JWK: https://payconiq.com/certificates


Rotating Payconiq Certificates

Payconiq reserves the right to rotate the certificates used to generate the callback signature. In view of this, Payconiq recommends programmatically fetching the JWKs and using the values to verify the signature.

Please contact devsupport if the signature verification continues to fail.


Status codes and 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 Payconiq servers. All errors should be handled programatically to prevent applications from breaking.

In the event of an error status code, an error object will be returned as part of the response when the API endpoint is called.

HTTP Codes used by Payconiq

Below are the list of codes Payconiq uses via HTTP responses.

Status Code Description
200 - Ok Everything works as expected.
201 - Created Payconiq has successfully fulfilled the request to create a payment.
204 - No Content Payconiq has successfully fulfilled the request to cancel a payment.
400 - Bad Request The request was unacceptable. This usually happens when there are missing parameters.
401 - Unauthorized The API key provided is not valid.
403 - Forbidden The user is not allowed to access the resource requested.
404 - Not Found The requested resource does not exist.
422 - Unprocessable Entity Payconiq cannot process the request due to restrictions.
429 - Too Many Requests This error code is returned when there are too many requests to the Payconiq backend.
500 - Internal Server Error Something went wrong on Payconiq’s end. (This is rare)
503 - Service Unavailable Something went wrong on Payconiq’s end. (This is rare)

Payment Statuses

Below is the list of statuses that are returned by the Payconiq API.

Status Name Status Description
AUTHORIZED This is the status of a payment before it is set to SUCCEEDED. Payconiq internal checks for payment are successful. This occurs before the payment is sent to the bank for processing.
AUTHORIZATION_FAILED This occurs when the bank fails to approve a payment due to validation reasons. These reasons include insufficient funds, limits exceeded, etc.
CANCELLED A payment has been cancelled by a merchant or consumer. If a payment is cancelled, it cannot be scanned and paid.
EXPIRED A payment has exceeded the allowable time to pay. If a payment has expired, it cannot be paid.
FAILED Something has gone wrong while confirming a payment payment such as incorrect consumer or merchant data setup.
IDENTIFIED A payment has been scanned by a Payconiq supported app and is pending confirmation or cancellation.
PENDING A payment has been created and it has not been scanned. Consumers can scan QR code linked to this payment and confirm it.
SUCCEEDED A payment has been authorized and processed successfully by Payconiq and the consumer's bank. This the final end state of a successful payment.

Errors

The Payconiq API uses conventional HTTP response codes in combination with a JSON body to indicate success or failure of an API request. The body of an error response will contain the following fields.

Error Response Definition

Attribute Comment/Format
code - Text describing the error that has occurred. [String, required]
UNAUTHORIZED, ACCESS_DENIED,
PAYMENT_NOT_FOUND,
TECHNICAL_ERROR,
CALLER_NOT_ALLOWED_TO_CANCEL,
PAYMENT_NOT_FOUND,
PAYMENT_NOT_PENDING,
PAYMENT_CONFLICT,
BODY_MISSING,
FIELD_REQUIRED,
QR_NO_LONGER_IN_USE,
UNABLE_TO_PAY_CREDITOR,
TRY_AGAIN_LATER
message - Text describing the error that has occurred. [String, required]
traceId - The id that is assigned to a single request or job. [String, required]
spanId - The id of work unit where the error occurred. [String, required]

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 Instore (V3) - Terminal & 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 payment flow

  • Merchant frontend sends payment creation details to Merchant’s backend. This will contain at least the payment amount.
  • Merchant backend sends a REST request to the Payconiq backend to create a payment. The parameters passed in this request are the payment amount, payment currency, payment description and other parameters.
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including the QR code.
  • The merchant’s backend sends the Payconiq QR url to the merchant frontend to render 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 payment details is sent to the Payconiq backend for the payment.
  • Payconiq backend sends the payment details to the Payconiq App which would contain the name of the merchant and the amount to pay.
  • The consumer confirms the payment by entering his/her PIN, fingerprint or face id and a payment request is sent to the Payconiq Backend for authorization.
  • A payment response with the details is sent back to the Payconiq App indicating a success or failure of the payment.
  • Payconiq backend sends a payment notification to the Merchant backend with the payment details to the callback url. The details of the notification will either contain success or failure details.
  • The merchant frontend displays the confirmation status it receives from Payconiq.
  • The consumer is notified of the payment status via the app.

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

Prerequisites

  • 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 (Optional) – This URL will be called by Payconiq’s backend servers in order to send the status of the payment to the merchant.


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


Create Payment

In order to begin a payment, you need to create a payment via the Payconiq through a POST request. A unique payment identifier is valid for two minutes (120 seconds) after which it expires. If a payment does not take place within these two minutes, a new payment has to be created.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments

PROD URL Definition: https://api.payconiq.com/v3/payments


Create Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.






Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
         "amount" : "1",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200"
      }'


Create Payment Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
callbackUrl
[URI, optional]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.
currency
[String, Optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
Value: EUR
description
[String, optional]
Maximum Length: 140 chars
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5aa9a9700000000000000000",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 112,
    "currency": "EUR",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdb1685b93d1c000bde96f2"
        },
        "cancel": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        }
    }
}


Create Payment Response

The following parameters are included in the header and body of the create payment response.


Response Header

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


Response Body

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
status
[String::enum, required]
Allowed values: PENDING
The status of the Payconiq Payment.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expiresAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remmittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
amount
[Integer, required]
Payment amount in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
creditor
[Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.










HTTP/1.1 400 Bad Request
{
    "traceId": "b2586833395d4750",
    "spanId": "c235e54376fab4b9",
    "code": "FIELD_IS_REQUIRED",
    "message": "Field 'amount' is mandatory"
}

Create Payments HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
400
[Integer]
BODY_MISSING: A JSON body needs to be provided.
FIELD_IS_REQUIRED: A mandatory field is missing from the JSON request.
FIELD_IS_INVALID: A field provided is not valid. Eg: The length of a field exceeds what is required.
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
MERCHANT_PROFILE_NOT_FOUND: The merchant profile for creating a payment does not exist.
422
[Integer]
UNABLE_TO_PAY_CREDITOR: This could be returned for multiple reasons in case something goes wrong.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


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 _links.qrcode.href 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.

Attribute Description
f
[String :: Enum]
Allowed Values: SVG, PNG
Image format
s
[String :: Enum]
Allowed Values: S, M, L, XL
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
The sizes 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 [email protected] for further assistance.


The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


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 payment is another sure way to know the status in order to complete the payment.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Cancel Payment

This endpoint is used to cancel a created Payconiq payment. A payment can only be cancelled only if the status is either PENDING or IDENTIFIED. Once cancelled, the status of the payment is set to CANCELLED.

Type: REST

HTTP Verb: DELETE

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Cancel Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx




Example Request:

curl -X DELETE
  https://api.ext.payconiq.com/v3/payments/5ba35a3d0989e3000758b9c1
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Cancel Payment Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Cancel Payment Request Body

There is no body in cancel payment request.


Cancel Payment Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the cancel payment response.

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


Cancel Payment Response Body

There is no body returned in the body of a cancel payment response.







HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "8abc6e29041adb94",
    "spanId": "6ba82033652b5b41",
    "code": "PAYMENT_NOT_PENDING",
    "message": "Payment '5ba35d610989e3000758b9cc' is not allowed to be cancelled"
}



Cancel Payment HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
CALLER_NOT_ALLOWED_TO_CANCEL: The merchant is not allowed to cancel this payment.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
PAYMENT_NOT_PENDING: Payment is not in a pending or identify state.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.


Payconiq Instore (V3) - Receipt & Top-up

Using a Payconiq QR scheme, the Payconiq QR code can be generated and printed on a receipt or a top-up medium for consumers to scan and make payments. Merchants and partners integrate with the Payconiq API’s in order to facilitate payments.

Instore Receipt features

  • A Payconiq QR code on a receipt can be paid once.
  • A Payconiq QR code on a receipt is valid until it is revoked.
  • A Payconiq QR code on a receipt has a fixed amount.
  • A Payconiq QR code on a receipt can be scanned multiple times.
  • A Payconiq QR code on a receipt is still valid after it is scanned and cancelled.

Instore Top-up features

  • A Payconiq QR code on a top-up medium can be paid multiple times.
  • A Payconiq QR code on a top-up medium is valid until it is revoked.
  • A Payconiq QR code on a top-up medium can have an amount defined by the consumer or changed by the consumer.
  • A Payconiq QR code on a top-up medium can be scanned multiple times.
  • A Payconiq QR code on a top-up medium is still valid after it is scanned and cancelled.

Process Flow

Involved Parties:

  • Payconiq Supported App – Payconiq consumer application.
  • Merchant Frontend – Receipt or Top-up medium.
  • Merchant Backend – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

Instore Receipt & Top-up Process Flows

W3Schools


Step by step payment flow

  • Merchant creates a QR code using the Payconiq QR URL schema. The URL will contain parameters which include an amount, description and a reference id.
  • Merchant prints the Payconiq QR code on the receipt or top-up medium and presents it to the consumer for scanning.
  • The consumer scans the Payconiq QR code using a Payconiq supported app which reads the details of the QR code and presents it for confirmation. The details would contain the amount to pay, the creditor name and a description.
  • The consumer confirms the payment with his fingerprint, face ID or by entering his/her pin. A confirm payment request is sent to the Payconiq backend for authorization.
  • Payconiq initiates a callback notification request to the merchant’s backend with the status of the payment via a callback url. The details of the notification will contain a payment id and status among other fields.
  • The merchant backend acknowledges the callback notification by responding appropriately.
  • The merchant frontend is notified of the status of the payment or the top-up medium is credited with a designated value.
  • A payment response with the details is sent back to the Payconiq Supported App indicating a success or failure of the payment.

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


Prerequisites

  • Merchant CallbackUrl – This URL will be called by Payconiq’s backend servers in order to send the status of the payment to the merchant.
  • Product Profile Id - This is a unique identifier of the payment product used by a merchant.
  • Payconiq URL Scheme - The Payconiq template QR URL scheme.
  • API Key (Optional) – 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.


Creating The Payconiq QR Code

The Payconiq QR code can be created using the Payconiq QR generation service. The following instructions have to be followed in order to successfully create the QR. Once created, the QR code can be printed on a receipt or top-up medium.


QR Parameters

Attribute Description
f
[String :: Enum]
Allowed Values: SVG, PNG
Image format. If not provided, the default format is PNG.
s
[String :: Enum]
Allowed Values: S, M, L, XL
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
The sizes only applies to PNG format.
*If not provided, the default size is Small.
c
[String, required]
The Payconiq UTF-8 URL encoded content. This is comprised of the template URL scheme.
c.D
[String, optional]
Maximum Length: 35 chars
UTF-8 URL encoded description of the payment
c.A
[String, optional]
Minimum: 1
Maximum: 999999
UTF-8 URL encoded amount of the QR code in Euro cents.
c.R
[String, optional]
Maximum Length: 35 chars
UTF-8 URL encoded reference of the QR code.

NB: The following link provides a tool to encode the URL as an example: https://www.urlencoder.org/


Generating the QR Code

Activity Comment
1. Obtain the pre-requisite information needed to generate the Payconiq QR Code. • Format of the Payconiq QR code.
• Size of the Payconiq QR code.
• Template URL scheme.
• Product profile id of the merchant.
• Amount of the Payconiq QR code.
• Description of the Payconiq QR code.
• Reference of the Payconiq QR code.
2. Build the Payconiq service URL using the optional parameters which include:
• Image format (PNG or SVG)
• Image size (S, M, L, XL). This only applies to PNG.
Sample format:
https://portal.payconiq.com/qrcode?f={imageFormat}&s={ImageSize}&c=

Example Output URL (PNG):
https://portal.payconiq.com/qrcode?f=PNG&s=L&c=

Sample URL (SVG)
https://portal.payconiq.com/qrcode?f=SVG&c=
3. UTF-8 encode the Payconiq URL payload parameter values using UTF-8 as the destination character set.
This means encoding the following:
• Description
• Amount
• Reference.
Payconiq unencoded URL payload parameters
D=Invoice Payment
A=1000
R=sd89sd91?sd9

Payconiq encoded URL payload parameters:
D=Invoice%20Payment
A=1000
R=sd89sd91%3Fsd9
4. Build the Payconiq URL payload using the following details.
• Template URL scheme
• Product profile id of the merchant.
• Amount of the Payconiq QR code.
• Description of the Payconiq QR code.
• Reference of the Payconiq QR code.
Sample format:

https://payconiq.com/t/1/{productProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}

Sample URL payload:
https://payconiq.com/t/1/5bb37284e35e2b29e363df22?D= Invoice%20Payment &A=1000&R= sd89sd91%3Fsd9
5. UTF-8 encode the Payconiq URL Payload from step 4. Payconiq URL Payload before Encoding:
https://payconiq.com/t/1/5bb37284e35e2b29e363df22?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5bb37284e35e2b29e363df22%3FD%3D%20Invoice%2520Payment%20%26A%3D1000%26R%3D%20sd89sd91%253Fsd9
6. Build full URL by combining results from step 2 and step 5.

Once completed, execute the resulting URL in a web view to obtain the Payconiq QR code. The Payconiq QR code can be saved a file and printed subsequently.
Sample full URL:

https://portal.payconiq.com/qrcode?f=PNG&s=XL&c=https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5bb37284e35e2b29e363df22%3FD%3D%20Invoice%2520Payment%20%26A%3D1000%26R%3D%20sd89sd91%253Fsd9

Sample formatted URL

Below is sample Payconiq QR code generated using the Payconiq QR Code generation service.


QR code properties:

Image Size: Large

Image Format: PNG


QR code parameters:

Amount: 2.50 EUR

Description: Thanks for your money

Product Profile Id: 5c18cbd1296e9a26d3278518

Reference: 1nF97PCaUy5gm9thum15

Formatted Url: Sample Receipt QR Code

Sample QR Code Image QR Code


The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.





signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


Callback Not Received or Signature Validation Fails

  • In the event where you don't receive the callback, you can initiate a Get Payments List call using your reference. The response will contain details of the payment.

  • If a callback is received but signature verification fails, merchants can Get the Payment Details using the payment id from the callback. This is another sure way to know the status in order to complete the payment.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.


Payconiq Invoice (V3) - Invoice

Using a Payconiq QR scheme, the Payconiq QR code can be generated and printed on an invoice for consumers to scan and make payments later. Merchants and partners integrate with the Payconiq API’s in order to facilitate payments.

Invoice features

  • A Payconiq QR code on an invoice can be paid once.
  • A Payconiq QR code on an invoice is valid until it is revoked.
  • A Payconiq QR code on an invoice has a fixed amount.
  • A Payconiq QR code on an invoice can be scanned multiple times.
  • A Payconiq QR code on an invoice is still valid after it is scanned and cancelled.

Process Flow

Involved Parties:

  • Payconiq Supported App – Payconiq consumer application.
  • Merchant Frontend – Consumer Invoice.
  • Merchant Backend – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

Invoice Process Flows

W3Schools


Step by step payment flow

  • Merchant creates a QR code using the Payconiq QR URL schema. The URL will contain parameters which include an amount, description and a reference id.
  • Merchant prints the Payconiq QR code on an invoice and presents it to the consumer for scanning.
  • The consumer scans the Payconiq QR code using a Payconiq supported app which reads the details of the QR code and presents it for confirmation. The details would contain the amount to pay, the creditor name and a description.
  • The consumer confirms the payment with his fingerprint, face ID or by entering his/her pin. A confirm payment request is sent to the Payconiq backend for authorization.
  • Payconiq initiates a callback notification request to the merchant’s backend with the status of the payment via a callback url. The details of the notification will contain a payment id and status among other fields.
  • The merchant backend acknowledges the callback notification by responding appropriately.
  • The merchant frontend is notified of the status of the payment.
  • A payment response with the details is sent back to the Payconiq Supported App indicating a success or failure of the payment.

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


Prerequisites

  • Merchant CallbackUrl – This URL will be called by Payconiq’s backend servers in order to send the status of the payment to the merchant.
  • Product Profile Id - This is a unique identifier of the payment product used by a merchant.
  • Payconiq URL Scheme - The Payconiq template QR URL scheme.
  • API Key (Optional) – 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.


Creating The Payconiq QR Code

The Payconiq QR code can be created using the Payconiq QR generation service. The following instructions have to be followed in order to successfully create the QR. Once created, the QR code can be printed on an invoice.


QR Parameters

Attribute Description
f
[String :: Enum]
Allowed Values: SVG, PNG
Image format. If not provided, the default format is PNG.
s
[String :: Enum]
Allowed Values: S, M, L, XL
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
The sizes only applies to PNG format.
*If not provided, the default size is Small.
c
[String, required]
The Payconiq UTF-8 URL encoded content. This is comprised of the template URL scheme.
c.D
[String, optional]
Maximum Length: 35 chars
UTF-8 URL encoded description of the payment
c.A
[String, optional]
Minimum: 1
Maximum: 999999
UTF-8 URL encoded amount of the QR code in Euro cents.
c.R
[String, optional]
Maximum Length: 35 chars
UTF-8 URL encoded reference of the QR code.

NB: The following link provides a tool to encode the URL as an example: https://www.urlencoder.org/


Generating the QR Code

Activity Comment
1. Obtain the pre-requisite information needed to generate the Payconiq QR Code. • Format of the Payconiq QR code.
• Size of the Payconiq QR code.
• Template URL scheme.
• Product profile id of the merchant.
• Amount of the Payconiq QR code.
• Description of the Payconiq QR code.
• Reference of the Payconiq QR code.
2. Build the Payconiq service URL using the optional parameters which include:
• Image format (PNG or SVG)
• Image size (S, M, L, XL). This only applies to PNG.
Sample format:
https://portal.payconiq.com/qrcode?f={imageFormat}&s={ImageSize}&c=

Example Output URL (PNG):
https://portal.payconiq.com/qrcode?f=PNG&s=L&c=

Sample URL (SVG)
https://portal.payconiq.com/qrcode?f=SVG&c=
3. UTF-8 encode the Payconiq URL payload parameter values using UTF-8 as the destination character set.
This means encoding the following:
• Description
• Amount
• Reference.
Payconiq unencoded URL payload parameters
D=Invoice Payment
A=1000
R=sd89sd91?sd9

Payconiq encoded URL payload parameters:
D=Invoice%20Payment
A=1000
R=sd89sd91%3Fsd9
4. Build the Payconiq URL payload using the following details.
• Template URL scheme
• Product profile id of the merchant.
• Amount of the Payconiq QR code.
• Description of the Payconiq QR code.
• Reference of the Payconiq QR code.
Sample format:

https://payconiq.com/t/1/{productProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}

Sample URL payload:
https://payconiq.com/t/1/5bb37284e35e2b29e363df22?D= Invoice%20Payment &A=1000&R= sd89sd91%3Fsd9
5. UTF-8 encode the Payconiq URL Payload from step 4. Payconiq URL Payload before Encoding:
https://payconiq.com/t/1/5bb37284e35e2b29e363df22?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5bb37284e35e2b29e363df22%3FD%3D%20Invoice%2520Payment%20%26A%3D1000%26R%3D%20sd89sd91%253Fsd9
6. Build full URL by combining results from step 2 and step 5.

Once completed, execute the resulting URL in a web view to obtain the Payconiq QR code. The Payconiq QR code can be saved a file and printed subsequently.
Sample full URL:

https://portal.payconiq.com/qrcode?f=PNG&s=XL&c=https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5bb37284e35e2b29e363df22%3FD%3D%20Invoice%2520Payment%20%26A%3D1000%26R%3D%20sd89sd91%253Fsd9

Sample formatted URL

Below is sample Payconiq QR code generated using the Payconiq QR Code generation service.


QR code properties:

Image Size: Large

Image Format: PNG


QR code parameters:

Amount: 2.50 EUR

Description: Thanks for your money

Product Profile Id: 5c18cbd1296e9a26d3278518

Reference: 1nF97PCaUy5gm9thum15

Formatted Url: Sample Invoice QR Code

Sample QR Code Image QR Code


The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


Callback Not Received or Signature Validation Fails

  • In the event where you don't receive the callback, you can initiate a Get Payments List call using your reference. The response will contain details of the payment.

  • If a callback is received but signature verification fails, merchants can Get the Payment Details using the payment id from the callback. This is another sure way to know the status in order to complete the payment.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.


Payconiq Online (V3) - 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 payment flow

  • Merchant frontend sends payment creation details to Merchant’s backend. This will contain at least the payment amount.
  • Merchant backend sends a REST request to the Payconiq backend to create a payment. The parameters passed in this request are the payment amount, payment currency, payment description and other parameters.
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including the QR code.
  • The merchant’s backend sends the Payconiq QR url to the merchant frontend to render 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 payment details is sent to the Payconiq backend for the payment.
  • Payconiq backend sends the payment details to the Payconiq App which would contain the name of the merchant and the amount to pay.
  • The consumer confirms the payment by entering his/her PIN, fingerprint or face id and a payment request is sent to the Payconiq Backend for authorization.
  • A payment response with the details is sent back to the Payconiq App indicating a success or failure of the payment.
  • Payconiq backend sends a payment notification to the Merchant backend with the payment details to the callback url. The details of the notification will either contain success or failure details.
  • The merchant frontend displays the confirmation status it receives from Payconiq.
  • The consumer is notified of the payment status via the app.

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

Prerequisites

  • 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 payment to the merchant.


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


Create Payment

In order to begin a payment, you need to create a payment via the Payconiq through a POST request. A unique payment identifier is valid for two minutes (120 seconds) after which it expires. If a payment does not take place within these two minutes, a new payment has to be created.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments

PROD URL Definition: https://api.payconiq.com/v3/payments


Create Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.






Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
         "amount" : "1",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200"
      }'


Create Payment Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
callbackUrl
[URI, optional]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.
currency
[String, Optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
Value: EUR
description
[String, optional]
Maximum Length: 140 chars
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5aa9a9700000000000000000",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 112,
    "currency": "EUR",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdb1685b93d1c000bde96f2"
        },
        "cancel": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        }
    }
}


Create Payment Response

The following parameters are included in the header and body of the create payment response.


Response Header

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


Response Body

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
status
[String::enum, required]
Allowed values: PENDING
The status of the Payconiq Payment.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expiresAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remmittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
amount
[Integer, required]
Payment amount in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
creditor
[Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.










HTTP/1.1 400 Bad Request
{
    "traceId": "b2586833395d4750",
    "spanId": "c235e54376fab4b9",
    "code": "FIELD_IS_REQUIRED",
    "message": "Field 'amount' is mandatory"
}

Create Payments HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
400
[Integer]
BODY_MISSING: A JSON body needs to be provided.
FIELD_IS_REQUIRED: A mandatory field is missing from the JSON request.
FIELD_IS_INVALID: A field provided is not valid. Eg: The length of a field exceeds what is required.
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
MERCHANT_PROFILE_NOT_FOUND: The merchant profile for creating a payment does not exist.
422
[Integer]
UNABLE_TO_PAY_CREDITOR: This could be returned for multiple reasons in case something goes wrong.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


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 _links.qrcode.href 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.

Attribute Description
f
[String :: Enum]
Allowed Values: SVG, PNG
Image format
s
[String :: Enum]
Allowed Values: S, M, L, XL
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
The sizes 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 [email protected] for further assistance.


The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


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 payment is another sure way to know the status in order to complete the payment.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Cancel Payment

This endpoint is used to cancel a created Payconiq payment. A payment can only be cancelled only if the status is either PENDING or IDENTIFIED. Once cancelled, the status of the payment is set to CANCELLED.

Type: REST

HTTP Verb: DELETE

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Cancel Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx




Example Request:

curl -X DELETE
  https://api.ext.payconiq.com/v3/payments/5ba35a3d0989e3000758b9c1
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Cancel Payment Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Cancel Payment Request Body

There is no body in cancel payment request.


Cancel Payment Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the cancel payment response.

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


Cancel Payment Response Body

There is no body returned in the body of a cancel payment response.







HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "8abc6e29041adb94",
    "spanId": "6ba82033652b5b41",
    "code": "PAYMENT_NOT_PENDING",
    "message": "Payment '5ba35d610989e3000758b9cc' is not allowed to be cancelled"
}



Cancel Payment HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
CALLER_NOT_ALLOWED_TO_CANCEL: The merchant is not allowed to cancel this payment.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
PAYMENT_NOT_PENDING: Payment is not in a pending or identify state.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.

Payconiq Online (V3) - 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 requires 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.

NB Bulking with a bulk identifier is not supported for the Widget implementation.


Process Flow

Involved Parties:

  • Merchant Frontend – 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

  • Consumer visits the merchant website adds items to the cart and chooses to pay with Payconiq.
  • Merchant website loads the widget using the required parameters.
  • The Payconiq widget sends a request to the Payconiq backend to create a payment.
  • Payconiq backend returns the created payment with the payment id to the Payconiq widget.
  • The Payconiq widget displays the QR code on the Merchant’s website for the consumer to scan and pay.
  • Consumer scans the Payconiq QR Code using the Payconiq App.
  • The Payconiq App requests for the payment details from the Payconiq Backend and displays it for consumer confirmation.
  • The consumer confirms the payment by entering the PIN, fingerprint or face ID (iOS only).
  • The status of the payment is passed to the Payconiq widget and the Merchant Backend using the callback URL with the webhook id.
  • They Payconiq app is updated with the status of the payment.
  • 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 Product Profile Id – This is a unique identifier of the payment product used by a merchant.
  • Merchant Callback URL – An endpoint exposed to Payconiq to send back the status of each payment. This should be provided during the onboarding stage and an HTTPS Url.
  • API Key (Optional) – 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.


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


Add the Payconiq Widget Script

EXT Java Script Library:
<script data-payconiq-script="bootstrap"
  src="https://portal.ext.payconiq.com/v3/online/static/widget.min.js"
  async="true">
</script>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PROD JavaScript Library:
<script data-payconiq-script="bootstrap"
  src="https://portal.payconiq.com/v3/online/static/widget.min.js"
  async="true">
</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 [email protected].

Include the Payconiq JavaScript library in the header to your payment page. The library will automatically add a global method called ‘payconiq’ to the window and can be accessed from any location of your payment page. A button is also loaded which when clicked kicks off the Payconiq payment process.


Implement the Pay Button & Handle Events
















<button onclick="start_payment()">Pay with Payconiq</button>
<script type="text/javascript">
  start_payment = function() {
    payconiq({
      widgetType: 'popup',
      transactionData: {
        webhookId: 'Pq-payment-123',
        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 Payconiq Pay button contains the necessary logic to create and send a Payconiq payment to the Payconiq backend servers. As part of the Pay button implementation, the Payconiq widget generates events for for specific statuses that occur. The events should handled in order to show the correct and appropriate message to the consumer. It also allows you to gracefully handle your Payconiq interaction.

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

Parameters

Attribute Description
widgetType
[Enum :: String, required]
Allowed Values: [popup, inline]
This denotes the dialog type.
transactionData
[string, required]
An object which contains the widget payment parameters.
transactionData.webhookId
[String, required]
Max Length: 35 chars
A unique reference identifier provided by the merchant. The webhook id is also included in the callback request.
transactionData.merchantId
[string, required]
24 chars
The unique identifier of the merchant’s payment profile.
transactionData.amount
[String, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
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.)


Process The Payconiq Callback

Payconiq calls the merchant’s callback endpoint to send the status of a payment. This is only informational towards the merchant or partner. The webhookId will be used as a query string parameter and echoed back to the merchant backend.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

In addition to verifying the signature, the merchant must GET the payment details and compare it with the parameters used to setup the widget. The parameters to compare include the amount, currency and merchant id or profile id.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


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 payment is another sure way to know the status in order to complete the payment. You can search for a payment using the webhook id.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

NB: You can search for payments using the webhook id as the reference.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 -H 'Content-Type: application/json'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.


Payconiq Online (V3) - App2App Linking

Payconiq uses universal links to identify, address and transport users 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.


Process Flow

Involved Parties:

  • Payconiq Supported App – Payconiq consumer application.
  • Merchant Frontend – Merchant App or Mobile websie.
  • Merchant Backend – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.

W3Schools

Generic App2App Implementation Steps

  • Merchant App/Mobile website sends payment creation details to Merchant’s backend. This will contain at least the payment amount.
  • Merchant backend sends a REST request to the Payconiq backend to create a payment. The parameters passed in this request are the payment amount, payment currency, payment description and other parameters.
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including several links.
  • The merchant’s backend sends the payment id and the necessary universal link to the merchant app.
  • The merchant app/mobile website adds a return url to the Payconiq deeplink to create a universal link.
  • The merchant app/mobile website executes or fires off the constructed universal link to invoke the Payconiq app.
  • The Payconiq app requests for the payment details from the Payconiq backend.
  • Payconiq backend sends the payment details to the Payconiq App which would contain the name of the merchant and the amount to pay.
  • The consumer confirms the payment by entering his/her PIN, fingerprint or face id and a payment request is sent to the Payconiq Backend for authorization.
  • A payment response with the details is sent back to the Payconiq App indicating a success or failure of the payment.
  • Payconiq backend sends a payment notification to the merchant backend with the payment details via the callback url. The details of the notification will either contain success or failure details.
  • The Payconiq App returns the merchant app/mobile website by invoking the specified return url.
  • The merchant App/mobile website gets the payment details to determine the final status of the payment and presents it to the consumer.

Implementation Options

There are two ways in which we offer App linking:

  • App to App Linking
  • Mobile 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 a Payconiq supported app, and goes back to the original app after the payment is processed. A Payconiq URL is used to achieve this.

The URL is returned after a payment is created using the APIs. You will find the URL in a field with name _links.self.href. You simply need to append your return url in order to create a universal link.

Prerequisites Before implementing the App2App integration you should have the following.

  • 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.
  • Return Url - A url which is executed in the case of a successful or unsuccessful payment(This excludes special error cases). Your URL must be a universal link(mobile apps) in order for Payconiq to return to your app after finishing a payment. Universal links provides users with a seamless integrated mobile experience. It must also be a valid https URL encoded web or link.
  • Merchant Callback Url – This URL will be called by Payconiq’s backend servers in order to send the status of the payment to the merchant.


General iOS & Android Implementation Steps

  • Using credentials provided after onboarding, create a Payconiq payment.
  • Using the deeplink url and your returnUrl, construct a Payconiq universal URL.
  • Execute or fire off the constructed URL to switch to the Payconiq application.
  • After payment has been confirmed by the customer in the Payconiq App, the calling application is opened using the specified return url.
  • The payment status must be fetched by the calling application in order to determine the status of the payment.
  • To implement universal links in your iOS app, please follow this link.

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


Create Payment

In order to begin a payment, you need to create a payment via the Payconiq through a POST request. A unique payment identifier is valid for two minutes (120 seconds) after which it expires. If a payment does not take place within these two minutes, a new payment has to be created.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments

PROD URL Definition: https://api.payconiq.com/v3/payments


Create Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.






Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
         "amount" : "1",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200"
      }'


Create Payment Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
callbackUrl
[URI, optional]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.
currency
[String, Optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
Value: EUR
description
[String, optional]
Maximum Length: 140 chars
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5aa9a9700000000000000000",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 112,
    "currency": "EUR",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdb1685b93d1c000bde96f2"
        },
        "cancel": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        }
    }
}


Create Payment Response

The following parameters are included in the header and body of the create payment response.


Response Header

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


Response Body

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
status
[String::enum, required]
Allowed values: PENDING
The status of the Payconiq Payment.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expiresAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remmittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
amount
[Integer, required]
Payment amount in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
creditor
[Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.










HTTP/1.1 400 Bad Request
{
    "traceId": "b2586833395d4750",
    "spanId": "c235e54376fab4b9",
    "code": "FIELD_IS_REQUIRED",
    "message": "Field 'amount' is mandatory"
}

Create Payments HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
400
[Integer]
BODY_MISSING: A JSON body needs to be provided.
FIELD_IS_REQUIRED: A mandatory field is missing from the JSON request.
FIELD_IS_INVALID: A field provided is not valid. Eg: The length of a field exceeds what is required.
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
MERCHANT_PROFILE_NOT_FOUND: The merchant profile for creating a payment does not exist.
422
[Integer]
UNABLE_TO_PAY_CREDITOR: This could be returned for multiple reasons in case something goes wrong.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Apple iOS

/* Create Payconiq payment */
let createdPayment = createPayconiqPayment(amount: paymentAmount, "description": paymentDescription, "reference": paymentReference, "currency": paymentCurrency, "callbackUrl": paymentCallbackUrl)

//Get deeplink url from created payment
let deeplinkUrl = createdPayment.deeplinkUrl

//Specify return url
let returnUrl = "?returnUrl=https://example.com"

//Start the Payconiq Application
if let url = URL(deeplinkUrl + returnUrl) {
    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
    }
}

The following parameters are used to invoke the Payconiq

Attribute Description
_links.deeplink.href
[String :: URI]
URL String used to perform App2App linking
Return Url
[String:: URI]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.

iOS Universal Link Integration

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

// Create a Payconiq Payment
PayconiqPayment createdPayment = createPayconiqPayment(amount, description, reference, currency, callbackUrl);

//Get the deeplink url from the created payment
String deeplinkUrl = createdPayment.getDeeplinkUrl();

// Construct the universal link
String returnUrl = "https://example.com/";
String universalLink = String.format(deeplinkUrl + "?returnUrl=%s", returnUrl);

// Start the Payconiq application
startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(universalLink)));

The following parameters are used to invoke the Payconiq

Attribute Description
_links.deeplink.href
[String :: URI]
URL String used to perform App2App linking
Return Url
[String:: URI]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.


Mobile Browser to App Linking

For the Browser to App linking, the link returned in the field with name _links.self.href after a payment has been created is used.

A return url is needed in order to return to the page from where the Payconiq App was called.

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, create a Payconiq payment.
  • Using the deeplink url and your returnUrl, construct a Payconiq universal URL.
  • Execute or fire off the constructed URL to switch to the Payconiq application.
  • After payment has been finalized by the customer in the Payconiq App, the calling website is opened using the specified return url.
  • The payment status must be fetched by the calling application in order to determine the status of the payment.


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.


iOS Browser2App Linking (EXT & PROD)

<script>
function createPayconiqUniversalLink()
{
  var deeplinkUrl = getDeeplinkUrlFromPaycconiqPayment();
  var returnUrl = "?returnUrl=www.example.com";
  return deeplinkUrl.concat(returnUrl);
}
</script>

<button>
  <a href = "createPayconiqUniversalLink()>
      Pay with Payconiq 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

<script>
function createPayconiqUniversalLink()
{
  var deeplinkUrl = getDeeplinkUrlFromPaycconiqPayment();
  var returnUrl = "?returnUrl=www.example.com";
  return deeplinkUrl.concat(returnUrl);
}
</script>

<button>
  <a href = "createPayconiqUniversalLink()">
    Pay with Payconiq 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.

The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payconiq Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


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 payment is another sure way to know the status in order to complete the payment.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payconiq payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payconiq payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payconiq payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payconiq payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payconiq payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payconiq Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payconiq payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payconiq payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payconiq payment service.

Migrating from V2 to V3

Why upgrade to v3?

The Payconiq Payments API V3 takes advantage of Payconiq’s new payment processing platform which allows Payconiq to offer more products and features in shorter development times.

It also has the following new features:

  • Payconiq has put together a more enhanced and enriched API compared to v2. This is the starting base of our v3 APIs with more features to come.
  • Adoption of the HAL specification which would allow you to discover new resources and follow links to new resources while working with the APIs.
  • Improved error messages. Payconiq error messages will include more details to quickly help you resolve any problems.
  • Offers new products (Payconiq Instore Receipt, Payconiq Instore Top-Up, Payconiq Instore QR-predefined amount and Payconiq Invoice) and feature possibilities.
  • For widget payments, a signature is no long required in order to create a payment.

The following changes have been implemented.

Changes to Error Objects

The following fields have been added:

  • traceId – The unique identifier that is assigned to a single request or job.
  • spanId – The unique identifier of work unit where the error occurred.

The following error codes have been added:

  • UNAUTHORIZED – An incorrect API key is used to access the API’s.
  • ACCESS_DENIED – Access has been denied to the requested resource.
  • PAYMENT_NOT_FOUND – A payment cannot be found.
  • TECHNICAL_ERROR – An error occurred in the Payconiq payment service.
  • CALLER_NOT_ALLOWED_TO_CANCEL – Calling party is not allowed to cancel a payment.
  • PAYMENT_NOT_PENDING – A payment is not pending
  • BODY_MISSING – A JSON body missing from the request.
  • FIELD_IS_REQUIRED – A JSON field is missing from the request.
  • FIELD_IS_INVALID – A JSON field is is invalid.
  • UNABLE_TO_PAY_CREDITOR – Returned when something goes wrong while trying to pay the merchant.
  • TRY_AGAIN_LATER – An internal error occurred while processing a payment.
  • REFUND_NOT_ALLOWED – A refund is not allowed for a payment.
  • REFUND_NOT_AVAILABLE – A refund is not possible on a payment.
  • MERCHANT_PROFILE_NOT_FOUND – The details of a merchant don’t exist for a payment being created.

The following error codes have been removed:

  • R002, R003, R004, R013, R017, R200, R201, R203, R204, R205, R221, R602, R918, R934, R957, R967, R969, R981, R979, R999.


Changes to Status Types

The following changes have been made in regards to the status of payments:

The following statuses have been removed:

  • CREATION
  • CONFIRMED
  • BLOCKED

The following statuses have been renamed:

  • CANCELED to CANCELLED (UK English spelling).
  • TIMEDOUT to EXPIRED

The following statuses have been added:

  • AUTHORIZED
  • AUTHORIZATION_FAILED
  • IDENTIFIED


Changes to Create Payment API

Create Payment API Request Changes

The following fields have been added:

The following fields have been renamed:

  • externalRefId has been renamed to reference.

The following fields have length restrictions:

  • reference has a length restriction of 35 chars.
  • description has a length restriction of 140 chars.
  • bulkId has a length restriction of 35 chars.

    Create Payment API Response Changes

    The following fields have been added:
  • status – This indicates the status of a created payment.
  • createdAt – The time when the payment was created.
  • expiresAt – The time when the payment expires.
  • reference – The payment reference from the merchant’s system.
  • amount – the amount of the created payment.
  • currency – The currency code of the created payment.
  • creditor – An object in the creditor of the payment.
  • creditor.profileId – The unique payment product identifier of the merchant.
  • creditor.merchantId – The unique identifier of the merchant.
  • creditor.name – The name of the merchant.
  • creditor.iban – The IBAN of the merchant.
  • creditor.callbackUrl – The callback url of the payment set by the merchant.
  • _links – A JSON object containing URIs which allows new resources to be discovered as per HAL specifications.
  • _links.self – A url object to get the payment details.
  • _links.deeplink – A url object used to initiate App to App links.
  • _links.qrcode – A url object to download the Payconiq branded QR code.
  • _links.cancel – A url object to cancel a payment.

The following fields have been renamed:

  • transactionId has been renamed to paymentId.
  • qrUrl has been renamed to _links.qrcode. This can now be found in the _links object which follows the HAL specifications.

The date time format for all dates is YYYY-MM-ddTHH:mm:ss.SSSZ – The time is in a UTC format and there is no offset for the timezone.


Changes to Get Payment Details API

Get Payment API Request Changes

There are no changes to the request.

Get Payment API Response Changes

The following fields have been added:

  • expireAt – The time when the payment expires.
  • reference – The payment reference from the merchant’s system.
  • tippingAmount – The amount added as a tip by the consumer in Euro cents.
  • totalAmount – The amount the consumer pays in total in Euro cents.
  • transferAmount – The amount the consumer will be charged in Euro cents.
  • message – Custom message from the consumer
  • _links – an object containing URIs which allows new resources to be discovered as per HAL specifications.
  • _links.self – a url object to get the payment details.
  • _links.deeplink – a url object used to initiate App to App links.
  • _links.qrcode – a url object to download the Payconiq branded QR code.
  • _links.cancel – a url object to cancel a payment.
  • _links.refund – a url object to get an IBAN to refund a payment.
  • creditor.iban – the IBAN of the creditor.
  • creditor.type – The type of the creditor.
  • creditor.merchantId – The unique identifier of the merchant.

The following fields have been renamed:

  • _id has been renamed to paymentId.
  • creationDate has been renamed to createdAt and has a new date format.
  • originUser object has been renamed to debtor.
  • originUser.firstName has been renamed to debtor.name.
  • originIBAN has been renamed to debtor.iban.
  • targetUser object has been renamed to creditor.
  • targetUser._id has been renamed to creditor.profileId.
  • targetUser.companyName has been renamed to creditor.name.
  • targetIBAN has been renamed to creditor.iban.
  • callbackUrl has been renamed to creditor.callbackUrl.

The following fields have been removed:

  • targetId
  • origin
  • endToEndId

The date time format for all dates is YYYY-MM-ddTHH:mm:ss.SSSZ – The time is in a UTC format and there is no offset for the timezone.


Changes to Get Payment List API

Get Payment List API Request Changes

The following fields have been renamed:

  • limit has been renamed to page.
  • size has been renamed to offset.
  • status has been renamed to paymentStatus.
  • externalRefId has been renamed to reference.

The following fields have been removed:

  • userId

Get Payment List API Response Changes

The following fields have been added:

  • size – the total size of elements returned.
  • totalPages – the total number of pages returned.
  • totalElements – Total number of elements returned for the search criteria.
  • number – the current page number.
  • details – an array object containing payment details.
  • details.expireAt – The time when the payment expires.
  • details.reference – The payment reference from the merchant’s system.
  • details.tippingAmount – The amount added as a tip by the consumer in Euro cents.
  • details.totalAmount – The amount the consumer pays in total in Euro cents.
  • details.transferAmount – The amount the consumer will be charged in Euro cents.
  • details.message – Custom message from the consumer.
  • details.bulkId – The bulk identifier of a payment.
  • details._links – an object containing URIs which allows new resources to be discovered as per HAL specifications.
  • details._links.self – a url object to get the payment details.
  • details._links.deeplink – a url object used to initiate App to App links.
  • details._links.qrcode – a url object to download the Payconiq branded QR code.
  • details._links.cancel – a url object to cancel a payment.
  • details._links.refund – a url object to get an IBAN to refund a payment.
  • details.creditor.iban – the IBAN of the creditor.
  • details.creditor.type – The type of the creditor.

The following fields have been renamed:

  • _id has been renamed to details.paymentId.
  • creationDate has been renamed to details.createdAt and has a new date format.
  • originUser object has been renamed to details.debtor.
  • originUser.firstName has been renamed to details.debtor.name.
  • originIBAN has been renamed to details.debtor.iban.
  • targetUser object has been renamed to details.creditor.
  • targetUser._id has been renamed to details.creditor.id.
  • targetUser.companyName has been renamed to details.creditor.name.
  • targetIBAN has been renamed to details.creditor.iban.
  • callbackUrl has been renamed to details.creditor.callbackUrl.

The following fields have been removed:

  • targetId
  • origin
  • endToEndId

The date time format for all dates is YYYY-MM-ddTHH:mm:ss.SSSZ – The time is in a UTC format and there is no offset for the timezone.


Changes to the Refund API

There was no refund endpoint documented in V2 and you were required to fetch the IBAN from the payment details in order to perform a refund. In V3, an endpoint has been provided to return only the IBAN of the consumer. The transfer of funds to the consumer has to be performed using the IBAN that has been retrieved.


Changes to the Callback

Callback Header Changes

The following fields have been added:

  • Signature – This represents a Payconiq digitally signed content using JSON data structures and base64url encoding.

The following fields have been removed:

  • X-Security-Signature
  • X-Security-Timestamp
  • X-Security-Key
  • X-Security-Algorithm


Callback Request Changes

The following fields have been added:

  • tippingAmount – The amount added as a tip by the consumer in Euro cents.
  • totalAmount – The amount the consumer pays in total in Euro cents.
  • transferAmount – The amount the consumer will be charged in Euro cents.
  • currency – Payment currency code in ISO 4217 format. Only Euros supported at the moment.
  • amount – Payment amount in Euro cents.
  • description – Custom description of the payment.
  • createdAt – The creation date and time of a Payconiq payment.
  • expireAt – The date and time when a Payconiq Payment expires.
  • debtor – The consumer account object that makes payments to the merchant.
  • debtor.name – The name of the consumer
  • debtor.iban – The masked IBAN of the consumer.

The following fields have been renamed:

  • _id has been renamed to paymentId.
  • externalRefId has been renamed to reference.


Changes to the Payconiq Widget

Changes to the Payconiq Pay button

The following field has been removed when implementing the Pay Button.

  • signature

The Payconiq widget now makes use of Universal links in order perform App2App links.


API Version 2 (V2) - Merchant

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.

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.
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 statuses that are most important to the implementation are as follows and have been described above. These are returned as the end state of a transaction.

  • SUCCEEDED
  • FAILED
  • TIMEDOUT
  • CANCELED
  • CONFIRMED

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

  • CREATION
  • PENDING


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.

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

Upcoming Certificate Change

The following certificate comes into effect on 10th April 2019.

Certificate Environment Valid From Expiry Date
(New) Prod Certificate
signature.payconiq.com:443
10th April 2019 11th March 2021

Current Certificates Change

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

No Callback Signature Validation

If you are not interested in validating the callback signature, Payconiq strongly recommends getting the payment details after receiving the callback notification by calling the Get Transaction Details API. Validating the callback signature is optional.

Getting the transaction details is an additional REST call from your setup but enforces security just as validating the signature does. The REST call is made by making use of the API key to invoke the request.

You can also search for payments using a specific date range or a reference using the Get Transaction List API call.


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 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 [email protected] 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",
               "bulkId":"Bulk-1-200"
}'


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
Must be https
description
[string, optional]
Custom description of the transaction. For reconciliation purposes, details in description field will reflect on the bank statement. Max Length: 140 chars
externalRefId
[string, optional]
External reference number of calling party Max Length: 35 chars
bulkId
[string, optional]
A field set by the merchant used to reference a bulk batch payment. If not set, bulking is done baed on the IBAN. Max length: 35 chars























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 [email protected] 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.


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",
   "bulkId":"Bulk-1-200"
}



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.
bulkId
A field set by the merchant used to reference a bulk batch payment.


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",
   "bulkId":"Bulk-1-200"
   },
 {…},
 {…}
]



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.
bulkId
A field set by the merchant used to reference a bulk batch payment.


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.

NB Bulking with a bulk identifier is not supported for the Widget implementation.


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.

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

Optional

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

If the above required information is not available, please send us an email on [email protected] 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 [email protected].

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 [deprecated]

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
[object, required]
This is an object which contains the transaction parameters
transactionData.webhookId
[string, required]
Maximum Length: 35 chars
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, optional]
A string with a unique value that is used to sign the current payment
transactionData.merchantId
[string, required]
Length: 24 chars
Unique identifier of merchant with Payconiq system
transactionData.amount
[string, required]
Minimum: 1
Maximum: 999999
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.

In addition to verifying the signature, the merchant must GET the payment details and compare it with the parameters used to setup the widget. The parameters to compare include the amount, currency and merchant id or profile id.

The backend must respond with an HTTP 200 OK status code to confirm receipt of the notification.


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 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 [email protected] 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
Must be https
description
[string, optional]
Custom description of the transaction. For reconciliation purposes, details in description field will reflect on the bank statement. Max Length: 140 chars
externalRefId
[string, optional]
External reference number of calling party Max Length: 35 chars

























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 [email protected] 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.


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 Partner Integration Guide

The Partner Integration Guide is intended for Partners that have entered into an agreement with PQI for the integration of Payconiq via the Payment Service Provider API. This enables Submerchants accept Payments and for Partners to collect Payments on behalf of the Submerchant. The Partner Integration Guide provides the necessary documentation for Partners to develop an integration with PQI’s Payment Service Provider API. PQI has the right to update the Partner Integration Guide in accordance with the conditions laid down in the Agreement and accompanying Schedules, including the SLA.


About the Payconiq Partner program

PQI allows Partners to integrate with PQI' Dynamic QR proposition, so Partners can collect Payments on behalf of their customers. Customers of Partners are known as Submerchants. Partners must be authorised to provide payment services by competent regulators in the EU member states where they operate.

In the Payconiq partner program, there are at least four parties identified who play a role in a payment. These parties are:

  • The consumer – The consumer uses a mobile app that supports Payconiq and uses that app to scan the Dynamic QR Code presented by the Submerchant. The consumer approves the Payment on a mobile device using the mobile app.
  • PQI – – A licensed payment institution and the service provider (IT infrastructure) that services both consumers and Partners in order to complete Payments. For this purpose the Payconiq backend exposes an API, for the integration with Payconiq.
  • The Partner – Partners integrate with Payconiq in order to collect Payments on behalf of the Submerchants, who are their customers.
  • The Submerchant – Submerchants are customers of Partners that integrate with Partners in order to allow Partners to collect Payments on the Submerchants behalf.

The Payment Service Provider API allows Partners to create Payments, receive Payment statuses, get Payment details, cancel Payments, search for Payments and get IBAN for refunds via the endpoints and process payment callbacks.

The Payment Service Provider API can be used in both instore (terminal) and online (webshop) payments.


The Partner may consume the following Payment Service Provider API calls on the Payconiq backend:

Payment Service Provider API Description
Create Payment API The Create Payment API is used by the Partner to create a Payment via the Payconiq backend.
Cancel Payment API The Cancel Payment API is used by the Partner to cancel a Payment via the Payconiq backend.
Get Payment Details API The Get Payment Details API is used by the Partner to get a Payment details created via the Payconiq backend.
Search Payments API The Search Payment API is used by the Partner to search for transaction payments created via the Payconiq backend.
Get consumer’s Refund IBAN API The Get Consumer Refund IBAN API is used by the Partner to get the consumer’s IBAN for refund purposes via the Payconiq backend.


The Partners may provide a callback API endpoint on their respective platforms for Payconiq to consume.

Payment Service Provider API Description
Payment Callback API The Payment Callback is used by Payconiq to inform the Partner of the final status of a Payment if configured while creating a payment.

Definitions

The following definitions and their meanings are used in the Partner Integration Guide:

Terminology Description
Payment Service Provider Application Program Interface (API) A set of functions exposed by the Payconiq back-end which allows the Partner to access the features and functionality provided by PQI to facilitate Payments.
Application Program Interface Key (API Key) A code passed by the Partner with every call to Payconiq. It grants access to the Partner in order to interact with the Payconiq backend. An API key is linked to a Payment Profile of the partner.
Payconiq External Environment (EXT) The Payconiq non-production environment where Partners test integrations before switching to the production environment.
Payconiq Production Environment (PROD) The Payconiq live environment where actual Payments take place.
Payconiq Merchant Identifier A unique identifier representing the Partner in the Payconiq backend. (The usage of Merchant Identifier rather than Partner Identifier is for backwards compatibility reasons only.)
Payment Profile A collection of settings that parameterize the PQI product offering towards the Partner. A payment profile describes how the Partner wants their payment to be configured.
Payment Profile Identifier A unique identifier representing the Payment Profile the Partner has subscribed to.
Dynamic Quick Response (QR) Code This is a combination of deep magenta squares arranged in a square grid on a white background which can be scanned by an imaging device such as a camera.
Payconiq Payment Button A link to consumers which allows consumers to start a Payment at the Submerchant shop/webshop.

Getting Started

Partner Onboarding

Partners that wish to collect Payments on behalf of Submerchants and enable Submerchants to accept Payments will have to integrate with the Payment Service Provider API. The first step is the integration on a test environment where the Partner can test the Payment Service Provider API. Following signature of the Agreement, Partner will be able to offer Payments to its customers (Submerchants) in a production (live) environment.

As part of the onboarding process PQI will provide an API Key, a Merchant Identifier and Payment Profile Identifier. The API Key will be used to gain authorised access to the Payment Service Provider API endpoints. PQI distributes the API Key, Merchant Identifier and Payment Profile Identifier to an email address provided for that purpose by the Partner.

As soon as the Partner has developed and tested an integration successfully the Partner may request PQI to grant access to the Production Environment (PROD). PQI may request the Partner to perform a specified test set and share the results, before PQI grants access. Before operations can commence on the Production Environment a signed agreement must be in place between Partner and PQI.


Environments

External Environment (EXT)

The EXT environment is a non-production environment intended for Partners to test their integrations. For this purpose the EXT environment offers the same (or newer) API as the Production Environment (PROD). Tests performed with the EXT environment will never result in ‘real’ Payments, where funds are credited to payment accounts. The EXT environment also does not support related features such as billing and bulking. Payconiq will provide the Partner with an API Key, a Merchant Identifier and Payment Profile Identifier applicable for this environment only.

PQI provides apps for both Android and iOS, that can be used for testing purposes on the EXT environment. Upon request, PQI will provide the links to the Partner to download and test their integration.

Production Environment (PROD)

The PROD environment is a production environment to be used to handle actual Payments. A successful Payment on the PROD environment will cause the consumer’s payment account (held with the Consumer’s bank) to be debited and the Partner’s payment account (held with the Partner’s bank) to be credited. The funds may also be credited to PQI’s payment account or PQI’s customer account foundation’s payment account. Payconiq will provide the Partner with an API Key, a Merchant Identifier and Payment Profile Identifier which will be different than the ones on the EXT environment

The apps for the PROD environment are publicly available and can be dowloaded on the Apple App Store and via the Google Play Store.


Partner Off-Boarding

External Environment (EXT)

If the Partner wishes to stop using Payconiq to facilitate payments in the EXT environment, PQI will unregister the Partner. When the partner is unregistered, the issued API Key is invalidated and can no longer be used to access the Payment Service Provider API on the EXT environment. The Merchant Identifier and Payment Profile Identifier are also invalidated.

Production Environment (PROD)

If the Partner wishes to stop using Payconiq to facilitate payments in the PROD environment, by terminating the Agreement, PQI will unregister the Partner following the required notice period. When the partner is unregistered, the issued API Key is invalidated and can no longer be used to access the Payment Service Provider API on the PROD environment. The Merchant Identifier and Payment Profile identifier are also invalidated. PQI will conclude all Payments pending at the time of the termination or expiration of the Agreement.


Default Remittance Information

A successful Payment results in a credit transfer from the consumer’s (payer) payment account (held with the consumer’s bank) to the Partner (payee) payment account (held with the Partner’s bank). There are 2 exemptions to this:

  1. If the consumer onboarded via a SEPA Direct Debit (SDD) eMandate then PQI (or PQI’s customer account foundation) will credit Partner’s payment account.

  2. If the Partner makes use of the Payconiq Bulking Service, then PQI (or PQI’s customer account foundation) will credit Partner’s payment account via aggregated amounts in a batched fashion in accordance with a timetable agreed between Partner and PQI.


Bank Statement Description

When a Payment reaches the final status “SUCCEEDED”, then the Payconiq backend initiates a credit transfer (or direct debit) from the consumer’s payment account (held with the consumer’s bank) to the Partner’s payment account (held with the Partner’s bank) or PQI’s payment account(or PQI’s customer account foundation’s payment account). The remittance information provided with the credit transfer has a maximum length of 140 characters (as standardized by the European Payments Council / EPC). These 140 characters will be encoded per default as concatenated string values, separated by spaces, in accordance with the table below. Banks provide this remittance information in online banking environments and/or paper bank statements.

Sample Remittance Information


"Payconiq f60454fd52e429d71964745d Online Kassa            4zyeYIKOw54Ybc9yenL5                Mars Bars                          "

Field Name Description Format
Issuer The entity that facilitates Payconiq Payment String
[Max Length: 8]
Delimiter Field separator String: Space
[Max Length: 1]
Payconiq Payment Identifier A unique identifier representing a Payconiq Payment Transaction
Delimiter Field separator String: Space
[Max Length: 1]
Sub Merchant Name The name of the merchant where the Payconiq Payment Transaction takes place. Field is padded with spaces if the max length is not reached String
[Max Length: 23]
Delimiter Field separator String: Space
[Max Length: 1]
Reference A unique identifier referencing a Payconiq Payment Transaction in the Partner's system. Field is padded with spaces if the max length is not reached. String
[Max Length: 35]
Delimiter Field separator String: Space
[Max Length: 1]
Description A description linked to a Payconiq Payment Transaction. Field is padded with spaces if the max length is not reached. String
[Max Length: 46]

An example of the remittance information entry is as follows for the sample values provided in the table above.

“Payconiq f60454fd52e429d71964745d Online Kassa            4zyeYIKOw54Ybc9yenL5                Mars Bars                          ”

Remark: The above does not apply to the bulked Payconiq Payments.


Payconiq Style Guide

Payconiq requires a consistent (user) experience across Partners and their Submerchants. Therefore Partners must follow the presentation requirements described in this section, as provided in the Agreement. Partners must ensure that Submerchants adhere to these presentation requirements in their instore or online checkout environment.

The Payconiq Payment Method

A Submerchant that accepts Payconiq as a payment method has to include Payconiq in the list of payment methods shown to consumers. It must be easily recognizable and must be as noticeable to consumers as other payment methods (if any).


The Dynamic QR Code

The Dynamic QR code must be branded with the Payconiq logo. The branding gives trust and makes it easy for consumers to see where they can pay with Payconiq. The Payconiq primary color is magenta(#FF4785). Instead of black, the Payconiq Dynamic QR Code must be displayed using the darkest shade of magenta (#7B314A) to match our primary colour (Magenta) but still keeping the contrast.

In the successful response to a Create Payment API call, a hyperlink is included that points to a url where the Payconiq Dynamic QR code with the Payconiq logo and the correct coloring can be downloaded as a PNG or SVG file. It is possible to retrieve the Payconiq QR code in different sizes.

Below is a Payconiq QR code placed over a Payconiq frame with a 10% border around the QR code (bottom and sides).

QR Code


Dynamic QR Code Sizes and Scan Distances

The following Dynamic QR Code sizes must be taken into consideration depending on the scanning distance of the consumer. This provides the consumer with an optimal experience when scanning the Dynamic QR code.

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 Frames

Payconiq provides a branding frame consisting of a magenta border and a Payconiq logo. The Payconiq Dynamic QR code must be embedded in this frame when presented to the consumer. The frames are available in both PNG and SVG formats.

An example frame before a Payconiq Dynamic QR code is embedded for consumer scanning.

QR Code

Below is an example of the final implementation of the Payconiq Dynamic QR code and Payconiq frame there is a 10% border around the Dynamic QR code (bottom and sides).

QR Code

Below are the frame formats that are available for download:

Description Format
Frame - Small PNG
Frame - Medium PNG
Frame - Large PNG
Frame - Extra Large PNG
Frame - Small SVG
Frame - Medium SVG
Frame - Large SVG
Frame - Extra Large SVG


The Payconiq Payment Button

The Payconiq Payment Button provides a clickable link to consumers which takes them to a Payconiq checkout environment with the Submerchant of a Partner. The Payconiq Payment Button must make clear to the consumer how and when the Payconiq payment method has been selected as a way to pay. This is achieved by showing the Payconiq Payment Button to the consumer before a Payment is made.

There are two ways to display the Payconiq Payment Button.


Method 1: The Complete Logo This is the complete Payconiq Logo which must be shown to the consumer indicating Payconiq as a payment method.

Payconiq Logo

Below are the full logos which can be used on your payment terminal or checkout page.

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


Method 2: The Payconiq mark. (With accompanying text)

Alternatively, Partners may display only the Payconiq mark as depicted below.

Payconiq Mark

Below are the full marks which can be used on your payment terminal or checkout page.

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

Partners who wish to display the Payconiq logo in a way that deviates from this document must contact PQI for approval and assistance.

Partners must use the SVG format when the display resolution exceeds the resolution of the generated Dynamic QR code to ensure the display of a sharp image.


The Payconiq Partner Integration API

The Payment Service Provider API is organized around REST and uses HTTP response codes to indicate API errors or success. In addition, standard HTTP features such as header authentication and HTTP verbs which are understood by many off the shelf HTTP clients are used.

Authentication

The Application Program Interface Key

All requests to the Payconiq backend are authenticated using an API Key. The API Key must be included in all API requests through the HTTP Authorization header. The API Key is a hexadecimal string in the form of a universally unique identifier (UUID) and identifies a unique product the Partner offers. The API Key is 36 characters long and all requests without an API Key will fail.

It is the responsibility of the Partner to keep the API Key confidential. The Partner should inform PQI as soon as the confidentiality of the API Key is compromised and request a new API Key. Partners may have multiple API Keys when using multiple Payment Profiles or multiple merchant accounts.

Message Encryption

All requests to the Payconiq backend are encrypted using TLS 1.2 or TLS 1.3 and must be made over HTTPS. The TLS authentication method used is one-way where only the Partner validates the Payconiq backend to ensure that it receives data from the intended backend. There is no mutual TLS authentication between the Partner and the Payconiq backend. The Payconiq backend refuses any connections without TLS encryption, such as plain HTTP.


Status Codes

The Payconiq Payment Service Provider 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, incorrect credentials, etc.) and codes in the 5xx range indicate an error with the Payconiq backend. It is the Partner’s responsibility to handle all errors programatically.

HTTP Codes Returned by Payconiq’s Backend

When a request from the Partner is successfully processed by the Payconiq backend, the following HTTP codes are returned.

Status Code Description
200 - OK Everything works as expected.
201 - Created Payconiq has successfully fulfilled the request to create a payment.
204 - No Content Payconiq has successfully fulfilled the request to cancel a payment.

When a request from the Partner is not processed successfully by the Payconiq backend, the following HTTP codes are returned indicating an error.

Status Code Description
400 - Bad Request The request was unacceptable. This usually happens when there are missing parameters.
401 - Unauthorized The API key provided is not valid.
403 - Forbidden The user is not allowed to access the resource requested.
404 - Not Found The requested resource does not exist.
422 - Unprocessable Entity Payconiq cannot process the request due to restrictions.
429 - Too Many Requests This error code is returned when there are too many requests to the Payconiq backend.
500 - Internal Server Error Something went wrong on the Payconiq backend.
503 - Service Unavailable Something went wrong on the Payconiq backend.

Payconiq Payment Statuses

A Payconiq Payment status indicates the situation of a Payment. The statuses are included in the body of the following:

  • Create Payment API response
  • Get Payment Details API response
  • Search Payment API response
  • Payment Callback request

Statuses may be either final or intermediary. When a Payconiq payment has a status that is final, the status does not change. However, when a Payconiq payment has a status that is intermediary, the status can change into one of the final statuses.

Below is the list of statuses that are returned by the Payconiq backend.

Status Name Status Description Stage
PENDING A Payment has been created and it has not been scanned. Consumers can scan Dynamic QR code linked to this Payment and confirm it. Intermediary
IDENTIFIED A Payment has been scanned by a Payconiq supported app and is pending confirmation or cancellation. Intermediary
AUTHORIZED This is the status of a Payment before it is set to SUCCEEDED. Payconiq internal checks for Payments that are successful. This occurs before the payment is sent to the bank for processing. Intermediary
SUCCEEDED A Payment has been authorized and processed successfully by Payconiq and the consumer's bank. This the final end state of a successful Payment. Final
AUTHORIZATION_FAILED This occurs when a Payment is not authorized due to validation reasons. These reasons include insufficient funds, limits exceeded, etc. Final
CANCELLED A Payment has been cancelled by a merchant or consumer. If a Payment is cancelled, it cannot be scanned and paid. Final
FAILED Something has gone wrong while confirming a Payment such as incorrect consumer or partner data setup. Final
EXPIRED A Payment has exceeded the allowable time to pay. If a payment has expired, it cannot be paid. Final

Payconiq Errors

The Payment Service Provider API uses conventional HTTP response codes in combination with a JSON body to indicate failure of a Payment Service Provider API request. The JSON body of the error structure is the same for all requests. The body of an error response will contain a code, message, traceId and spanId. The four fields are described below.

Error Response Definition

Attribute Comment/Format
code - Text describing the error that has occurred. [String, required]
UNAUTHORIZED, ACCESS_DENIED,
PAYMENT_NOT_FOUND,
TECHNICAL_ERROR,
CALLER_NOT_ALLOWED_TO_CANCEL,
PAYMENT_NOT_FOUND,
PAYMENT_NOT_PENDING,
PAYMENT_CONFLICT,
BODY_MISSING,
FIELD_REQUIRED,
QR_NO_LONGER_IN_USE,
UNABLE_TO_PAY_CREDITOR,
TRY_AGAIN_LATER
message - Text describing the error that has occurred. [String, required]
traceId - The id that is assigned to a single request or job. [String, required]
spanId - The id of work unit where the error occurred. [String, required]

Handling Errors

The Partner must handle errors and show an appropriate message to the consumer or Submerchant in the event of any errors. This will allow the consumer and Submerchant to react appropriately


Payment Callback

A Partner can define a specific URL (callback URL) that the Payconiq backend will use to notify the Partner regarding the status of a Payment. This allows the Partner to react to the Payment and process the data. The callback requests are issued via HTTP POST and are asynchronous therefore the order in which they arrive is not guaranteed. The callback sent by the Payconiq backend comprises of header parameters and a JSON body.

All callback requests will be encrypted using one-way TLS where the Payconiq backend verifies the certificate of the Partner anytime Payconiq sends a callback request. Payconiq does not support two-way TLS encryption for its callback request.

Callback Headers

The callback consists of headers of which some are informational and others used to validate the signature of the callback. The parameters in the header are made up of the following: Signature, User-Agent and Content-Type.

Name Description
signature This represents a Payconiq digitally signed content using JSON data structures and base64url encoding which makes up the JSON Web Signature (JWS).
user-agent 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 The Content-Type entity header is used to indicate the media type of the resource.

The Callback Signature

To prove that Payconiq generated the callback to the merchant, the Payconiq API sends a detached JSON Web Signature(JWS) which includes the signed base64UrlEncoded header and request body. The signature is signed using a publicly hosted certificate. A JWS represents these logical values separated by dots(.):

  • JOSE Header
  • JWS Payload (Not included)
  • JWS Signature

The signature will be generated as per following instructions:

jws = base64URLEncode(JOSE Header)..base64URLEncode(alg(base64URLEncode(JOSE Header).base64URLEncode(Request Body)))


Terminologies

Name Description
JSON Web Signature (JWS) A data structure representing a digitally signed message.
JSON Object Signing and Encryption (JOSE) Header JSON object containing the parameters describing the cryptographic operations and parameters employed.
JSON Web Key (JWK) A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.
JSON Web Key Set (JWKS) A JSON object that represents a set of JWKs.


JOSE Header Fields

The JOSE Header setup by Payconiq consists of the following:

Header Parameter Description
typ - Type The "typ" (type) Header Parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of this complete JWS.
kid - Key ID The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS
alg - Algorithm The "alg" (algorithm) Header Parameter identifies the cryptographic algorithm used to secure the JWS.
crit - Critical The "crit" (critical) Header Parameter indicates that extensions to this specification and/or [JWA] are being used that MUST be understood and processed.

{

"typ": "jose+json",

"kid": "JWK kid",

"alg": "ES256",

"crit": ["https://payconiq.com/sub", "https://payconiq.com/iss", "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path"],

"https://payconiq.com/sub" : "{merchantProfileId}",

"https://payconiq.com/iss" : "Payconiq",

"https://payconiq.com/iat" : "{Current creation date time in [ISODateTime format], expressed in UTC time format(YYYY-MM-DDThh:mm:ss.sssZ)},

"https://payconiq.com/jti" : "{Unique-request-identifier}",

"https://payconiq.com/path": "callback request path ex. https://www.merchantcallback.com/payconiqpayment"

}

Verifying the Callback Signature

The merchant or Partner must verify the signature in order to obtain cryptographic proof regarding the integrity and authenticity of the message. The Partner should store both the message body and the signature in order to be able to provide evidence of integrity and authenticity of the message in the event of a dispute.

To verify the JWS, refer to the JWS documentation which provides extensive guidelines.

Alternatively, the following steps can be performed to verify the signature. If any of the listed steps fails, then the signature cannot be verified.


Notes

  • Prior to verifying the signature, you can cache the full JWKS. This ensures that the JWKS is not always downloaded via the URL to verify the signature.
  • To know which JWK to use in verifying the signature, retrieve the JWK whose key id matches with the key id in the JOSE Header of the signature.
  • The JWKS can be downloaded and re-cached whenever the key id in the JOSE Header does not match what was previously cached.
  • The ES256 signature algorithm is whitelisted. The algorithm of the JWK.


Steps

  • This assumes that the JWKS has been cached.
  1. Extract the "kid" field from the JOSE Header of the signature.
  2. Compare the extracted "kid" with the cached "kid" in the JWKS. If there is a match, jump to step 3. If they do not match, jump to step 4.
  3. Use the cached JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".

  4. Refresh the JWKS cached by downloading the latest JWKS.

  5. Extract the "kid" field from the JOSE Header of the signature to retrieve the corresponding JWK.
  6. Used the cached JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".


  • This assumes that the public key certificate has not been cached.
  1. Extract the "kid" field from the JOSE Header of the signature.
  2. Download the JWK which matches the key id ("kid") field in the JOSE Header of the signature.
  3. Use the downloaded JWK to verify the signature using your preferred library (for java the standard is jose4j) making sure that:

    ->> The following critical headers are set: "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path", "https://payconiq.com/iss", "https://payconiq.com/sub".

Code snippets for Java and PHP programming languages on how to verify 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 PQI. If the callback signature verification fails, contact PQI to report the issue.


The Payconiq Callback Certificates

The Payconiq certificate is hosted via a publicly available endpoint in a JSON Web Key JWK format as a JSON Web Key Set (JWKS). They should be retrieved using the following links:

Environment URL Key Id
EXT https://ext.payconiq.com/certificates rs.signature.ext.payconiq.com
PROD https://payconiq.com/certificates rs.signature.payconiq.com

Rotating the Payconiq Callback Certificates

PQI reserves the right to rotate the certificates used to validate the callback signature. As a result, PQI recommends programmatically fetching the JWKs and using the values to validate the signature. When a certificate is changed or added, a new JWK with a new Key Id will also be added. Signatures generated with the new certificate will contain an updated key id.

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. If the callback signature verification fails, contact Payconiq to report the issue.

The Callback Body

The body of the callback is JSON formatted with fields indicating the status of the payment.


Payconiq Product Workflows

The following Payconiq products make use of the Payconiq Payment Service Provider APIs.

  • Payconiq Instore – On a terminal
  • Payconiq Online – On a website checkout page

Payconiq Instore – On a Terminal

The Payconiq Instore solution – On a Terminal is suitable for Partners who facilitate payments for Submerchants with physical presence in one or more locations and want to offer the Payconiq payment method. A Payment is created with mandatory details via the Payconiq backend and a Dynamic QR code is displayed on a payment terminal for the Consumer to scan. The Consumer sees the amount, Partner name, shop name and description after scanning with a Payconiq supported app. The Consumer then confirms the payment using a Payconiq supported app. The created Payment is valid for 120 seconds (2 minutes). Once the Payment is confirmed by the Consumer, an optional callback is sent to the Partner indicating the status of the Payment.

The following process flow will be followed in order to complete the implementation.

Payconiq Online (Custom Website Checkout) Process Flow Payconiq Instore (On a Terminal) Process Flow

Step by step payment flow

  • The Partner sends a REST request to the Payconiq backend to create a Payment. (Full details provided in API specification)
  • The Payconiq backend returns the created payment with the Payment id and other relevant details to the Partner including a link to the Dynamic QR code.
  • The Partner backend facilitates the display of the Payconiq QR code towards the Submerchant.
  • The consumer scans the Dynamic QR code and then confirms the Payment with a Payconiq supported app.
  • The Payconiq backend sends a Payment callback notification to the Partner with the Payment details which includes the status via the callback URL.

Payconiq Online – Online Custom Checkout

The Payconiq Online – Online Custom Checkout solution is suitable for Partners who facilitate payments for Submerchants with an online presence and want to offer the Payconiq payment method. A Payment is created with mandatory details via the Payconiq backend and a Dynamic QR code is displayed on a website for the Consumer to scan. The Consumer sees the amount, the Partner name, the shop name and description after scanning. The Consumer then confirms the payment using a Payconiq supported app. Once the Payment is confirmed by the consumer, an optional callback is sent to the partner indicating the status of the Payment.

The following process flow will be followed in order to complete the implementation.

Payconiq Online (Custom Website Checkout) Process Flow Payconiq Online (Custom Website Checkout) Process Flow

Step by step payment flow

  • The Partner sends a REST request to the Payconiq backend to create a Payment. The parameters passed in this request are the payment amount, payment currency, payment description, callback URL and merchant data. (Full details provided in API specification)
  • The Payconiq backend returns the created payment with the Payment id and other relevant details to the Partner including a link to the Dynamic QR code.
  • The Partner backend facilitates the display of the Payconiq QR code towards the Submerchant.
  • The consumer scans the Dynamic QR code and then confirms the Payment with a Payconiq supported app.
  • The Payconiq backend sends a Payment callback notification to the Partner with the Payment details which includes the status via the callback URL.


API Definitions

The following section defines all the Payment Service Provider API endpoints and definitions which will be exposed to Partners in order to integrate with the Payconiq backed.

Create Payment API

This endpoint is used to create a Payment. A Payment is valid for 2 minutes and if not confirmed or cancelled, the Payment expires, and a new Payment id has to be created.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/subMerchant

PROD URL Definition: https://api.payconiq.com/v3/payments/subMerchant


Create Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.






Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments/subMerchant
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
         "amount" : "1",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200",
         "country": "NLD",
         "paymentChannel": "ONLINE",
         "posId": "POS12345",
         "subMerchant": {
           "subMerchantId": "0001MERCH0001",
           "name": "Merchant ABC",
           "naceCode": "4765",
           "mcc": "5190"
          }
      }'


Create Payment Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
callbackUrl
[URI, optional]
A url to which the Merchant or Partner will be notified of a payment. Must be Https for production.
currency
[String, Optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
Value: EUR
description
[String, optional]
Maximum Length: 140 chars
Custom description of the Payment. This will be shown to the consumer when making Payments and will be present on the bank statement of the Partner and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the in the calling party's system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
country
[String::enum, required]
Allowed values: NLD, BEL, LUX
The ISO Alpha-3 country code where the payment takes place. See https://www.iso.org/obp/ui/#search/code/
paymentChannel
[String::enum, required]
Allowed values: INSTORE, ONLINE
The channel of payment.
posId
[String, conditional]
Maximum Length: 36 chars
The external identifier for the point of sale where the payment is taking place. Required for INSTORE payment.
subMerchant
[Object, required]
This is the underlying merchant who will be the ultimate beneficiary of the payment.
subMerchant.subMerchantId
[String, required]
Minimum Length: 1 char
Maximum Length: 36 chars
External identifier for the merchant.
subMerchant.name
[String, required]
Minimum Length: 1 char
Maximum Length: 22 chars
The name of the location where the payment is taking place. This will be shown to the consumer in the app.
subMerchant.naceCode
[String, optional]
The NACE code of the merchant.
subMerchant.mcc
[String, optional]
Minimum Length: 4 chars
Maximum Length: 4 chars
The merchant category code of the merchant.

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5aa9a9700000000000000000",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 112,
    "currency": "EUR",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdb1685b93d1c000bde96f2"
        },
        "cancel": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2"
        }
    }
}


Create Payment Response

The following parameters are included in the header and body of the create payment response.


Response Header

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


Response Body

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payment id.
status
[String::enum, required]
Allowed values: PENDING
The status of the Payment.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payment.
expiresAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payment expires.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remmittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payment in the merchant’s system.
amount
[Integer, required]
Payment amount in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
creditor
[Object, required]
The merchant account object set to receive the Payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.










HTTP/1.1 400 Bad Request
{
    "traceId": "b2586833395d4750",
    "spanId": "c235e54376fab4b9",
    "code": "FIELD_IS_REQUIRED",
    "message": "Field 'amount' is mandatory"
}

Create Payments HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
400
[Integer]
BODY_MISSING: A JSON body needs to be provided.
FIELD_IS_REQUIRED: A mandatory field is missing from the JSON request.
FIELD_IS_INVALID: A field provided is not valid. Eg: The length of a field exceeds what is required.
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
MERCHANT_PROFILE_NOT_FOUND: The merchant profile for creating a payment does not exist.
422
[Integer]
UNABLE_TO_PAY_CREDITOR: This could be returned for multiple reasons in case something goes wrong.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payment service.
503
[Integer]
Service Unavailable


The Payconiq QR Generation Service

Payconiq provides a QR generation service which is used to produce a Payconiq QR code. With a set of parameters, a Payconiq Dynamic QR code can be downloaded and displayed. Below are a list of products and how the Payconiq QR code is created.

Displaying the Payconiq Dynamic QR Code

The Payconiq Dynamic QR code can be downloaded and displayed or rendered in a web view container for quick scanning using a parameter with name qrcode returned after a Payment is created. This parameter is a url which 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.

The following parameters can be appended to the QR url in order to render it differently.

Attribute Description
f
[String :: Enum]
Allowed Values: SVG, PNG
Image format
s
[String :: Enum]
Allowed Values: S, M, L, XL
Image size of the QR code to generate.
Small (S) = 180x180
Medium (M) = 250x250
Large (L) = 400x400
Extra Large (XL) = 800x800
The sizes 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


The Payconiq Callback

Payconiq calls the merchant’s callbackUrl endpoint to send the status of a payment. This is only informational towards the merchant or partner. There is no impact on a payment if it is not processed successfully by the merchant or partner.

The merchant backend must verify that the notification message originated from Payconiq and was not altered or corrupted during transmission by validating the signature.

Type: REST

HTTP Verb: POST

EXT URL Definition: {callbackUrl}

PROD URL Definition: {callbackUrl}


Callback Request Header

The following parameters are included in the header of the callback request.




signature: eyJ0eXAiOiJKT1NFK0pTT04iLCJraWQiOiJ5ZXNPbmUiLCJhbGciOiJSUzI1NiIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCI6IjIwMTktMDEtMTRUMTE6MTE6MTFaIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vanRpIjoiR2l2ZU1lIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vcGF0aCI6Ii90aGUvcm9hZC9sZXNzL3RyYXZlbGVkIiwiaHR0cHM6Ly9wYXljb25pcS5jb20vaXNzIjoiUGF5Y29uaXEiLCJjcml0IjpbImh0dHBzOi8vcGF5Y29uaXEuY29tL2lhdCIsImh0dHBzOi8vcGF5Y29uaXEuY29tL2p0aSIsImh0dHBzOi8vcGF5Y29uaXEuY29tL3BhdGgiLCJodHRwczovL3BheWNvbmlxLmNvbS9pc3MiXX0..LoBPG9T00c-0urv5FXrTWmumUJBTpTaqG5F0HciYHgi0Ck-bZrFxX8MLEgKbdv5YUMKKDnbLcFS0M4lNiGa17Qo8OOH4mCAjvuVEyoutHObd_TrZ4oUM0CX3uRNd88shemup9YPEMtRjmPZATXzStTBdQeRpq_f89bAqy2nCOxg_2BgqSnvC_R4JMA7I5SaRndvzbn80oeVHUEMkpmRFNnhRtVujeEUnfn3hBR_YIHh3vJKWArIYOV9eMkpDFb6nC_GoZoNGfPFunBUtOXU1y3gCDi6GOsa4eaDygNsBk-ZNj2v8cMRPBnHdw2oOaAjEs6K63An0bbkdKG7UzVojAw


content-type: application/json



user-agent: Payconiq Payments/v3

Attribute Comment/ Format
signature
[String, required]
This represents a Payconiq digitally signed content using JSON data structures and base64url encoding. The signature is made up of JSON Web Signature (JWS) and a JSON Object Signing and Encryption (JOSE) header.
content-type
[String, required]
application/json
The Content-Type entity header is used to indicate the media type of the resource.
user-agent
[String, required]
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.






{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2018-09-20T10:53:49.875Z",
    "expireAt": "2018-09-20T10:55:49.875Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV"
}


Callback Request Body

The following parameters are included in the body of the callback request.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payment id.
amount
[Integer, required]
Minimum: 1
Maximum: 999999
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
currency
[String, optional]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
reference
[String, optional]
Merchant’s payment reference used to reference the Payment in the merchant’s system.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payment expires.
status
[String::enum, required]

Allowed values: PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, EXPIRED.
The status of the Payment.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.


Get Payment Details

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

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

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Get Payment Details Header

The following parameters are included in the header of the request.

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/payments/5b976d11dd172a0007c4429d
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'



Get Payment Details Request Path

The following parameters are included in the path of a get payment details request.

Attribute Description
paymentId
[String, required]
The unique Payconiq identifier of a payment as provided by the create payment service.


Get Payment Details Response Header

The following parameters are included in the header of the get payment details response.

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








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "5bdaf066b93d1c000bde9683",
    "createdAt": "2018-11-01T12:24:06.004Z",
    "expireAt": "2018-11-01T12:26:06.004Z",
    "currency": "EUR",
    "status": "SUCCEEDED",
    "creditor": {
        "profileId": "5b71369f5832fd22658e0ef4",
        "merchantId": "5b71369f5832fd09188e0915",
        "name": "Merchant Name",
        "iban": "NL47FRBK0293409698",
        "callbackUrl": "https://www.testcallback.com/payconiq/payment"
    },
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "amount": 10,
    "transferAmount": 10,
    "tippingAmount": 0,
    "totalAmount": 10,
    "description": "Otto's Payment Test",
    "bulkId": "centraal station pos-2",
    "_links": {
        "self": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
        },
        "deeplink": {
            "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
        },
        "qrcode": {
            "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
        },
        "refund": {
            "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
        }
    }
}



Get Payment Details Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
paymentId
[String, required]
Fixed length: 24 chars
The unique Payment id.
createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payment.
expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payment expires.
currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payment.
creditor
[JSON Object, required]
The merchant account object set to receive the Payment from a consumer.
creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
creditor.merchantId
[String, required]
The unique identifier of a merchant.
creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
debtor.name
[String, optional]
The name of the consumer.
debtor.iban
[String, optional]
The masked IBAN of the consumer.
amount
[Integer, required]
Payment amount in Euro cents.
transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
message
[String, optional]
Custom message from the consumer.
reference
[String, optional]
Merchant’s payment reference used to reference the Payment in the merchant’s system.
bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
_links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
_links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
_links.self.href
[String :: URI, optional]
URL String.
_links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
_links.deeplink.href
[String :: URI, optional]
URL String.
_links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
_links.qrcode.href
[String :: URI, optional]
URL String.
_links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
_links.cancel.href
[String :: URI, optional]
URL String.
_links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
_links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 404 Not Found
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}


Get Payment Details HTTP Status and Error Codes

Below are the status codes and descriptions returned as part of the API responses.

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payment service.
503
[Integer]
Service Unavailable


Get Payments List

This endpoint is use to retrieve a list of a Payments. The page and size parameters are used to specify how many records to return as well as filter the results for the total number of records returned per page. By default the latest 50 payments are returned per request and are sorted by creation date in descending order.

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/search?page={p}&size={s}

PROD URL Definition: https://api.payconiq.com/v3/payments/search?page={p}&size={s}


Get Payments List Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.













Example Request:
curl -X POST
  'https://api.ext.payconiq.com/v3/payments/search?page=10&size=10'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{
        "from":"2018-08-01T00:10:10.000Z",
        "to":"2018-08-31T00:10:10.999Z",
        "paymentStatuses":["SUCCEEDED"],
        "reference":"1234568"
  }'


Get Payments List Request Path

Attribute Comment/ Format
page
[Integer, optional]
Zero based page index in the list request.
NB: The page defaults to 0 if not present in the request path.
size
[Integer, optional]
The size of the page to be returned in the list.
NB: The size defaults to 50 if not present in the request path.


Get Payments List Request Body

Attribute Description
from
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The start date and time to filter the search results.
Default: Current date and time minus one day. (Now - 1 day)
to
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The end date and time to filter the search results..
Default: Current date and time. (Now)
paymentStatuses
[Array::String, Optional]
An array of payment statuses to filter the search results on.
reference
[String, optional]
Maximum Length: 35 chars
External payment reference used to reference the Payment in the calling party's system.


Get Payment List Response Header

The following parameters are included in the header of the get payment list response.

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











HTTP/1.1 200 OK
{
    "size": 2,
    "totalPages": 7,
    "totalElements": 13,
    "number": 0,
    "details": [
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        },
        {
            "paymentId": "5bdaf066b93d1c000bde9683",
            "createdAt": "2018-11-01T12:24:06.004Z",
            "expireAt": "2018-11-01T12:26:06.004Z",
            "currency": "EUR",
            "status": "SUCCEEDED",
            "creditor": {
                "profileId": "5b71369f5832fd22658e0ef4",
                "merchantId": "5b71369f5832fd09188e0915",
                "name": "Merchant Name",
                "iban": "NL47FRBK0293409698",
                "callbackUrl": "https://www.testcallback.com/payconiq/payment"
            },
            "debtor": {
                "name": "John",
                "iban": "*************12636"
            },
            "amount": 10,
            "transferAmount": 10,
            "tippingAmount": 0,
            "totalAmount": 10,
            "description": "Otto's Payment Test",
            "bulkId": "centraal station pos-2",
            "_links": {
                "self": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683"
                },
                "deeplink": {
                    "href": "https://payconiq.com/pay/2/5bdaf066b93d1c000bde9683"
                },
                "qrcode": {
                    "href": "https://portal.ext.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5bdaf066b93d1c000bde9683"
                },
                "refund": {
                    "href": "https://api.ext.payconiq.com/v3/payments/5bdaf066b93d1c000bde9683/debtor/refundIban"
                }
            }
        }
    ]
}

Get Payments list Response Body

The following parameters are included in the body of the get payment details response.

Attribute Description
size
[Integer, required]
The total size of elements returned in the current page.
totalPages
[Integer, required]
Total number of pages that contain the list of results.
totalElements
[Integer, required]
Total number of elements in the list requested.
number
[Integer, required]
The current page number.
details
[JSON Object, required]
An array of payment details returned for the search criteria.
details.paymentId
[String, required]
Fixed length: 24 chars
The unique Payment id.
details.createdAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The creation date and time of the Payment.
details.expireAt
[String, required]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ
The date and time when a Payment expires.
details.currency
[String, required]
Payment currency code in ISO 4217 format. Only Euros supported at the moment.
details.status
[String::enum, required]
Allowed values: PENDING, IDENTIFIED, CANCELLED, AUTHORIZED, AUTHORIZATION_FAILED, EXPIRED, FAILED, SUCCEEDED
The status of the Payment.
details.creditor
[JSON Object, required]
The merchant account object set to receive the Payment from a consumer.
details.creditor.profileId
[String, required]
The unique payment product identifier of the merchant.
details.creditor.merchantId
[String, required]
The unique identifier of a merchant.
details.creditor.name
[String, required]
The merchant’s company name that will be shown to the consumer.
details.creditor.iban
[String, required]
The bank account of the merchant where payments will be sent to.
details.creditor.callbackUrl
[String, optional]
A URL to which the Merchant or Partner will be notified of a payment.
Must be https for production.
details.debtor
[JSON Object, required]
The consumer account object that makes payments to the merchant
details.debtor.name
[String, optional]
The name of the consumer.
details.debtor.iban
[String, optional]
The masked IBAN of the consumer.
details.amount
[Integer, required]
Payment amount in Euro cents.
details.transferAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer will be charged in Euro cents
details.tippingAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount added as a tip by the consumer in Euro cents.
details.totalAmount
[Integer, required]
Minimum: 1
Maximum: 999999
The amount the consumer pays in total in Euro cents.
details.description
[String, optional]
Custom description of the payment. This will be shown to the consumer when making payments and will be present on the bank statement of the merchant and consumer for reconciliation purposes. Only the first 35 characters are used for the remittance information.
details.message
[String, optional]
Custom message from the consumer.
details.reference
[String, optional]
Merchant’s payment reference used to reference the Payment in the merchant’s system.
details.bulkId
[String, optional]
Maximum Length: 35 chars
A field set by the calling party used to reference a bulk batch payment. If not set, bulking is done based on the IBAN.
details._links
[Object, optional]
Links object which contain urls to be used by merchants to load the QR codes, perform App2App linking, cancel a payment and get the payment details.
details._links.self
[Object, optional]
Hypermedia GET URL used to fetch payment details
details._links.self.href
[String :: URI, optional]
URL String.
details._links.deeplink
[Object, optional]
Hypermedia GET URL used to perform App2App linking
details._links.deeplink.href
[String :: URI, optional]
URL String.
details._links.qrcode
[Object, optional]
Hypermedia GET URL used to fetch QR code for display and scanning purposes (PNG/SVG)
details._links.qrcode.href
[String :: URI, optional]
URL String.
details._links.cancel
[Object, optional]
Hypermedia DELETE URL used to cancel a payment.
details._links.cancel.href
[String :: URI, optional]
URL String.
details._links.refund
[Object, optional]
Hypermedia GET Url used to fetch refund information for a payment.
details._links.refund.href
[String :: URI, optional]
URL String.










HTTP/1.1 401 Unauthorized
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "UNAUTHORIZED",
    "message": "Payment not found '5ba35a3d0989e3000758b9c2'"
}




Get Payments List HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payment service.
503
[Integer]
Service Unavailable


Cancel Payment

This endpoint is used to cancel a created Payment. A payment can only be cancelled only if the status is either PENDING or IDENTIFIED. Once cancelled, the status of the payment is set to CANCELLED.

Type: REST

HTTP Verb: DELETE

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}


Cancel Payment Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx




Example Request:

curl -X DELETE
  https://api.ext.payconiq.com/v3/payments/5ba35a3d0989e3000758b9c1
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Cancel Payment Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a Payment as provided by the create payment service.


Cancel Payment Request Body

There is no body in cancel payment request.


Cancel Payment Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the cancel payment response.

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


Cancel Payment Response Body

There is no body returned in the body of a cancel payment response.







HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "8abc6e29041adb94",
    "spanId": "6ba82033652b5b41",
    "code": "PAYMENT_NOT_PENDING",
    "message": "Payment '5ba35d610989e3000758b9cc' is not allowed to be cancelled"
}



Cancel Payment HTTP Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
CALLER_NOT_ALLOWED_TO_CANCEL: The merchant is not allowed to cancel this payment.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
PAYMENT_NOT_PENDING: Payment is not in a pending or identify state.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payment service.
503
[Integer]
Service Unavailable


Get Refund IBAN

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. This endpoint is used to retrieve the IBAN of the consumer for the purpose of performing refunds to the consumer. This endpoint does not handle the actual transfer of money. The merchant or partner is responsible for actual transfer of funds to the consumer. Getting the IBAN for refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{paymentId}/debtor/refundIban

PROD URL Definition: https://api.payconiq.com/v3/payments/{paymentId}/debtor/refundIban








curl -X GET
 https://api.ext.payconiq.com/v3/payments/5bdb1685b93d1c000bde96f2/debtor/refundIban
 -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'



Get Refund IBAN Request Header

Attribute Comment/ Format
Authorization
[String, required]
Authorization field which contains the API Key.
Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-type
[String, required]
application/json
Content type of the data in the request body.

Get Refund IBAN Request Path

Attribute Comment/ Format
paymentId
[Integer, required]
Fixed length: 24 chars
The unique identifier of a payment as provided by the create payment service.


Get Refund IBAN Payment Response Header

The following parameters are included in the header of the get refund iBAN response.

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


Get Refund IBAN Response Body

The following parameters are included in the body of the get refund IBAN response.



HTTP/1.1 200 OK
{
    "iban": "NL77ABNA1111111111"
}

Attribute Description
iban
[String, required]
The IBAN of the consumer








HTTP/1.1 422 Unprocessable Entity
{
    "traceId": "d7152b6b08caa620",
    "spanId": "556d68164b8e8ef6",
    "code": "REFUND_NOT_AVAILABLE",
    "message": "Refund not available for payment '5ba35a3d0989e3000758b9c2'"
}


Get Refund IBAN Status and Error Codes

Status Code Error Codes
401
[Integer]
UNAUTHORIZED: The user not have an API Key or API Key is incorrect.
403
[Integer]
ACCESS_DENIED: The API key could not be verified or the API key does not contain the required authority to access the resource requested.
404
[Integer]
PAYMENT_NOT_FOUND: Payment could not be found for the corresponding payment id.
422
[Integer]
REFUND_NOT_ALLOWED: The payment is a consumer payment(peer2peer or payment request).
REFUND_NOT_AVAILABLE: The details of the consumer is not available yet.
429
[Integer]
Too Many Requests
500
[Integer]
TECHNICAL_ERROR: Technical error in the Payment service.


FAQs

Additional information

How can I confirm my test payment?

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

Upcoming Certificate Change

The following certificate comes into effect on 10th April 2019.

Certificate Environment Valid From Expiry Date
(New) Prod Certificate
signature.payconiq.com:443
10th April 2019 11th March 2021

Current Certificates Change

Certificate Environment Expiry Date
(Old) 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 [email protected]

Our privacy statement and terms & conditions are below

Privacy statement

Terms & conditions