curl

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.

Why Payconiq

Your customers do everything with their phone: look up prices, request routes to the store, compare articles. But paying with a telephone still sounds like music for the future. Just like when contactless payment was introduced a few years ago. The future is reality faster than you think. Thanks to Payconiq you can now let your customers experience the convenience of mobile payment. It is simple, fast and secure. Pay instore, online and your invoice with just your mobile phone.

This video provides more information about What Payconiq is.

W3Schools

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

Payconiq Product Overview

Payconiq offers the following products in the world of mobile payment.

Payconiq Instore

Payconiq can be directly integrated into your cash register system or pin terminal. You show a QR code in your store on a receipt, sticker (at the cash register), customer-facing screen or pin terminal. Your customer will then scan the QR code with the app on his phone. Just confirm and get paid.

Payconiq Online

Payconiq can be directly integrated into your webshop. To complete an online order, a unique QR code appears on the screen. Your customer scans it with the Payconiq app and pays without having to leave your page. On mobile, it will create an app2app payment via a universal deep link.

Payconiq Invoice

Invoices paid via mobile phone are paid thrice as fast compared to normal payments and without the hassle of typing over the invoice data. Payconiq can be Payconiq can be directly integrated with your invoices and allows your customers to pay it with their mobile phone.

Voucher payment (Belgium only)

Accepting payments with vouchers has never been easier! We combine a Payconiq payment and a payment with vouchers in 1 single scan of the Payconiq QR Code. (meal vouchers only for now).
Accept meal vouchers of Edenred, Monizze and Pluxee | Payconiq by Bancontact


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 or JWS key which will be used when interacting with the Payconiq endpoints. This will be shared via mail.

To accept voucher payments, the merchant needs an active contract with one or multiple voucher providers (Pluxee, Edenred and/or Monizze) and an activation in the Payconiq back-end. Contact the BPC team to activate voucher payment on the merchant profile: Contact us | Payconiq by Bancontact


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.

You can also email us at [email protected] to get external account access.

In case you have an external account and want to activate voucher payments, send the following information to [email protected]:

  • Merchant ID
  • Product or PPID on which you want to activate voucher payments

In case you don’t have an external account yet, please provide the following information to [email protected]:

  • Company Name
  • Contact First Name
  • Contact Second Name
  • Telephone Number
  • Email
  • Address
  • Language
  • Callback URL
  • Type of Integration: Instore on display, Custom Online, app2app, POS etc. [Please mention the Payconiq product for which you need a test merchant account here. Payconiq products available at: Payconiq-Developer Portal
  • Activate voucher payments: Yes / No

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, the External build of the Payconiq by Bancontact app can be downloaded and setup to perform test transactions and to validate the integration end to end. This build is linked to the PQI EXT environment.

Please note that the PROD version of the Payconiq by Bancontact app can be downloaded via the Apple App Store and via the Google Play Store.

Payconiq By Bancontact App

W3Schools

The External build of the app can be downloaded via the following links: Android & iOS

Please note that the infrastructure supporting the External build is switched off each day from 21h30(CET) to 6h00 (CET) and during the weekends from Friday 21h30 (CET) until Monday 6h00 (CET).

In case you’re encountering issues during the app installation and/or activation, please send us a description of the issue encountered, the version of the app you used and your account details (phone number & email address) to [email protected].

Installation steps

  • Remove all existing build(s) of the Payconiq by Bancontact app from your device.
  • Download the above-mentioned apps from App Center and install them on your device.
  • Once installed, open the Payconiq by Bancontact app and start the onboarding process.
    • with iOS, you can get a pop-up saying that ITP isn't a trusted company, To change this, go in device Settings > General > VPN & Device Management > You'll find ITP in the "Enterprise apps". Flag it as Trusted.

Onboarding procedure

  1. Select: Continue without itsme
  2. Email address:
    1. Enter your email address
    2. Enter the code 123456
  3. Enter your first name and last name (only applicable if you are a new user)
  4. Phone number
    1. Enter your phone number (must be an EU phone number)
    2. Enter the code 123456

After this, the app will create the user wallet. Once this step is finished, the onboarding flow continues:

  1. Set a PIN code. It will be used to validate payments and enter some protected sections in the app.
  2. Either activate Biometric or skip the step.
  3. Add a Bancontact card (see list here below):
    1. Select the bank of the card
    2. Input the bank card number with the expiry date
    3. Switch the toggle “I have read and accepted the terms and conditions of my bank.”
  4. Once the card is added, link your bank account:
    1. Select the bank Payconiq Dynamic Bank V2 in the bank list that will be displayed
    2. Click on the button “Confirm” in the web page that will open
    3. You will be redirected to the Payconiq by Bancontact app
  5. Give access to the camera.

To test meal voucher payment:

  1. Select Payment methods in the menu (top left of the home screen)
  2. Enter you PIN code
  3. Select “Your meal vouchers”
  4. Select “Payconiq Voucher Provider”
  5. Click on “Link account to Payconiq Voucher Provider” The Payconiq Voucher Provider is a generic card with a positive balance of € 1.000.

NOTE: This balance will not change even after making a payment.

Re-onboarding

If you want to onboard again with a new email or phone combination, don't forget to first delete your existing user account via the app.

  1. Open the menu
  2. Payment methods
  3. Tap on the linked bank account
  4. Tap on [ Unlink bank account ], and confirm on the next screen by tapping [ Unlink bank account ]
  5. Next go to the app Settings (via app Menu)
  6. Tap on Delete my account
  7. Confirm the deletion
  8. The app will reset

Test cards

Issuer Card Number Expiry Date
Belfius 6703 0510 0219 0500 6 Dec-26
Belfius 6703 0510 0219 0400 9 Dec-26
Belfius 6703 0510 0220 7700 3 Dec-26
Belfius 6703 0510 0219 1500 5 Dec-26
Bank van Breda 6703 6459 1548 1200 7 Feb-27
Bank van Breda 6703 6459 1548 1400 3 Feb-27
CPH 6703 1250 3048 3700 1 Jul-27
CPH 6703 1250 3048 3800 9 Jul-27
Deutsche Bank 6703 6118 2742 2001 8 Feb-27
Deutsche Bank 6703 6108 2717 6001 7 Oct-25
Deutsche Bank 6703 6108 2727 5002 5 Jan-26
VDK 6703 8900 1815 4201 6 Dec-26
VDK 6703 8900 1815 4301 4 Dec-26
VDK 6703 8900 1815 4401 2 Dec-26
VDK 6703 8900 1484 2901 8 Dec-26
BNPPF 4871 0406 2038 651 0 Jun-26

The Payconiq Brand Guide

Online Payments

You can find Payconiq's Branding Guidelines for Online Payments here.

W3SchoolsFor Belgium: the guidelines for Payconiq by Bancontact can be found here.

W3Schools


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 Magenta & White Payconiq QR Code QR Code


Sample Black & White 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

Payconiq QR Code Colours

  • The Payconiq QR code comes in two flavours. Magenta and white or Black and white.


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.


Payouts

For all Payconiq payments that are made to our merchant, Payconiq ensures that that funds are credited to your bank account by means of a credit transfer. The credit transfer for payments to your account can be received in two ways.

  • Bulk Payouts - All payments to your merchant for a day are credited as one single line item on your bank account.

  • Individual Payouts - All payments to your merchant are credited as multiple line items on your bank account.

  • Voucher payment - All voucher payments to your merchant are directly credited by the voucher providers (Edenred, Pluxee or Monizze).

By default your merchant is configured to have Individual Payouts. If you would like to receive Bulk Payouts for payments to your merchant, please reach out to your local Payconiq Organisation.

Bulk Payouts and Remittance

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 and Merchant Id. With this method all payments are aggregated based on your bank account number (IBAN) and Merchant Id. This applies when no bulk identifier has been provided.

Bulking Notes

  • Successful Transactions are bulked over the course of a day from 00:01:00 to 00:00:00 (CET) next day.
  • 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 payout will be done from Payconiq end but it depends on the merchant's bank if they do a payout towards merchant's account on Saturday and Sunday or not.
  • Your account will be credited either two to three days after the transactions are bulked.
  • The remittance information contains the date the payments were processed YYYYMMDD (8 char) + Payout end2end ID (24 char) + bulk ID (35 char) + PQ (2 char) + BulkRecon (9 char) + Merchant ID (24 char).
  • Each item in the remittance information is separated by hyphens: “-”
  • The bulk end to end identifier will also be in the End-to-end reference field of your bank statement.
  • Reconciliation can be done using reconciliation APIs.

Individual Payouts and Remittance

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

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 is 1 exemption to this:

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 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 String: Space
[Max Length: 24]
Delimiter Field separator String: Space
[Max Length: 1]
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                          ”


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


Payout Reconciliation

To help reconcile and match the payouts you receive on your bank account with the batches of payments and refunds they relate to, Payconiq offers Reconcliation via APIs. The Reconciliation APIs are mainly for bulked payments however can also be used for Individual payouts.

Reconciliation Endpoints

Payconiq offers three (3) endpoints to help you reconcile your payouts.

  • Get List of Payouts API – API to fetch a list of payouts that were made to your bank account by date.
  • Get List of Reconciliation Payments API – API to fetch list of SUCCEEDED payments for reconciliation purposes by payout Id or start and end date.
  • Get List of Reconciliation Refunds API – API to fetch list of SUCCEEDED refunds for reconciliation purposes by payout Id or start and end date.

All APIs will be authenticated using signatures.

Reconciliation Data Availability

The following notes apply on the availability of Reconciliation data via APIs

  • All Reconciliation information will be available from 9:00:00 CET every day for the previous day’s payments and refunds.
  • Reconciliation information is available for both EXT and PROD environments.
  • If you have troubles finding your reconciliation data, please contact [email protected].

Payment API Version 3 (V3)

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 asynchronous HTTPS confirm URL (callback URL) via which Payconiq will 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. The callbacks are issued via HTTP POST requests and encrypted using TLS 1.2.

You may choose to receive the payment callbacks either via one-way or two-way(requires enablement on server side) TLS encryption.

TLS One-way TLS Encryption Support

In the TLS One-way encyrption, all callback requests will be encrypted where the Payconiq backend verifies the certificate of the merchant or partner anytime Payconiq sends a callback request. There is not requirement to exchange certificates beforehand and the callbacks should work out of the boc. Please contact [email protected] if you are having any issues.

TLS Two-way TLS Encryption Support (TLS-Mutual Authentication)

In the two-way TLS encryption support, the merchant or parter verifies the details of Payconiq before processing the details of the callback. This allows Payconiq and the merchant or partner to communicate with privacy and data integrity with an additional JWS security. Please reach out to [email protected] regarding necessary certificate details that need to be shared if this is required.

TLS-MA Certificate Rotation & Pinning

Payconiq reserves the right to rotate its certificate without informing the merchant or partner since each certificate has a validity period or may be compromised. In case the merchant or partner pins certificates, it must only pin the Payconiq certificate on the CN name. This will make rotation of the certificate seamless.


Callback Retry Policy

Payconiq guarantees sending a callback to the backend of a merchant or partner for 24 hours. In the event the merchant or parter does not respond correctly (Http 200 - OK) to the initial callback, Payconiq retries delivering the callback. After 24 hours, Payconiq stops trying to resend the callback.

Payconiq retries to send a callback for the following scenarios:

  • Not responding in 15 seconds to the callback
  • Responding with a Http 429 - Too Many Requests
  • Responding with a Http 500 - Internal Server Error
  • Responding with a Http 503 - Service Unavailable
  • Responding with a Http 504 - Gateway Timeout
  • Responding with a Http 509 - Bandwidth Limit Exceeded

Notes

  • The status of a payment does not change.
  • The content of callback does not change. The headers, body and target url remains as just as the first attempt.
  • Responding with a Http 200 means that Payconiq stops sending the callback.
  • After 24 hours Payconiq stops retrying the callback.


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:

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


content-type: application/json



user-agent: Payconiq Payments/v3

json

{
    "paymentId": "5ba37c3d0989e3000758b9d8",
    "transferAmount": 122,
    "tippingAmount": 0,
    "amount": 122,
    "totalAmount": 122,
    "description": "Sample description",
    "createdAt": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]
}
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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013

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
  • EXPIRED
  • CANCELLED
  • AUTHORIZATION_FAILED

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

  • AUTHORIZED
  • PENDING
  • IDENTIFIED


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" : "{PaymentProfileId}",

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

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.

