General

Payconiq is an all-in-one app enabling consumers from Belgium, Germany and the Netherlands to make direct payments online. It makes it easy for consumers and merchants to send and receive payments by supporting all payment methods in a single app - online, in-store and peer-to-peer. The app makes a direct connection with the customer’s payment account at one of the participating banks.

There are three ways to offer Payconiq to your customer:

1. Payconiq selection + QR code in the Buckaroo checkout

In this situation, the payment method selection will be done in the Buckaroo checkout page. After selecting Payconiq, Buckaroo will display the QR code to the customer. The Payconiq service can be left out in the API call to Buckaroo. Instead, provide the basic parameter "ContinueOnIncomplete" with value "RedirectToHTML" in the request. This way a redirect URL will be returned in the response, that leads the customer to the Buckaroo checkout.

2. Payconiq selection on webshop checkout and QR code on Buckaroo checkout

Here the Payconiq payment option is already selected in the webshop checkout. After confirmation the customer will be redirected to the Buckaroo page where the QR code is displayed immediately. To do this, perform the "Pay" call. In the response, redirect the customer to the RedirectURL under "RequiredAction".

3. Payconiq selection + QR code on webshop checkout (Client SDK needed)

This option provides the best customer experience. Here the payment option is selected in the webshop checkout, after which the QR code will be displayed in the webshop as well. This way the customer will not have to be redirected to the external Buckaroo checkout page for the QR code. In order to implement this, the ClientSDK is needed. More information can be found in the SDK section.

Mobile payments

To optimize the payment experience for mobile users, it is recommended to redirect them directly to a specific URL rather than the Buckaroo checkout URL or the SDK. This will avoid an unnecessary step/redirect for the customer. First off, identify the customers’ device. If it’s a mobile android device, redirect the customer to the “PayconiqAndroidUrl” found in the Buckaroo response. If it’s a mobile iOS device, redirect the customer to the “PayconiqIosUrl”. For any other device, redirect the customer to the “PayconiqUrl”.

Please note: it is not required to do this, as both the Buckaroo checkout and the Client SDK can handle mobile users, but we strongly advise you to take this into consideration.

Buckaroo checkout page

The Payconiq QR code on the Buckaroo checkout page is by default displayed with a pink coloured background. However, if the checkout page has been personalized (with a modified stylesheet), it is most likely that the pink background isn't showing. In this case you can add the following code to your stylesheet:

/* Payconiq specifics */
#payconiqQrWrapper {
    background: #ca0066;
    margin: 0 -20px -30px;
    padding: 10px 0 20px; 
    color: #fff;
}

@media only screen and (max-width: 480px) {
    /* Payconiq specifics */
    #payconiqQrWrapper {
         margin: 0 -6px -30px -14px;
    }
}

Recurring payments

It is also possible to use a Payconiq transaction as a reference transaction for recurring SEPA Direct Debit transactions. To do this, add the basic parameter "StartRecurrent" with value "True" to your Payconiq API request. Once successful, you can perform a recurring SEPA direct debit transaction. Please see the SEPA Direct Debit section for an explanation of the "PayRecurrent" request.

Testing

Payconiq supports a complete testflow. However, if you wish to perform test transactions, you will need the test app from Payconiq instead of their regular app. To install this app, please open the following url on your phone. You will be required to sign up by entering your email address and a link will be sent to you to download the app.

iOS: https://betas.to/CzggCAq4

Android: https://betas.to/k9XmeUUG

After installing, you will have to do the following at the very least:

  1. Trust the app – you can do this via the settings on your mobile phone.
  2. While setting up, if you do not receive the verification SMS for EXT, you can always use 99999 on EXT. This is the default code.

Pay

The Pay action is the default action for the service Payconiq. With this action a new transaction will be initiated via Payconiq.

In case of a correct request a pending response will follow with the transaction status “791 Pending Processing”. The response will contain some details about the transaction.

When using the Buckaroo Client SDK all you need to proceed is the SDK itself and the transactionKey. See below under “Example Client SDK implementation” for an example of how to use the Client SDK within you website / webshop.

View in playground

Request


JSON gateway request

There are no service specific parameters for this request.

Description

A description for the transaction, visible to the consumer in the Payconiq app. Please note: This is a basic parameter (optional), not a service specific parameter.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10,
   "Invoice": "testinvoice123",
   "Description": "Payment for testinvoice123",
   "Services": {
      "ServiceList": [
         {
            "Name": "payconiq",
            "Action": "Pay"
         }
      ]
   }
}

Response


JSON gateway response

QrUrl

A URL pointing to a PNG of the QR code that can be scanned with the Payconiq app. Only useful for a custom QR implementation.

PayconiqUrl

Redirect mobile users to this URL if the operating system is not iOS or Android.

PayconiqIosUrl

Redirect mobile iOS users to this URL.

PayconiqAndroidUrl

Redirect mobile Android users to this URL.

TransactionId

This is the Payconiq transaction ID.

JSON