Payconiq will follow and below guidelines with regards to hosting and rotating JWKs.

Rotating the JWK Payconiq will append a new JWK with a new kid to the existing JWKs for the first 24 hours. After the 24-hour period, the old JWK will be removed from the host site location.

Merchants and Partners should cache the JWKs for a period of 12 hours and use it to verify any signature sent by Payconiq. After 12 hours, the JWKs must be re-cached automatically. If there any changes made to the JWKs, the changes should come into effect.

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

Pay mobile by scanning the QR code on a customer facing screen and terminal.

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.


Instore Process Flow With Void Enabled

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.
  • The customer is debited, and the payment is in a state that is pending an acknowledgment (PENDING_MERCHANT_ACKNOWLEDGEMENT) from the merchant/terminal.
  • Payconiq sends a callback to the merchant to notify them about the status of the payment. The merchant can also poll Payconiq for the status of the payment.
  • Towards the consumer we will inform them to check the terminal for the final status of the payment.
  • The merchant terminal sends a positive acknowledgement for the payment to indicate that the terminal processed the payment successfully.
  • Payconiq marks the payment as SUCCEEDED and initiates a payout to the merchant.
  • 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.
  • Voucher activation (Optional) - To accept (meal) voucher payments the merchant requires an active contract with one or multiple meal voucher providers (Pluxee, Edenred and/or Monizze) and an activation on your profile (Belgium only). Contact the BPC team to activate voucher payment on the merchant profile: Contact us | Payconiq by Bancontact .


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" : "999999",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200",
         "voucherEligibility": [
             {
               "voucherSchemes": [
                 "BEL_MEAL_VOUCHER"
               ],
               "amount": 1013
             }
          ]
      }'

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.
voucherEligibility
[Object, optional]
List of Value-Added Services (vouchers) eligible amounts within the payment. Defines an amount that could be paid with proper voucher schemes.
voucherEligibility.voucherSchemes
[String, required]
List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherEligibility.amount
[Integer, required]
Amount in cents eligible for payment with voucher. EUR 10.13 will be 1013 

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5bdb1685b93d1c000bde96f2",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 999999,
    "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, small (S) size and magenta in color.

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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme. This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier] currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013 










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


Void Payment


This endpoint enable payment terminals stay in the lead of payments. With the ability to void a payment, the payment terminal informs Payconiq about the end result of the payment before Payconiq pays out the payment to the merchant. If something goes wrong while completing the payment, the terminal has a window of time to let Payconiq know so as to void the payment and return funds to the consumer. This ensures that the terminal remains in the lead of payments. In exceptional cases where no message is sent to the Payconiq concerning the payment, Payconiq voids the payment and returns the funds to the consumer.

There could be three scenarios with the void payments.

Scenario One: Happy Flow

  • Merchant creates a payment via Payconiq and displays the Payconiq QR code.

  • Consumer scans the QR code to retrieve payment information.

  • Consumer signs (enter pin/fingerprint/FaceId) the payment successfully.

  • The customer is debited, and the payment is in a state that is pending an acknowledgment (PENDING_MERCHANT_ACKNOWLEDGEMENT) from the merchant/terminal.

  • Payconiq sends a callback to the merchant to notify them about the status of the payment. The merchant can also poll Payconiq for the status of the payment.

  • Towards the consumer we will inform them to check the terminal for the final status of the payment.

  • The merchant terminal sends a positive acknowledgement for the payment to indicate that the terminal processed the payment successfully.

  • Payconiq marks the payment as SUCCEEDED and initiates a payout to the merchant.

  • Payconiq updates the consumer about the status of the payment.


Type: REST

HTTP Verb: POST

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

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


Void 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/{id}/acknowledge'
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d
  '{  
      "currency": "EUR",
      "amount": 0,
      "reference": "string"
  }'

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

Void Payments Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999		 Payment amount in Euro cents.
currency
[String, Optional]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
Value: EUR
reference
[String, optional]
Maximum Length: 35 chars		 External payment reference used to reference the Payconiq payment in the calling party's system.

Void Payment Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the void 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


Void Payment Response Body

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









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

Void Payments 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.
404
[Integer]		 PAYMENT_NOT_FOUND No payment could be found for the supplied identifier
422
[Integer]		 PAYMENT_VOIDED Payment is already voided
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable



Scenario Two: Unhappy Flow - Merchant Void

  • Merchant creates a payment via Payconiq and displays the Payconiq QR code.

  • Merchant creates a payment via Payconiq and displays the Payconiq QR code.

  • Consumer scans the QR code to retrieve payment information.

  • Consumer signs (enter pin/fingerprint/FaceId) the payment successfully.

  • The customer is debited, and the payment is in a state that is pending an acknowledgment (PENDING_MERCHANT_ACKNOWLEDGEMENT) from the merchant/terminal.

  • Payconiq sends a callback to the merchant to notify them about the status of the payment. The merchant can also poll Payconiq for the status of the payment.

  • Towards the consumer we will inform them to check the terminal for the final status of the payment.

  • The merchant terminal cancels the payment because something went wrong while processing the payment on the terminal.

  • Payconiq marks the payment as VOIDED and initiates a payout to the consumer.

  • Payconiq updates the consumer about the status of the payment.


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


Scenario Three: Unhappy Flow - Void Timeout

  • Consumer scans the QR code to retrieve payment information.

  • Consumer signs (enter pin/fingerprint/FaceId) the payment successfully.

  • The customer is debited, and the payment is in a state that is pending an acknowledgment (PENDING_MERCHANT_ACKNOWLEDGEMENT) from the merchant/terminal.

  • Payconiq sends a callback to the merchant to notify them about the status of the payment. The merchant can also poll Payconiq for the status of the payment.

  • Towards the consumer we will inform them to check the terminal for the final status of the payment.

  • The merchant terminal does not send a positive acknowledgement/cancel the payment in the X hours timeout.

  • Payconiq marks the payment as VOIDED and initiates a payout to the consumer.

  • Payconiq updates the consumer about the status of the payment.


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. 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 a refund only applies when the payment is SUCCEEDED and the consumer is still an active Payconiq user.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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) - Static QR Sticker

Pay mobile by scanning the QR code on a sticker. The sticker is integrated with the register.

Process Flow

Involved Parties:

  • Payconiq App – Payconiq consumer application.
  • Merchant Frontend – Point of Sale.
  • 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

  • The Merchant displays the Payconiq QR sticker in a location close to the point of sale.

  • The Merchant creates a Payment by sending a REST request to the Payconiq backend. The request contains the specific POS identifier for which the payment is created.

  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend.

  • Payconiq app scans the QR sticker to start the payment for the amount to be paid.
  • A request for payment details is sent to the Payconiq backend for the payment. The POS ID on the QR is matched with POS ID at the Payconiq backend to fetch the details.
  • Payconiq backend sends the payment details for the specific POS ID to the Payconiq app which contains 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.
  • The consumer is notified of the payment status via the app.
  • 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.

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.


Creating The Payconiq Static 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 location URL scheme.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.

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.
• Location URL scheme.
• Payment profile id of the merchant.
• POS id.
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:
• POS Id		 Payconiq unencoded URL payload parameters(POS ID)
POS00001
Payconiq encoded POS ID:
POS00001
4. Build the Payconiq URL payload using the following details.
• Location URL scheme
• Payment profile id of the merchant.
• POS Id.		 Sample format:

https://payconiq.com/l/1/{PaymentProfileId}/{POSId}

Sample URL payload:
https://payconiq.com/l/1/5bb37284e35e2b29e363df22/POS00001
5. UTF-8 encode the Payconiq URL Payload from step 4. Payconiq URL Payload before Encoding:
https://payconiq.com/l/1/5bb37284e35e2b29e363df22/POS00001

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Fl%2F1%2F5bb37284e35e2b29e363df22%2FPOS00001
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%2Fl%2F1%2F5bb37284e35e2b29e363df22%2FPOS00001

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:

Payment Profile Id: 5c18cbd1296e9a26d3278518

Formatted Url: Sample Static QR Code

Sample QR Code Image QR Code


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/pos

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


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/pos
  -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  -H 'Content-Type: application/json'
  -d '{
      "reference": "987456264",
      "amount": "999999",
      "currency": "EUR",
      "description": "Sample description",
      "callbackUrl": "https://www.testcallback.com/payconiq/payment",
      "bulkId": "centraal station pos-2",
      "posId": "POS00001",
      "shopName": "Bun Café",
      "shopId": "SHOP00001",
      "voucherEligibility": [
          {
            "voucherSchemes": [
              "BEL_MEAL_VOUCHER"
           ],
           "amount": 1013
          }
        ]
      }'

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.
posId
[String, required]
Maximum Length: 36 chars		 The external identifier for the point of sale where the Payment is taking place.
shopId
[String, optional]
Maximum Length: 36 chars		 The identifier of the shop where the Payment is created.
shopName
[String, optional]
Maximum Length: 36 chars		 The name of the shop where the Payment is created. This shop name is showed to the consumer when making Payments.

Only the first 23 characters are used for the remittance information.
voucherEligibility
[Object, optional]
List of Value-Added Services (vouchers) eligible amounts within the payment. Defines an amount that could be paid with proper voucher schemes.
voucherEligibility.voucherSchemes
[String, required]
List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherEligibility.amount
[Integer, required]
Amount in cents eligible for payment with voucher. EUR 10.13 will be 1013 

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5bdb1685b93d1c000bde96f2",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:45:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 999999,
    "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 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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
        {
          "voucherProvider": "BEL_MONIZZE",
           "voucherScheme": "BEL_MEAL_VOUCHER",
           "amount": 1013
        }
      ],
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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 '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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
             "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],           
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013 










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.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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

Pay mobile by scanning the QR code on a receipt.

Process Flow

Involved Parties:

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

Instore Receipt

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 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 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 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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.
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/5c18cbd1296e9a26d3278518?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/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%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%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9

Sample formatted URL

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


QR code properties:

Image Size: Medium

Image Format: PNG


QR code parameters:

Amount: 2.50 EUR

Description: Thanks for your money

Product Profile Id: 61375f7d093b13000669053f

Reference: sd89sd91%3Fsd9

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013. 










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.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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

Pay mobile by scanning the QR code on an invoice.

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.
  • In the case structured remittance information is required then the description parameter is used to provide the structured message.
  • Merchant prints the Payconiq QR code according to the style guide on an invoice and offers 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 via fingerprint, face ID or by entering the 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.
  • The provided structured message will show up on the bank statement for automatic reconciliation.

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.
  • Payment 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.
  • Correct Configurations - In case structured remittance is required this should be specified on contract signature or signing.


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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.
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/

NOTE: The combination of amount, reference, and description should always be unique. If not, the QR code could be considered paid.


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.
• Payment 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 or D=OGM(Structured Remittance Enabled)
A=1000
R=sd89sd91?sd9

Payconiq encoded URL payload parameters:
D=Invoice%20Payment or D=OGM(Structured Remittance Enabled)
A=1000
R=sd89sd91%3Fsd9
4. Build the Payconiq URL payload using the following details.
• Template URL scheme
• Payment 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/{PaymentProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}

Sample URL payload:
https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?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/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%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=L&c=https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9

Sample formatted URL

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


QR code properties:

Image Size: Medium

Image Format: PNG


QR code parameters:

Amount: 2.50 EUR

Description: Thanks for your money

Payment Profile Id: 61375f73093b13000669053e

Reference: 1nF97PCaUy5gm9thum15

Formatted Url: Sample Invoice QR Code

Sample QR Code Image QR Code


For the merchants who send the invoice over email and post both. They can provide the option to the user who opens the invoice received via email on phone to pay via deeplink.

Deeplink with Unstructured Remittance

Prerequisites

Amount: 2.50 EUR

Description: Invoice Payment

Payment Profile Id: 5c18cbd1296e9a26d3278518

Reference: 4198798465

Example Template Deeplink

https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=250&R=4198798465

Deeplink with Structured Remittance

Prerequisites

Amount: 2.50 EUR

Description: 173855053134 (OGM)

Payment Profile Id: 5c18cbd1296e9a26d3278518

Example Template Deeplink

https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=173855053134&A=250

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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": "2019-11-26T15:26:19.363Z",
           "expireAt": "2019-11-26T15:29:19.363Z",
           "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013. 










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.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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.

Remittance Information

Structured Remittance

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 1 exemption to this:

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 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 will show the structured message.





Sample Remittance Information


"424779266492"


Field Name Description Format
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]


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

Unstructured Remittance

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 1 exemption to this:

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 from the consumer’s payment account to the Merchant's/Partner’s payment account or Payconiq's payment account.





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 String: Space
[Max Length: 24]
Delimiter Field separator String: Space
[Max Length: 1]
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                          ”


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


Payconiq Online (V3) - Custom Online

In e-commerce, pay mobile by scanning the QR code during the check out.

Process Flow With Merchant's Checkout Page

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 With Merchant Checkout Page

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.

Process Flow With Payconiq Checkout Page

If you want user to complete the payment on Payconiq checkout page instead of your own checkout page then you can use the checkout URL in the create response and implement it instead of QR code URL. This will take the user to the Payconiq checkout page and display the QR code or "Pay with Payconiq app" button based on the device they are accessing your website. The Consumer sees the amount, the shop name and description after scanning. The Consumer then confirms the payment using a Payconiq supported app. The created Payment is valid for 1200 seconds (20 minutes). Once the Payment is confirmed by the consumer, an optional callback is sent to the merchant indicating the status of the Payment. After payment is completed, consumer is automatically redirected back to merchant's web shop using returnUrl, provided by merchant during payment creation.

Involved Parties:

  • Payconiq Supported App – Payconiq consumer application.
  • Merchant – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.
  • Payconiq Checkout Page – Web page hosted by Payconiq, which will facilitate payment process for consumer.

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, return url and other parameters.
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including checkout url link.
  • The merchant’s backend redirects consumer to Payconiq-hosted checkout page using checkout url provided in response for payment creation.
  • Payconiq Supported 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.
  • Checkout web page is redirecting consumer back to merchant's web shop using returnUrl, provided by the merchant during payment creation.
  • 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.
  • Merchant's ReturnUrl – This URL should be provided during payment creation request by merchant in order to redirect consumer back to the merchant's web shop after payment is completed on checkout page.


The Payconiq Brand Guide

You can find Payconiq's Branding Guidelines for Online Payments here.

W3Schools

W3SchoolsFor Belgium: the guidelines for Payconiq by Bancontact can be found here.


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 twenty(20) minutes (1200 seconds) after which it expires. If a payment does not take place within these twenty(20) 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" : "999999",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200",
         "returnUrl": "https://dummy.webshop/checkout/success",
         "voucherEligibility": [
             {
               "voucherSchemes": [
                 "BEL_MEAL_VOUCHER"
               ],
               "amount": 1013
             }
           ]
      }'

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 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.
returnUrl
[String, optional]
Maximum Length: 2048 chars		 A field set by the calling party used to redirect consumer back after payment is completed on checkout web page hosted by Payconiq. This field is mandatory if merchant wants to use checkout web page flow.
voucherEligibility
[Object, optional]
List of Value-Added Services (vouchers) eligible amounts within the payment. Defines an amount that could be paid with proper voucher schemes.]
voucherEligibility.voucherSchemes
[String, required]
List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherEligibility.amount
[Integer, required]
Amount in cents eligible for payment with voucher. EUR 10.13 will be 1013 

































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5bdb1685b93d1c000bde96f2",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 999999,
    "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"
        },
        "checkout": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2?token=530ea8a4ec8ded7d87620c8637354022cd965b143f257f8f8cb118e7f4a22d8f&returnUrl=https%3A%2F%2Fummy.webshop%2Fcheckout%2Fsuccess"
        }
    }
}

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 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.
_links.checkout
[Object, optional]		 Hypermedia GET URL used to redirect consumer to checkout web page hosted by Payconiq
_links.checkout.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, small (S) size and magenta in color.

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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.

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. There is no impact on a payment if it is not processed successfully by the merchant.

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013

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
  • AUTHORIZATION_FAILED
  • CANCELLED
  • EXPIRED

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

  • IDENTIFIED
  • PENDING


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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 will be notified of a payment.
Must be https for production.
debtor
[JSON Object, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount.Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier] currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013. 










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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],     
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013 










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

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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

In m-commerce, pay mobile with a redirect to a Payconiq enabled app.

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.

Process Flow with Payconiq Fallback Page

This solution is to avoid the cases where the user is taken to the browser showing Payconiq page to download the Payconiq app even when the user has the Payconiq app or Payconiq supported app installed in the phone. You can implement the checkout URL in the response of the create payment request instead of creating your own universal link from the deeplink href received in the response. The checkout URL works as a universal link if everything goes fine the user will be directly taken to the Payconiq supported app to complete the payment. In the edge cases, the user will be taken to the Payconiq fallback page where they can choose the Payconiq supported app and complete the payment. The Consumer sees the amount,the shop name and description after scanning. The Consumer then confirms the payment using a Payconiq supported app. The created Payment is valid for 1200 seconds (20 minutes). Once the Payment is confirmed by the consumer, an optional callback is sent to the merchant indicating the status of the Payment. After payment is completed, consumer is automatically redirected back to merchant's web shop using returnUrl, provided by merchant during payment creation.

Involved Parties:

  • Payconiq Supported App – Payconiq consumer application.
  • Merchant – Backend of merchant that integrates and interacts with Payconiq.
  • Payconiq Backend – Backend of Payconiq that provides integration and payment services.
  • Payconiq Checkout Page – Web page hosted by Payconiq, which will facilitate payment process for consumer.

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, return url and other parameters.
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including checkout url link.
  • The merchant’s backend redirects consumer to Payconiq-hosted checkout page using checkout url provided in response for payment creation.
  • User clicks on "Pay by Payconiq App" button and is taken to the Payconiq supported app to complete 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.
  • Checkout web page is redirecting consumer back to merchant's web shop using returnUrl, provided by the merchant during payment creation.
  • 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.

Implementation Options

There are two ways in which we offer App linking:

  • App to App Linking
  • Mobile Browser to App Linking


App to App (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.deeplink.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 twenty(20) minutes (1200 seconds) after which it expires. If a payment does not take place within these twenty(20) 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" : "999999",
         "currency" : "EUR",
         "callbackUrl": "https://dummy.network/api/v1/orders/payconiq",
         "description": "Test payment 12345",
         "reference": "12345",
         "bulkId":"Bulk-1-200",
         "returnUrl": "https://dummy.webshop/checkout/success",
         "voucherEligibility": [
            {
               "voucherSchemes": [
                 "BEL_MEAL_VOUCHER"
              ],
              "amount": 1013
            }
         ]    
      }'

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 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.
returnUrl
[String, optional]
Maximum Length: 2048 chars		 A field set by the calling party used to redirect consumer back after payment is completed on checkout web page hosted by Payconiq. This field is mandatory if merchant wants to use checkout web page flow.
voucherEligibility
[Object, optional]
List of Value-Added Services (vouchers) eligible amounts within the payment. Defines an amount that could be paid with proper voucher schemes.
voucherEligibility.voucherSchemes
[String, required]
List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherEligibility.amount
[Integer, required]
Amount in cents eligible for payment with voucher. EUR 10.13 will be 1013 


































Example Response:
HTTP/1.1 201 Created
{
    "paymentId": "5bdb1685b93d1c000bde96f2",
    "status": "PENDING",
    "createdAt": "2018-09-18T11:43:29.160Z",
    "expiresAt": "2018-09-18T11:43:29.160Z",
    "description": "Sample description",
    "reference": "987456264",
    "amount": 999999,
    "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"
        },
        "checkout": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2?token=530ea8a4ec8ded7d87620c8637354022cd965b143f257f8f8cb118e7f4a22d8f&returnUrl=https%3A%2F%2Fummy.webshop%2Fcheckout%2Fsuccess"
        }
    }
}

Note: To support deeplink in Payconiq by Bancontact app please parse the deeplink into lower case.

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 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.
_links.checkout
[Object, optional]		 Hypermedia GET URL used to redirect consumer to checkout web page hosted by Payconiq
_links.checkout.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 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 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.deeplink.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. There is no impact on a payment if it is not processed successfully by the merchant.

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "status": "SUCCEEDED",
    "debtor": {
        "name": "John",
        "iban": "*************12636"
    },
    "currency": "EUR",
    "reference": "12346816AFV",
    "voucherAmounts": [
      {
        "voucherProvider": "BEL_MONIZZE",
        "voucherScheme": "BEL_MEAL_VOUCHER",
        "amount": 1013
      }
   ]    
}

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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013


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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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 will be notified of a payment.
Must be https for production.
debtor
[JSON Object, optional]		 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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": "2019-11-26T15:26:19.363Z",
           "expireAt": "2019-11-26T15:29:19.363Z",
           "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],            
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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 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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers. This section will be available only if payment was confirmed. Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013. 










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

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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.