copy
{
   "Key": "899402E3B0854F698F6FB627A00Cxxxx",
   "Status": {
      "Code": {
         "Code": 791,
         "Description": "Pending processing"
      },
      "SubCode": {
         "Code": "S002",
         "Description": "An additional action is required: Redirect to Buckaroo"
      },
      "DateTime": "2018-06-27T10:24:05"
   },
   "RequiredAction": {
      "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=FE3BD28B5875494BBDD31FFB86E2xxxx",
      "RequestedInformation": null,
      "PayRemainderDetails": null,
      "Name": "Redirect",
      "TypeDeprecated": 0
   },
   "Services": [
      {
         "Name": "Payconiq",
         "Action": null,
         "Parameters": [
            {
               "Name": "QrUrl",
               "Value": "https://static.buckaroo.nl/qr/v1/aHR0cHM6Ly9wYXljb25pcS5jb20vcGF5LzEvNWIzMzQ5YTU1MjI1ZmIxNTBmMjdlxxxx"
            },
            {
               "Name": "PayconiqUrl",
               "Value": "https://payconiq.com/pay/1/5b3349a55225fb150f27ebfa?returnUrl=https%3a%2f%2ftestcheckout.buckaroo.nl%2fhtml%2fsslreturnpage.aspx%3fbrq_payment%3dC4E20544AF0843849D948D000xxxx2"
            },
            {
               "Name": "PayconiqIosUrl",
               "Value": "payconiq.ext://payconiq.com/pay/1/5b3349a55225fb150f27ebfa?returnUrl=https%3a%2f%2ftestcheckout.buckaroo.nl%2fhtml%2fsslreturnpage.aspx%3fbrq_payment%3dC4E20544AF0843849D948D00xxxx5A2"
            },
            {
               "Name": "PayconiqAndroidUrl",
               "Value": "intent://payconiq.com/pay/1/5b3349a55225fb150f27ebfa?returnUrl=https%3a%2f%2ftestcheckout.buckaroo.nl%2fhtml%2fsslreturnpage.aspx%3fbrq_payment%3dC4E20544AF0843849D948D0xxxx835A2#Intent;scheme=payconiq;package=com.payconiq.customers.external;end"
            },
            {
               "Name": "TransactionId",
               "Value": "5b3349a55225fb150f27xxxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice123",
   "ServiceCode": "Payconiq",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "C096",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "C4E20544AF0843849D948D00028xxxxx"
}

Client SDK implementation

After you initiated a server side Pay request you can initiate the payment on the client side. You will need to initiate the Client SDK with two parameters:

1. Container selector: Use the query selector format for selecting a DOM element.

2. Transaction key: Insert the transaction key from the server side Pay response. You can find the value in the “Key” field of the JSON response.

When initiated the Client SDK will render a minimal “widget” inside the container element of your choice. The script will render a QR code and listen for status updates. In case the consumer is using a mobile device the script will redirect the consumer directly to the Payconiq app to complete the payment.

After the payment is completed, cancelled or failed the consumer will be redirected (by the SDK) to the ReturnUrl.

Include the ClientSDK like this in the bottom of the BODY element of your page. Like this:

<script src="https://checkout.buckaroo.nl/api/buckaroosdk/script"></script>

Note: The only dependency of the Buckaroo Client SDK is jQuery 1.9+

Script example:

$(document).ready(function() { BuckarooSdk.Payconiq.initiate("#payconiqQr", "94EDDFBCFF774714AEDE0F9346XXXX"); });

Refund

To refund a successfully performed Payconiq transaction, use the action Refund. A bank transfer is then initiated which transfers the amount of the original transaction to the consumer.

View in playground

Request


JSON gateway request

OriginalTransactionKey
Required

Transaction key of the original transaction that needs to be refunded. Please note: This is a basic parameter, not a service specific parameter. This value is a 32-character hex string.

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1,
   "Invoice": "testinvoice 123",
   "OriginalTransactionKey": "4E8BD922192746C3918BF4077CXXXXXX",
   "Services": {
      "ServiceList": [
         {
            "Name": "Payconiq",
            "Action": "Refund"
         }
      ]
   }
}

Response


JSON gateway response

customeraccountname

The beneficiary of the bank account from which the payment was made.

CustomerIBAN

The international bank account number (iban code) of the bank of the consumer. Please note: This field is optional. In some countries, banks are not allowed to provide this information to third parties.

JSON

copy
{
   "Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S990",
         "Description": "De verwerking is geslaagd."
      },
      "DateTime": "2017-03-31T09:03:45"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "Payconiq",
         "Action": null,
         "Parameters": [
            {
               "Name": "customeraccountname",
               "Value": "J. de Tèster"
            },
            {
               "Name": "CustomerIBAN",
               "Value": "NL44RABO0123456789"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "Payconiq",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1,
   "TransactionType": "C097",
   "MutationType": 1,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "4E8BD922192746C3918BF4077CXXXXXX"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "J. de Tèster",
   "PayerHash": null,
   "PaymentKey": "AE8B6E18A2684846AAAF06A63FXXXXXX"
}