Payconiq Online (V3) - Top-up

Pay mobile by topping up a payment card or wristband.

Online 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 – 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.

Online 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 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.
  • Payment 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 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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.
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.
• Payment 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
• Payment 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/{paymentProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}

Sample URL payload:
https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?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/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9

Payconiq URL Payload after Encoding:
https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%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%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9

Sample formatted URL

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


QR code properties:

Image Size: Medium

Image Format: PNG


QR code parameters:

Amount: 2.50 EUR

Description: Thanks for your money

Payment Profile Id: 61375fac093b130006690540

Reference: 1nF97PCaUy5gm9thum15

Formatted Url: Sample Top-up 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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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",
    "voucherAmounts": [
          {
            "voucherProvider": "BEL_MONIZZE",
             "voucherScheme": "BEL_MEAL_VOUCHER",
             "amount": 1013
          }
        ],    
    "_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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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, optional]		 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.
voucherAmounts
[Object ,optional]		 Defines an amount that was paid with voucher scheme.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher. EUR 10.13 will be 1013 










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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",  
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],                       
            "_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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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",
            "voucherAmounts": [
               {
                  "voucherProvider": "BEL_MONIZZE",
                  "voucherScheme": "BEL_MEAL_VOUCHER",
                  "amount": 1013
               }
             ],             
            "_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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payconiq payment succeeded.
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.
voucherAmounts
[Object ,optional]		 List of amounts that was paid by vouchers.This section will be available only if payment was confirmed.Field is optional and will be provided for hybrid payments only.
voucherAmounts.voucherProvider
[String ,required]		 Provider of the Value Added Service (vouchers), has the form [alpha-3-country-code]_[identifier]. Currently known values:
BEL_MONIZZE
BEL_SODEXO
BEL_EDENRED
voucherAmounts.voucherScheme
[String ,required]		 List of voucher schemes that could be used to pay the amount. Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]currently known values:
BEL_MEAL_VOUCHER
BEL_ECO_VOUCHER
BEL_GIFT_VOUCHER
BEL_COVID_VOUCHER
BEL_SPORT_VOUCHER
BEL_CONSUMPTION_VOUCHER
voucherAmounts.amount
[String ,required]		 Amount in cents that was paid with voucher, EUR 10.13 will be 1013 










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.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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.



Payout Reconciliation API

The Payout Reconciliation APIs allows you to reconcile and match payouts your receive on your bank account. The Payout Reconciliation APIs are composed of Payouts, Payments and Refunds.

Get Payout List

This API is used to retrieve a list of payouts after a payout run. If there are no payouts for any reason, the API will return an empty list.

Type: REST

HTTP Verb: GET

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

PROD URL Definition: https://api.payconiq.com/v3/reconciliation/payouts


Get Payout List Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/payouts
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Get Payout List Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
date
[String, optional]		 The date in yyyy-MM-dd format for which the list of payouts should be returned. If not provided, current date in UTC will be used.


Get Payout List Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 10000,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "payouts": [
        {
            "payoutId": "5f44fd40812c8c49d8705541",
            "merchantId": "5cc6e4c15a2c1100071f0a5f",
            "bulkId": "Bulk-11111",
            "iban": "NL10ABNA8674905641",
            "payoutStatus": "SUCCEEDED",
            "payoutDate": "2020-08-25T12:00:00.211Z",
            "payoutCurrency": "EUR",
            "totalPayments": 3,
            "totalRefunds": 0,
            "totalPaymentAmount": 1549,
            "totalRefundAmount": 0,
            "payoutAmount": 1549
        },
        {
            "payoutId": "5f44fd40812c8c49d8705546",
            "merchantId": "5cc6e4c15a2c1100071f0a5f",
            "bulkId": "NONE",
            "iban": "NL10ABNA8674905641",
            "payoutStatus": "SUCCEEDED",
            "payoutDate": "2020-08-25T12:00:00.26Z",
            "payoutCurrency": "EUR",
            "totalPayments": 2,
            "totalRefunds": 2,
            "totalPaymentAmount": 541,
            "totalRefundAmount": 246,
            "payoutAmount": 295
        }
    ]
}


Get Payout List Response Body

The following parameters are included in the body of the payout list 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.
payouts.payoutId
[String, required]
Fixed length: 24 chars		 The unique identifier associated with the payout if a pay-out was successfully created.
payouts.merchantId
[String, required]
Fixed length: 24 chars		 The merchant id used during aggregation of the payout run.
payouts.bulkId
[String, required]
The bulk id used during aggregation of the of the payout run if available, if not NONE would be sent as default.
payouts.iban
[String, required]
The IBAN in (ISO 13616) format used during aggregation of the payout run and this will be used to payout to the merchant.
payouts.payoutStatus
[Enum, required]
1) SUCCEEDED - Payout was successfully processed. 2) FAILED - Payout failed.		 The status of the payout at Payconiq side.
payouts.payoutDate
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when payout was created in UTC.
payouts.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payouts.totalPayments
[Integer, required]		 The total number of payments included in the payout.
payouts.totalRefunds
[Integer, required]		 The total number of refunds included in the payout.
payouts.totalPaymentAmount
[Integer, required]		 The total payment amount in cents contained in the payout.
payouts.totalRefundAmount
[Integer, required]		 The total refund amount in cents contained in the payout.
payouts.payoutAmount
[String, required]		 Total amount in cents paid out to the merchant. 










HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Get Payout List 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable

Get Payout Payments

Endpoint to get list of payments.

Type: REST

HTTP Verb: GET

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

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


Get Payout Payments Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/payments
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Payout Payments Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
payout-id
[String, optional]		 ID of the payout.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
start-date
[String, optional]		 The start date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days When the start date is filled the end date needs to be filled as well.
end-date
[String, optional]		 The end date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days. When the end date is filled the start date needs to be filled as well.


Get Payout Payments Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 2,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "payments": [
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "John's Merchant",
            "submerchantName": "",
            "submerchantId": "",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 920,
            "reference": "11826440",
            "description": "Handmade Steel Towels",
            "transactionDate": "2020-09-01T12:30:36.538Z"
        },
        {
            "paymentId": "ec33dc9ff64675a9f5f778c3",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "John's Merchant",
            "submerchantName": "",
            "submerchantId": "",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 401,
            "reference": "19848995",
            "description": "plug-and-play",
            "transactionDate": "2020-09-01T12:34:37.742Z"
        }
    ]
}


Get Payout Payments Response Body

The following parameters are included in the body of the payout list 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.
payments.paymentId
[String, required]
Fixed length: 24 chars		 The id of the payment.
payments.payoutId
[String, optional]
Fixed length: 24 chars		 The id of the payout.
payments.paymentProfileId
[String, required]
Fixed length: 24 chars		 The profile id of the merchant used in the transaction.
payments.merchantName
[String, required]
The name of the merchant
payments.submerchantName
[String, optional]		 The name of the submerchant if it was a 4 corner merchant
payments.submerchantId
[String, optional]		 The id of the submerchant if it was a 4 corner merchant
payments.paymentChannel
[Enum, required]		 The channel of the payment.
payments.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payments.amount
[String, required]		 Total amount in cents of the transaction.
payments.reference
[String, optional]		 The reference provided by the merchant/partner during a payment/refund.
payments.description
[String, optional]		 The description provided by the merchant/partner during a payment/refund
payments.transactionDate
[String, required]YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when transaction was created in UTC 










HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Get Payout 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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]		 PAYOUT_NOT_FOUND: Payout with the id not found.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable

Get Payout Refunds

Endpoint to get list of refunds.

Type: REST

HTTP Verb: GET

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

PROD URL Definition: https://api.payconiq.com/v3/reconciliation/refunds


Get Payout Refunds Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/refunds
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Get Payout Refunds Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
payout-id
[String, optional]		 ID of the payout.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
start-date
[String, optional]		 The start date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days When the start date is filled the end date needs to be filled as well.
end-date
[String, optional]		 The end date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days. When the end date is filled the start date needs to be filled as well.


Get Payout Refunds Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 2,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "refunds": [
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "Ivan's 4C Merchant",
            "submerchantName": "",
            "submerchantId": "",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 323,
            "reference": "testing-0000000014",
            "description": "Testing refunds",
            "transactionDate": "2020-09-01T12:32:30.645Z",
            "refundId": "5f4e3f5ea7645312960aa6bb"
        },
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "Ivan's 4C Merchant",
            "submerchantName": "",
            "submerchantId": "",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 323,
            "reference": "testing-0000000015",
            "description": "Testing refunds",
            "transactionDate": "2020-09-01T12:32:36.589Z",
            "refundId": "5f4e3f64a7645312960aa6bc"
        }
    ]
}


Get Payout Refunds Response Body

The following parameters are included in the body of the payout list 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.
payments.paymentId
[String, required]
Fixed length: 24 chars		 The id of the payment.
payments.payoutId
[String, optional]
Fixed length: 24 chars		 The id of the payout.
payments.paymentProfileId
[String, required]
Fixed length: 24 chars		 The profile id of the merchant used in the transaction.
payments.merchantName
[String, required]
The name of the merchant
payments.submerchantName
[String, optional]		 The name of the submerchant if it was a 4 corner merchant
payments.submerchantId
[String, optional]		 The id of the submerchant if it was a 4 corner merchant
payments.paymentChannel
[Enum, required]		 The channel of the payment.
payments.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payments.amount
[String, required]		 Total amount in cents of the transaction.
payments.reference
[String, optional]		 The reference provided by the merchant/partner during a payment/refund.
payments.description
[String, optional]		 The description provided by the merchant/partner during a payment/refund
payments.transactionDate
[String, required]YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when transaction was created in UTC
refunds.refundId
[String, required]
Fixed length: 24 chars		 The id of the refund. 









HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Payout Refunds 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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]		 PAYOUT_NOT_FOUND: Payout with the id not found.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable


Payment Refund Service

Refunds

A refund allows an amount to be returned to your customer. All Payconiq payment methods support refunds for SUCCEEDED payment and are always directly paid out towards the IBAN of your customer. The refunded amount will be withheld from your next settlement (bulk payout).

Refunds are created using the Create Payment Refund API.

It is also possible to GET the IBAN via an API call and perform the payout towards your customer via your own process. Please see the “Get Refund IBAN” section.

Note : Only Payconiq payment can be refunded. Vouchers are not refunded via Payconiq.


Partial Refunds And Over Refunding

Partial refunds are fully supported. You can create multiple partial refunds if needed.


Insufficient Balance

If you have insufficient balance in your settlement, Payconiq will not refund the customer.


Refund Statuses

Refunds have their own status. An explanation of the status types can be found under section “Payment Refund Service HTTP Status and Error Codes”.


Possible Errors

Sometimes a situation can occur in which it is not possible to perform the refund. In such cases an HTTP error will be returned. Some of these situations are illustrated here: REFUND_NOT_POSSIBLE REFUND_NOT_ALLOWED DEBTOR_IBAN_NOT_AVAILABLE

It is possible that the payment has already been fully refunded. You can refer “Payment Refund Service HTTP Status and Error Codes” section for more error codes.


Retrying a Refund Request

In the event where an original refund request needs to be retried for any reason such as errors(4XX or 5XX), always use the same idempotency-key from the original request. The Payconiq refund system uses this key for idempotency checks. This will ensure that the same refunded is not requested more than once. If you wish to issue multiple refunds for the same payment, the idempotency-key should be changed.


Prerequisites

  • JSON Web Signature (JWS) : A data structure representing a digitally signed message. Note: The refund API does not work with API key. If the merchant starts using JWS for refund API then they should also consider switching to JWS to create payments. This will keep the system uniform and avoid any confusion between API key and JWS.
  • In order to initiate refunds, the functionality must be activated on the Payconiq Merchant account. Please contact your account manager or the Bancontact Payconiq Company team (for Belgium) for more information on how to activate refund and the Payconiq Merchant Contract.


Create Refund For Payment

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds

PROD URL Definition: https://api.payconiq.com/v3/payments/{payment-id}/refunds


Payment Refund Service Request Header

Attribute Comment/ Format
Signature [String, required] Authorization field which contains the JWS. xxxxxxxx…xxxxxxxxxxxx
Idempotency-Key [String, required] Unique request identifier with a maximum of 64 characters (we recommend UUID). It will be used for idempotency check.
Content-type [String, required] application/json Content type of the data in the request body.


Payment Refund Service Request Path

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



Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
        "amount": 0,
        "currency": "EUR",
        "description": "string"
      }'
Attribute Description
amount[Integer, required] Minimum: 1 Maximum: 999999 Payment amount in Euro cents.
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 Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.


Payment Refund Service Response

The following parameters are included in the header and body of the Payment Refund Service response.


Response Header


Example Response:
HTTP/1.1 201 Created
{

  "refundId": "string",
  "paymentId": "string",
  "amount": 0,
  "currency": "EUR",
  "status": "PENDING",
  "description": "string",
  "creationDate": "2020-05-12T13:20:02.855Z"

}
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
refundId[String, required] Fixed length: 24 chars The unique Refund id. Note: The refund creation endpoint is idempotent, so the same request can be retried in case of timeout or network issue.
paymentId[String, required] Fixed length: 24 chars] The unique Payment id.
amount[Integer, required] Payment amount in Euro cents.
currency[String, optional] Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status[String::enum, required] Allowed values: PENDING The status of the Payment.
description[String, optional] Custom description of the Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.
creationDate[String, required] Format: YYYY-MM-ddTHH:mm:ss.SSSZ The creation date and time of the Payment.


Payment Refund Service HTTP Status and Error Codes

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

HTTP/1.1 400 Bad Request
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
400[Integer]

VALIDATION_ERROR - request validation failed
401[Integer]

UNAUTHORIZED - caller does not have valid authentication credentials.
403[Integer]

ACCESS_DENIED - operation not allowed, caller does not have required authorities.
404[Integer]

REFUND_NOT_FOUND - refund not found.
404[Integer]

PAYMENT_NOT_FOUND - payment not found.
500[Integer]

TECHNICAL_ERROR: Technical error in the Payment service.
503[Integer]

Service Unavailable


Refund creation failed for business reasons

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

HTTP/1.1 422 Bad Request
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
422[Integer] PAYMENT_FOR_REFUND_NOT_FOUND - payment not found.
422[Integer] INVALID_REFUND_AMOUNT - refund amount is too high.
422[Integer] REFUND_NOT_ALLOWED - refund is not allowed for the merchant.
422[Integer] REFUND_NOT_POSSIBLE - refund is not possible for this payment at the moment.
422[Integer] DEBTOR_IBAN_NOT_AVAILABLE - debtor iban not available yet, try again later.
Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.
422[Integer] REFUND_REQUEST_CONFLICT - request id is already used by refund with different parameters.


Get Refund By ID

Endpoint to get refund details by id.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}

PROD URL Definition: https://api.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}


Payment Refund Service Request Header



curl -X GET
 https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}

 -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'
Attribute Comment/ Format
Signature[String, required] Authorization field which contains the JWS. xxxxxxxx…xxxxxxxxxxxx
Content-type[String, required] application/json Content type of the data in the request body.


Payment Refund Service 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.
refund-id[Integer, required] Fixed length: 24 chars The unique identifier of a refund as provided by the payment refund service.


Payment Refund Service 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


Payment Refund Service Response Body

The following parameters are included in the body of the payment refund service.

Response Body

HTTP/1.1 200 OK
{
  "refundId": "string",
  "paymentId": "string",
  "amount": 0,
  "currency": "EUR",
  "status": "PENDING",
  "description": "string",
  "creationDate": "2020-05-12T14:45:14.323Z"
}
Attribute Description
refundId[String, required] Fixed length: 24 chars The unique Refund id. Note: The refund creation endpoint is idempotent, so the same request can be retried in case of timeout or network issue.
paymentId[String, required] Fixed length: 24 chars The unique Payment id.
amount[Integer, required] Payment amount in Euro cents.
currency[String, optional] Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status[String::enum, required] Allowed values: PENDING, PROCESSING, REFUNDED, FAILED The status of the Payment.
description[String, optional] Custom description of the Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.
creationDate[String, required] Format: YYYY-MM-ddTHH:mm:ss.SSSZ The creation date and time of the Payment.


Refund Statuses

Status Name Status Description
PENDING Refund request accepted by Payconiq, will be processed soon.
PROCESSING Money was paid to consumer, but was not deducted from the merchant. Payconiq will try to collect the refund for 14 days after which the refund expires and manual collection process will take over.
REFUNDED Refund request successfully processed, and money was deducted from merchant and paid to consumer.
FAILED Refund request processing failed for technical reasons, money movement didn't happen.


Payment Refund Service Status and Error Codes

HTTP/1.1 422 Unprocessable Entity
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
400[Integer]

VALIDATION_ERROR - request validation failed.
401[Integer]

UNAUTHORIZED - caller does not have valid authentication credentials.
403[Integer]

ACCESS_DENIED - operation not allowed, caller does not have required authorities.
404[Integer]

REFUND_NOT_FOUND - refund not found.
404[Integer]

PAYMENT_NOT_FOUND - payment not found.
500[Integer]

TECHNICAL_ERROR:Technical error in the Payment service.
503[Integer]

Service Unavailable


Refund Remittance

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.



Unstructured Refund remittance:

Format of unstructured refund remittance information:

Payconiq RefundID refund for Creditor name Description ref Reference field


Field Name Description Format
Issuer The entity that facilitates Payconiq Payment. String
[Max Length: 8]
Delimiter Field separator. String: Space
[Max Length: 1]
RefundID A unique identifier representing a Payconiq Refund Transaction. String
[Max Length: 24]
Delimiter Field separator. String: Space
[Max Length: 1]
Creditor 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]
Description A description linked to a Payconiq Refund Transaction. Field is padded with spaces if the max length is not reached. String
[Max Length: 31]
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]		 
Sample Remittance Information


“Payconiq 61f1204b4d07487d6ac57842 refund for Cookie Shop             8zyeAIKOt54Ybc3yfnL5            ref 2633686194                        "


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

“Payconiq 61f1204b4d07487d6ac57842 refund for Cookie Shop             8zyeAIKOt54Ybc3yfnL5            ref 2633686194                          ”


Note: Structured remittance is not applicable for refund.


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.
Payment Acknowledge API The Payment Acknowledge API is used to successfully aknowledge a payment via the Payconiq backend. This is used for instore payments.
Void Payment API The Void Payment API is used to void a payment via the Payconiq backend. This is used for instore payments.


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.
JSON Web Signatures(JWS) All requests to the Payconiq backend are verified using JSON Web Signatures(JWS).The use of JWS serves as a mechanism for authentication and guarantees the integrity of all requests that are sent to Payconiq.
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 a Merchant Identifier and Payment Profile Identifier.The partner has to provide the URL on which they have hosted the JWKs in order to activate the account. The JWS will be used to gain authorised access to the Payment Service Provider API endpoints. PQI distributes 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 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 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 they can no longer have access to 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 partner can no longer have access to 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 is an exemption to this:

  • 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 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 Brand Guide

Online Payments

You can find Payconiq's Branding Guidelines for Online Payments here.

W3SchoolsFor Belgium: the guidelines for Payconiq by Bancontact can be found here.

W3Schools

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.


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

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. The Payconiq backend refuses any connections without TLS encryption, such as plain HTTP. You may choose to receive the payment callbacks either via one-way or two-way(requires enablement on server side) TLS encryption.

TLS One-way TLS Encryption Support

In the TLS One-way encyrption, all callback requests will be encrypted where the Payconiq backend verifies the certificate of the Partner anytime Payconiq sends a callback request. There is not requirement to exchange certificates beforehand and the callbacks should work out of the boc. Please contact [email protected] if you are having any issues.

TLS Two-way TLS Encryption Support (TLS-Mutual Authentication)

In the two-way TLS encryption support, the parter verifies the details of Payconiq before processing the details of the callback. This allows Payconiq and the Partner to communicate with privacy and data integrity with an additional JWS security. Please reach out to [email protected] regarding necessary certificate details that need to be shared if this is required.

TLS-MA Certificate Rotation & Pinning

Payconiq reserves the right to rotate its certificate without informing the Partner since each certificate has a validity period or may be compromised. In case the Partner pins certificates, it must only pin the Payconiq certificate on the CN name. This will make rotation of the certificate seamless.

Digital Signatures (JWS)

All requests to the Payconiq backend are verified using JSON Web Signatures(JWS).The use of JWS serves as a mechanism for authentication and guarantees the integrity of all requests that are sent to Payconiq. When using JWS, an attacker cannot simply alter the content of the messages sent between the client and server and vice versa. An attacker would also need to know the corresponding private key which is used for signing. The JWS must be included in all API requests using a signature header. If a valid request with a correct signature is sent to Payconiq, Payconiq sends a valid response with a corresponding signature.

Security Requirements

  • The request and responses are signed using a Detached JWS Signature.
  • Algorithm for signing is ES256 with a minimum key size of 256 bits.
  • All requests and responses are authenticated by verifying signatures. This includes the body, path and certain headers of each request/response.
  • The certificates for signature verification MUST be provided in a JSON Web Key (JWK) format as JSON Web Key Set (JWKs). Both Payconiq and Partner will share the JWKs through a publicly hosted URL.
  • The JWK to be used for signature verification will be identified by the Key Id (kid) which is part of the JSON Object Signing and Encryption (JOSE) Header of the JWS.
  • The Certificate used for signing should be obtained from a Certificate Authority(CA) with good reputation. Payconiq’s preferred CAs include QuoVadis, IdenTrust and DigiCert.
  • The Partner must protect their private keys, preferably in a hardware security module (HSM).
  • The JWS must be computed as per the specifications documented.


JSON Web Signature Definition

The Detached JSON Web Signature represents a Payconiq digitally signed content using JSON data structures and base64url encoding which makes up the JSON Web Signature (JWS). The JWS is made up of an Unencoded Payload with Compact Serialization which means that the payload which is signed is not included in the JWS. The JWS represents the following logical fields separated by dots (.)

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

Header Parameter Description
JSON Web Signature (JWS) A data structure representing a digitally signed message.
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.
MUST be set to the ES256 algorithm
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.
The critical headers are to contain the following parameters: The Payconiq Profile id assigned to the partner.
The Payconiq Profile id assigned to the partner.
Date and time when the signature was created. ISODateTime format], expressed in UTC time format(YYYY-MM-DDThh:mm:ss.sssZ).
A unique request identifier.
* The path or endpoint being called by the partner.

The JOSE Header setup consists of the following:



{
  "typ": "JOSE+JSON",
  "kid": "es.signature.acc.payconiq.com",
  "alg": "ES256",
  "https://payconiq.com/iat": "2019-07-26T11:04:50.200734Z",
  "https://payconiq.com/jti": "5d089c577eb41c0007fcf12b",
  "https://payconiq.com/path": "/v3/payments/subMerchant",
  "https://payconiq.com/iss": "5cc6e4c15a2c1100071f0a5f",
  "https://payconiq.com/sub": "5cc6e4c88b6e691156d1376d",
  "crit": [
    "https://payconiq.com/iat",
    "https://payconiq.com/jti",
    "https://payconiq.com/path",
    "https://payconiq.com/iss",
    "https://payconiq.com/sub"
  ]
}

{

"typ": "jose+json",

"kid": "JWK kid",

"alg": "ES256",

"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": " request path https://api.payconiq.com/v3/payments/subMerchant",

"https://payconiq.com/iss" : "{Merchant Id}",

"https://payconiq.com/sub" : "{Profile Id}",

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

}


JSON Web Key (JWK)

The JSON Web Key(JWK) is a JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value. It is used to verify the JWS sent by the client. The JWK is stored in a JSON Web Key Set (JWKs).

The JWK has several parameters with the following which are mandatory. More details can be found here.

  • "alg" – The algorithm parameter identifies the algorithm intended for use with the key. Payconiq supports the ES256 algorithm.
  • "kid" – The key ID parameter is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover.
  • "x5c" – The X.509 certificate chain contains a chain of one PKIX certificate.
  • "kty" – The key type parameter identifies the cryptographic algorithm family used with the key, such as “RSA” or “EC”.
  • "use" – The public key use parameter identifies the intended use of the public key. The value must always be set to “sig”.

For the ES256 algorithm, the following additional parameters are mandatory

  • "crv" – The elliptic curve.
  • "x" – X coordinates of the elliptic curve.
  • "y" – Y coordinates of the elliptic curve.


Partner - Hosting and Rotating the JWKs

Hosting the JWK

The JWK must be hosted via a publicly available endpoint of the partner. The partner must guarantee the uptime of the website where the JWK is hosted so that a signature which is sent by the partner can be validated by Payconiq at all times.

Rotating the JWK

In order to rotate a key, the partner must append the new JWK to the existing JWKs for the first 12 hours. After the 12 hours, the old JWK may be removed from the host site location and replaced with the new JWK used to generate signatures. Signatures must be generated using the new JWK.

Payconiq will cache the JWKS for a period of 12 hours and use it to verify any signature sent by the partner. After 12 hours, the JWKS will be re-cached automatically. If there are any changes made to the JWKS, the changes will come into effect.


Payconiq - Hosting and Rotating the JWKs

Payconiq will follow and below guidelines with regards to hosting and rotating JWKs.

Hosting the JWK

Payconiq hosts its External and Production JWKs using the following endpoints.

Rotating the JWK

Payconiq will append a new JWK to the existing JWKs for the first 24 hours. After the 24-hour period, the old JWK will be removed from the host site location.

Partners should cache the JWKs for a period of 12 hours and use it to verify any signature sent by Payconiq. After 12 hours, the JWKs must be re-cached automatically. If there any changes made to the JWKs, the changes should come into effect.


JWS Usage

To prove that the partner sent a request message to Payconiq, the partner must include a detached JWS in the header of the request message. Upon receipt of the request message, Payconiq verifies the JWS of the request. If successfully verified, Payconiq will process the request message and respond with an appropriate message.

To prove that Payconiq responded to the request message, Payconiq includes a detached JWS in the response message to the partner. Upon receipt of the response message, the partner must verify the JWS of the response. If successfully verified, the partner may process the response message.


Request Messages

The JWS is mandatory in the request header of all messages sent to Payconiq. Payconiq will verify the JWS using the JWK hosted by the partner. If Payconiq fails to verify the JWS in the request message, it will be denied with a HTTP 401 or 403 error response message.


Response Messages

The JWS is mandatory in the response header of all messages sent by Payconiq. For 401 and 5XX response messages, Payconiq will include a JWS if all mandatory fields are present in the JWS of the request message with a valid signature. The partner must verify the JWS using the JWK hosted by Payconiq. If the partner fails to verify the JWS sent in the response, it must not process the response. The partner must get in touch with Payconiq to report the problem.


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 partner 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
PENDING_MERCHANT_ACKNOWLEDGEMENT A Payment has been has been confirmed by a consumer and is pending acknowledgment from the partner to either complete or void the payment.
Note: This is only supported where Void is enabled for the partner.		 Intermediary
VOIDED A Payment has been cancelled for technical reasons after the consumer confirmed the payment.
Note: This is only supported where Void is enabled for the partner.		 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. You may choose to receive the payment callbacks either via one-way or two-way TLS encryption.

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 partner, 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 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 Instore – On a Terminal with Void enabled.

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


Supporting Void Payments

To ensure that the payment terminal remains in the lead of the payment, Payconiq supports void as a functionality. With support for void, an intermidiate step is introduced which allows the Partner to acknowledge to Payconiq that the terminal completed the processing of the payment successfully. In the event where something goes wrong while completing the payment such as technical problems, the Partner can inform Payconiq to void the payment. A partner has 7 days from when a payment was created to either acknowledge or void a payment.


Notes

  • A partner must be bulk-enabled to be able to support void payments.
  • A partner will acknowledge to Payconiq that the payment was processed successfully on the payment terminal using an API.
  • A partner will cancel a payment after it has been confirmed by a consumer to void the payment using an API.
  • A partner has 7 days (168 hours) to either acknowledge or void a payment.
  • For technical failures, a partner must continue to acknowledge a payment for 7 days (168 hours) until Payconiq returns success.
  • For technical failures, a partner must continue to void a payment for 7 days (168 hours) until Payconiq returns success.
  • A payment is automatically voided after 7 days (168 hours) if it is not acknowledged or voided.


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) With Void Enabled 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 customer is debited, and the payment is in a state that is pending an acknowledgment (PENDING_MERCHANT_ACKNOWLEDGEMENT) from the Submerchant/terminal.
  • Payconiq sends a callback to the Submerchant to notify them about the status of the payment. The Submerchant can also poll Payconiq for the status of the payment.
  • Towards the consumer we will inform them to check the terminal for the final status of the payment.
  • The Submerchant terminal sends a positive acknowledgement for the payment to indicate that the terminal processed the payment successfully.
  • The payment is marked as SUCCEEDED and Payconiq facilitates the transfer of funds to the Partner as per the bulk schedule.


Note - Voiding a Payment

  • In the event where the terminal fails to complete processing the payment while the payment is pending acknlowledgement, the Partner must void the payment.
  • After a payment is voided, the customer will be credited and the Partner will not receive funds for the voided payment.

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. The Consumer then confirms the payment using a Payconiq supported app. The created Payment is valid for 1200 seconds (20 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 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.

Payconiq Online – Checkout page flow

The Payconiq Online – Checkout page flow 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(including returnUrl) via the Payconiq backend and partner receives checkout url in the payment creation response. Partner should redirect consumer to the checkout page, hosted by Payconiq, using checkout url. 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. The created Payment is valid for 1200 seconds (20 minutes). Once the Payment is confirmed by the consumer, an optional callback is sent to the partner indicating the status of the Payment. After payment is completed, consumer is automatically redirected back to merchant's web shop using returnUrl, provided by partner during payment creation.

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

Payconiq Online (Custom Website Checkout) Process Flow Payconiq Online – Checkout page 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)
  • Payconiq backend returns the created payment with the Payconiq payment id and other relevant details to the merchant’s backend – including checkout url link.
  • The merchant’s backend redirects consumer to Payconiq-hosted checkout page using checkout url provided in response of payment creation.
  • The consumer scans the Dynamic QR code and then confirms the Payment with a Payconiq supported app.
  • Checkout web page is redirecting consumer back to merchant's web shop using returnUrl, provided by the partner during payment creation.
  • 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.

  • Payconiq Instore: A Payment is valid for 2 minutes and if not confirmed or cancelled, the payment expires, and a new Payment has to be created.
  • Payconiq Online: A Payment is valid for 20 minutes and if not confirmed or cancelled, the payment expires, and a new Payment 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
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..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 'Signature: xxxxxxxx..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",
         "returnUrl": "https://dummy.webshop/checkout/success"
         "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 of the country where the merchant is based in. 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.
returnUrl
[String, optional]
Maximum Length: 2048 chars		 A field set by the calling party used to redirect consumer back after payment is completed on checkout web page hosted by Payconiq. This field is mandatory if merchant wants to use checkout web page flow.
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"
        },
        "checkout": {
            "href": "https://payconiq.com/pay/2/5bdb1685b93d1c000bde96f2?token=530ea8a4ec8ded7d87620c8637354022cd965b143f257f8f8cb118e7f4a22d8f&returnUrl=https%3A%2F%2Fummy.webshop%2Fcheckout%2Fsuccess"
        }
    }
}

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.
_links.checkout
[Object, optional]		 Hypermedia GET URL used to redirect consumer to checkout web page hosted by Payconiq
_links.checkout.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.
cl
[String :: Enum]
Allowed Values: magenta, black		 The colour of the QR code.
Default is magenta.

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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payment succeeded.
status
[String::enum, required]

Allowed values:PENDING, IDENTIFIED, AUTHORIZED, AUTHORIZATION_FAILED, SUCCEEDED, FAILED, CANCELLED, PENDING_MERCHANT_ACKNOWLEDGEMENT, VOIDED, EXPIRED.		 The status of the Payment.
debtor
[JSON Object, required]		 The consumer account object that makes payments to the merchant
debtor.name
[String, optional]		 Name of the consumer.
debtor.iban
[String, optional]		 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
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..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 'Signature: xxxxxxxx..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": "2019-11-26T15:26:19.363Z",
    "expireAt": "2019-11-26T15:29:19.363Z",
    "succeededAt": "2019-11-26T15:27:34.835Z",
    "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.
succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payment succeeded.
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, PENDING_MERCHANT_ACKNOWLEDGEMENT, VOIDED		 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, optional]		 The consumer account object that makes payments to the merchant
debtor.name
[String, optional]		 Name of the consumer.
debtor.iban
[String, optional]		 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 used 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
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..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 'Signature: xxxxxxxx..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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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": "2019-11-26T15:26:19.363Z",
            "expireAt": "2019-11-26T15:29:19.363Z",
            "succeededAt": "2019-11-26T15:27:34.835Z",
            "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.succeededAt
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The date and time when a Payment succeeded.
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, PENDING_MERCHANT_ACKNOWLEDGEMENT, VOIDED		 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]		 Name of the consumer.
details.debtor.iban
[String, optional]		 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
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:

curl -X DELETE
  https://api.ext.payconiq.com/v3/payments/5ba35a3d0989e3000758b9c1
  -H 'Signature: xxxxxxxx.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


Void Payment

This endpoint is used to void a payment. A payment can only be voided only if the status is PENDING_MERCHANT_ACKNOWLEDGEMENT. Once the request is processed successfully, the status of the payment is set to VOIDED.

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}


Void Payment Request Header

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:

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

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


Void Payment Request Body

There is no body in void payment request.


Void Payment Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the void 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


Void Payment Response Body

There is no body returned in the body of a void 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"
}

Void 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


Payment Acknowledge

This endpoint is used to acknowledge a payment and inform Payconiq that the payment has been successfully processed by the payment terminal. After a payment is successfully acknowledged, the payment transitions to a final endstuatus of succeeded. This endpoint can be called multiple times.

Type: REST

HTTP Verb: POST

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

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


Payment Acknowledge Request Header

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx.xxxxx
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/{paymentId}/acknowledge'
-H 'Signature: xxxxxxxx.xxx.xxxxxxxxxxxx'
-H 'Content-Type: application/json'
-d
'{  
"currency": "EUR",
"amount": 0,
"reference": "string"
}'

Payment Acknowledge 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.

Payment Acknowledge Request Body

Attribute Description
amount
[Integer, required]
Minimum: 1
Maximum: 999999		 Payment amount in Euro cents.
currency
[String, Optional]		 Payment currency code in ISO 4217 format. Only Euro supported at the moment.
Value: EUR
reference
[String, optional]
Maximum Length: 35 chars		 External payment reference used to reference the Payconiq payment in the calling party's system.

Payment Acknowledge Response Header





HTTP/1.1 204 No Content

The following parameters are included in the header of the payment acknowledge 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


Payment Acknowledge Response Body

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









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


Payment Acknowledge 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.
404
[Integer]		 PAYMENT_NOT_FOUND No payment could be found for the supplied identifier
422
[Integer]		 PAYMENT_VOIDED Payment is already voided
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable


Get Refund IBAN

A get refund IBAN call allows an amount to be returned to your customer via your own process. This endpoint does not perform the actual payout towards your customer. This endpoint is intended to provide the necessary data so that customer can be refunded via your own refund process. If it is desired that Payconiq directly pays out your customer then please look at our integration guidelines under the "Payment Refund Services" section.

Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.

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 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Get Refund IBAN Request Header

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..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.



Payout Reconciliation API

The Payout Reconciliation APIs allows you to reconcile and match payouts your receive on your bank account. The Payout Reconciliation APIs are composed of Payouts, Payments and Refunds.

Get Payout List

This API is used to retrieve a list of payouts after a payout run. If there are no payouts for any reason, the API will return an empty list.

Type: REST

HTTP Verb: GET

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

PROD URL Definition: https://api.payconiq.com/v3/reconciliation/payouts


Get Payout List Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/payouts
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Get Payout List Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
date
[String, optional]		 The date in yyyy-MM-dd format for which the list of payouts should be returned. If not provided, current date in UTC will be used.


Get Payout List Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 10000,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "payouts": [
        {
            "payoutId": "5f44fd40812c8c49d8705541",
            "merchantId": "5cc6e4c15a2c1100071f0a5f",
            "bulkId": "Bulk-11111",
            "iban": "NL10ABNA8674905641",
            "payoutStatus": "SUCCEEDED",
            "payoutDate": "2020-08-25T12:00:00.211Z",
            "payoutCurrency": "EUR",
            "totalPayments": 3,
            "totalRefunds": 0,
            "totalPaymentAmount": 1549,
            "totalRefundAmount": 0,
            "payoutAmount": 1549
        },
        {
            "payoutId": "5f44fd40812c8c49d8705546",
            "merchantId": "5cc6e4c15a2c1100071f0a5f",
            "bulkId": "NONE",
            "iban": "NL10ABNA8674905641",
            "payoutStatus": "SUCCEEDED",
            "payoutDate": "2020-08-25T12:00:00.26Z",
            "payoutCurrency": "EUR",
            "totalPayments": 2,
            "totalRefunds": 2,
            "totalPaymentAmount": 541,
            "totalRefundAmount": 246,
            "payoutAmount": 295
        }
    ]
}


Get Payout List Response Body

The following parameters are included in the body of the payout list 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.
payouts.payoutId
[String, required]
Fixed length: 24 chars		 The unique identifier associated with the payout if a pay-out was successfully created.
payouts.merchantId
[String, required]
Fixed length: 24 chars		 The merchant id used during aggregation of the payout run.
payouts.bulkId
[String, required]
The bulk id used during aggregation of the of the payout run if available, if not NONE would be sent as default.
payouts.iban
[String, required]
The IBAN in (ISO 13616) format used during aggregation of the payout run and this will be used to payout to the merchant.
payouts.payoutStatus
[Enum, required]
1) SUCCEEDED - Payout was successfully processed. 2) FAILED - Payout failed.		 The status of the payout at Payconiq side.
payouts.payoutDate
[String, optional]
Format:
YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when payout was created in UTC.
payouts.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payouts.totalPayments
[Integer, required]		 The total number of payments included in the payout.
payouts.totalRefunds
[Integer, required]		 The total number of refunds included in the payout.
payouts.totalPaymentAmount
[Integer, required]		 The total payment amount in cents contained in the payout.
payouts.totalRefundAmount
[Integer, required]		 The total refund amount in cents contained in the payout.
payouts.payoutAmount
[String, required]		 Total amount in cents paid out to the merchant. 










HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Get Payout List 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable

Get Payout Payments

Endpoint to get list of payments.

Type: REST

HTTP Verb: GET

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

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


Get Payout Payments Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/payments
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Payout Payments Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
payout-id
[String, optional]		 The unique identifier associated with the payout if a pay-out was successfully created.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
start-date
[String, optional]		 The start date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days When the start date is filled the end date needs to be filled as well.
end-date
[String, optional]		 The end date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days. When the end date is filled the start date needs to be filled as well.


Get Payout Payments Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 2,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "payments": [
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "John's Merchant",
            "submerchantName": "My Enterprise",
            "submerchantId": "79839YHGGH",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 920,
            "reference": "11826440",
            "description": "Handmade Steel Towels",
            "transactionDate": "2020-09-01T12:30:36.538Z"
        },
        {
            "paymentId": "ec33dc9ff64675a9f5f778c3",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "John's Merchant",
            "submerchantName": "Veggie Store",
            "submerchantId": "3794757YHF",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 401,
            "reference": "19848995",
            "description": "plug-and-play",
            "transactionDate": "2020-09-01T12:34:37.742Z"
        }
    ]
}


Get Payout Payments Response Body

The following parameters are included in the body of the payout list 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.
payments.paymentId
[String, required]
Fixed length: 24 chars		 The id of the payment.
payments.payoutId
[String, optional]
Fixed length: 24 chars		 The id of the payout.
payments.paymentProfileId
[String, required]
Fixed length: 24 chars		 The profile id of the merchant used in the transaction.
payments.merchantName
[String, required]
The name of the merchant
payments.submerchantName
[String, optional]		 The name of the submerchant if it was a 4 corner merchant
payments.submerchantId
[String, optional]		 The id of the submerchant if it was a 4 corner merchant
payments.paymentChannel
[Enum, required]		 The channel of the payment.
payments.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payments.amount
[String, required]		 Total amount in cents of the transaction.
payments.reference
[String, optional]		 The reference provided by the merchant/partner during a payment/refund.
payments.description
[String, optional]		 The description provided by the merchant/partner during a payment/refund
payments.transactionDate
[String, required]YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when transaction was created in UTC 










HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Get Payout 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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]		 PAYOUT_NOT_FOUND: Payout with the id not found.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable

Get Payout Refunds

Endpoint to get list of refunds.

Type: REST

HTTP Verb: GET

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

PROD URL Definition: https://api.payconiq.com/v3/reconciliation/refunds


Get Payout Refunds Header

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

Attribute Comment/ Format
Signature
[String, required]		 Authorization field which contains the JWS.
xxxxxxxx..xxxxxxxxxxxx		 




Example Request:
curl -X GET
  https://api.ext.payconiq.com/v3/reconciliation/refunds
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'

Get Payout Refunds Request Path

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

Attribute Description
size
[Integer, optional]		 The size of the page to be returned in list requests.
NB: The size is fixed as defaults to 10000.
payout-id
[String, optional]		 The unique identifier associated with the payout if a pay-out was successfully created.
page
[Integer, optional]		 Zero-based page index in list requests.
NB: The page defaults to 0 if not present in the request path.
start-date
[String, optional]		 The start date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days When the start date is filled the end date needs to be filled as well.
end-date
[String, optional]		 The end date (inclusive) in yyyy-MM-dd format for which the list of payments/refunds should be returned. The maximum difference between the start date and end date can be 30 days. When the end date is filled the start date needs to be filled as well.


Get Payout Refunds Response Header

The following parameters are included in the header of the payout 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 








Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "size": 2,
    "totalPages": 1,
    "totalElements": 2,
    "number": 0,
    "refunds": [
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "Ivan's 4C Merchant",
            "submerchantName": "My Enterprise",
            "submerchantId": "aaioay9nmqtn2qv",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 323,
            "reference": "testing-0000000014",
            "description": "Testing refunds",
            "transactionDate": "2020-09-01T12:32:30.645Z",
            "refundId": "5f4e3f5ea7645312960aa6bb"
        },
        {
            "paymentId": "1827fe4ac1f10ba942247444",
            "payoutId": "5f4ec46064b30e3b08ebb96c",
            "paymentProfileId": "5cc6e4c88b6e691156d1376d",
            "merchantName": "Ivan's 4C Merchant",
            "submerchantName": "My Enterprise",
            "submerchantId": "aaioay9nmqtn2qv",
            "paymentChannel": "ONLINE",
            "currency": "EUR",
            "amount": 323,
            "reference": "testing-0000000015",
            "description": "Testing refunds",
            "transactionDate": "2020-09-01T12:32:36.589Z",
            "refundId": "5f4e3f64a7645312960aa6bc"
        }
    ]
}


Get Payout Refunds Response Body

The following parameters are included in the body of the payout list 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.
payments.paymentId
[String, required]
Fixed length: 24 chars		 The id of the payment.
payments.payoutId
[String, optional]
Fixed length: 24 chars		 The id of the payout.
payments.paymentProfileId
[String, required]
Fixed length: 24 chars		 The profile id of the merchant used in the transaction.
payments.merchantName
[String, required]
The name of the merchant
payments.submerchantName
[String, optional]		 The name of the submerchant if it was a 4 corner merchant
payments.submerchantId
[String, optional]		 The id of the submerchant if it was a 4 corner merchant
payments.paymentChannel
[Enum, required]		 The channel of the payment.
payments.currency
[String, required]		 Payment currency code in ISO 4217 format. Only Euros supported at the moment.
payments.amount
[String, required]		 Total amount in cents of the transaction.
payments.reference
[String, optional]		 The reference provided by the merchant/partner during a payment/refund.
payments.description
[String, optional]		 The description provided by the merchant/partner during a payment/refund
payments.transactionDate
[String, required]YYYY-MM-ddTHH:mm:ss.SSSZ		 The timestamp, when transaction was created in UTC
refunds.refundId
[String, required]
Fixed length: 24 chars		 The id of the refund. 









HTTP/1.1 400 Bad Request
{
    "code": "BAD_REQUEST",
    "message": "Period between start and end date can not be bigger than 30 days"
}

Payout Refunds 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]		 BAD_REQUEST: Some field in the request was not formatted correctly.
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]		 PAYOUT_NOT_FOUND: Payout with the id not found.
500
[Integer]		 TECHNICAL_ERROR: Technical error in the Payconiq payment service.
503
[Integer]		 Service Unavailable


Payment Refund Service

Refunds

A refund allows an amount to be returned to your customer. All Payconiq payment methods support refunds for SUCCEEDED payment and are always directly paid out towards the IBAN of your customer. The refunded amount will be withheld from your next settlement (bulk payout).

Refunds are created using the Create Payment Refund API.

It is also possible to GET the IBAN via an API call and perform the payout towards your customer via your own process. Please see the “Get Refund IBAN” section.


Partial Refunds And Over Refunding

Partial refunds are fully supported. You can create multiple partial refunds if needed.


Insufficient Balance

If you have insufficient balance in your settlement, Payconiq will not refund the customer.


Refund Statuses

Refunds have their own status. An explanation of the status types can be found under section “Payment Refund Service HTTP Status and Error Codes”.


Possible Errors

Sometimes a situation can occur in which it is not possible to perform the refund. In such cases an HTTP error will be returned. Some of these situations are illustrated here: REFUND_NOT_POSSIBLE REFUND_NOT_ALLOWED DEBTOR_IBAN_NOT_AVAILABLE

It is possible that the payment has already been fully refunded. You can refer “Payment Refund Service HTTP Status and Error Codes” section for more error codes.


Retrying a Refund Request

In the event where an original refund request needs to be retried for any reason such as errors(4XX or 5XX), always use the same idempotency-key from the original request. The Payconiq refund system uses this key for idempotency checks. This will ensure that the same refunded is not requested more than once. If you wish to issue multiple refunds for the same payment, the idempotency-key should be changed.


Prerequisites

  • JSON Web Signature (JWS) : A data structure representing a digitally signed message. Note: The refund API does not work with API key. If the merchant starts using JWS for refund API then they should also consider switching to JWS to create payments. This will keep the system uniform and avoid any confusion between API key and JWS.
  • In order to initiate refunds, the functionality must be activated on the Payconiq Merchant account. Please contact your account manager or the Bancontact Payconiq Company team (for Belgium) for more information on how to activate refund and the Payconiq Merchant Contract.


Create Refund For Payment

Type: REST

HTTP Verb: POST

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds

PROD URL Definition: https://api.payconiq.com/v3/payments/{payment-id}/refunds


Payment Refund Service Request Header

Attribute Comment/ Format
Signature [String, required] Authorization field which contains the JWS. xxxxxxxx…xxxxxxxxxxxx
Idempotency-Key [String, required] Unique request identifier with a maximum of 64 characters (we recommend UUID). It will be used for idempotency check.
Content-type [String, required] application/json Content type of the data in the request body.


Payment Refund Service Request Path

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



Example Request:
curl -X POST
  https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds
  -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'
  -H 'Cache-Control: no-cache'
  -H 'Content-Type: application/json'
  -d '{
        "amount": 0,
        "currency": "EUR",
        "description": "string"
      }'
Attribute Description
amount[Integer, required] Minimum: 1 Maximum: 999999 Payment amount in Euro cents.
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 Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.


Payment Refund Service Response

The following parameters are included in the header and body of the Payment Refund Service response.


Response Header


Example Response:
HTTP/1.1 201 Created
{

  "refundId": "string",
  "paymentId": "string",
  "amount": 0,
  "currency": "EUR",
  "status": "PENDING",
  "description": "string",
  "creationDate": "2020-05-12T13:20:02.855Z"

}
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
refundId[String, required] Fixed length: 24 chars The unique Refund id. Note: The refund creation endpoint is idempotent, so the same request can be retried in case of timeout or network issue.
paymentId[String, required] Fixed length: 24 chars] The unique Payment id.
amount[Integer, required] Payment amount in Euro cents.
currency[String, optional] Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status[String::enum, required] Allowed values: PENDING The status of the Payment.
description[String, optional] Custom description of the Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.
creationDate[String, required] Format: YYYY-MM-ddTHH:mm:ss.SSSZ The creation date and time of the Payment.


Payment Refund Service HTTP Status and Error Codes

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

HTTP/1.1 400 Bad Request
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
400[Integer]

VALIDATION_ERROR - request validation failed
401[Integer]

UNAUTHORIZED - caller does not have valid authentication credentials.
403[Integer]

ACCESS_DENIED - operation not allowed, caller does not have required authorities.
404[Integer]

REFUND_NOT_FOUND - refund not found.
404[Integer]

PAYMENT_NOT_FOUND - payment not found.
500[Integer]

TECHNICAL_ERROR: Technical error in the Payment service.
503[Integer]

Service Unavailable


Refund creation failed for business reasons

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

HTTP/1.1 422 Bad Request
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
422[Integer] PAYMENT_FOR_REFUND_NOT_FOUND - payment not found.
422[Integer] INVALID_REFUND_AMOUNT - refund amount is too high.
422[Integer] REFUND_NOT_ALLOWED - refund is not allowed for the merchant.
422[Integer] REFUND_NOT_POSSIBLE - refund is not possible for this payment at the moment.
422[Integer] DEBTOR_IBAN_NOT_AVAILABLE - debtor iban not available yet, try again later.
Note: The IBAN for payments done via the Payconiq by Bancontact App is only available one or two days after the payment.
422[Integer] REFUND_REQUEST_CONFLICT - request id is already used by refund with different parameters.


Get Refund By ID

Endpoint to get refund details by id.

Type: REST

HTTP Verb: GET

EXT URL Definition: https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}

PROD URL Definition: https://api.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}


Payment Refund Service Request Header



curl -X GET
 https://api.ext.payconiq.com/v3/payments/{payment-id}/refunds/{refund-id}

 -H 'Signature: xxxxxxxx..xxxxxxxxxxxx'
Attribute Comment/ Format
Signature[String, required] Authorization field which contains the JWS. xxxxxxxx…xxxxxxxxxxxx
Content-type[String, required] application/json Content type of the data in the request body.


Payment Refund Service 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.
refund-id[Integer, required] Fixed length: 24 chars The unique identifier of a refund as provided by the payment refund service.


Payment Refund Service 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


Payment Refund Service Response Body

The following parameters are included in the body of the payment refund service.

Response Body

HTTP/1.1 200 OK
{
  "refundId": "string",
  "paymentId": "string",
  "amount": 0,
  "currency": "EUR",
  "status": "PENDING",
  "description": "string",
  "creationDate": "2020-05-12T14:45:14.323Z"
}
Attribute Description
refundId[String, required] Fixed length: 24 chars The unique Refund id. Note: The refund creation endpoint is idempotent, so the same request can be retried in case of timeout or network issue.
paymentId[String, required] Fixed length: 24 chars The unique Payment id.
amount[Integer, required] Payment amount in Euro cents.
currency[String, optional] Payment currency code in ISO 4217 format. Only Euros supported at the moment.
status[String::enum, required] Allowed values: PENDING, PROCESSING, REFUNDED, FAILED The status of the Payment.
description[String, optional] Custom description of the Refund. This will be shown to the consumers bank statement. Only the first 35 characters are used for the remittance information.
creationDate[String, required] Format: YYYY-MM-ddTHH:mm:ss.SSSZ The creation date and time of the Payment.


Refund Statuses

Status Name Status Description
PENDING Refund request accepted by Payconiq, will be processed soon.
PROCESSING Money was paid to consumer, but was not deducted from the merchant. Payconiq will try to collect the refund for 14 days after which the refund expires and manual collection process will take over.
REFUNDED Refund request successfully processed, and money was deducted from merchant and paid to consumer.
FAILED Refund request processing failed for technical reasons, money movement didn't happen.


Payment Refund Service Status and Error Codes

HTTP/1.1 422 Unprocessable Entity
{
  "code": "string",
  "message": "string"
}
Status Code Error Codes
400[Integer]

VALIDATION_ERROR - request validation failed.
401[Integer]

UNAUTHORIZED - caller does not have valid authentication credentials.
403[Integer]

ACCESS_DENIED - operation not allowed, caller does not have required authorities.
404[Integer]

REFUND_NOT_FOUND - refund not found.
404[Integer]

PAYMENT_NOT_FOUND - payment not found.
500[Integer]

TECHNICAL_ERROR:Technical error in the Payment service.
503[Integer]

Service Unavailable


Refund Remittance

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.



Unstructured Refund remittance:

Format of unstructured refund remittance information:

Payconiq RefundID refund for Creditor name Description ref Reference field


Field Name Description Format
Issuer The entity that facilitates Payconiq Payment. String
[Max Length: 8]
Delimiter Field separator. String: Space
[Max Length: 1]
RefundID A unique identifier representing a Payconiq Refund Transaction. String
[Max Length: 24]
Delimiter Field separator. String: Space
[Max Length: 1]
Creditor 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]
Description A description linked to a Payconiq Refund Transaction. Field is padded with spaces if the max length is not reached. String
[Max Length: 31]
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]		 
Sample Remittance Information


“Payconiq 61f1204b4d07487d6ac57842 refund for Cookie Shop             8zyeAIKOt54Ybc3yfnL5            ref 2633686194                        "


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

“Payconiq 61f1204b4d07487d6ac57842 refund for Cookie Shop             8zyeAIKOt54Ybc3yfnL5            ref 2633686194                          ”


Note: Structured remittance is not applicable for refund.


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.

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://

How long is a transaction/payment id valid for?

  • A transaction/payment id is valid for twenty (20) minutes for online and two (2) minutes for instore payments before it times out.

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.

How do voucher payments work?

Accept meal vouchers of Edenred, Monizze and Pluxee | Payconiq by Bancontact
Faqs | Payconiq by Bancontact

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

curl