The Rabo Smart Pay (OmniKassa) API provides you with functionality to do online payments.

Starting the following dates, the following product name(s) have changed:

• October 11th, 2022 - Rabo OmniKassa to Rabo Smart Pay. On a technical level (endpoints, api-calls), this name change has no impact.
• October 4th, 2022 - Payment brand AfterPay to Riverty. For the time being, the company decided to use both names as a combination: Riverty/AfterPay. On a technical level (endpoints, api-calls), this name change has no impact.

Rabo Smart Pay offers you an all-in-one solution for receiving payments on your physical and online locations. It includes a dashboard that puts you in full control of Rabo Smart Pay and all its included products and payment brands.

Products:

• Rabo OnlineKassa
• Payment terminals
• Rabo PinBox
• Rabo SmartPin
• Retourpinnen
• Rabo PinTegoed
• Rabo Betaalverzoek Plus

Payment brands:

• Maestro
• V PAY
• iDEAL
• MasterCard
• Visa
• PayPal
• Riverty/AfterPay
• Sofort

Rabo Smart Pay offers several APIs, both for new and already active users.

Get started with Rabo Smart Pay

The Rabo Smart Pay (OmniKassa) API facilitates online payments initiated by a web shop.

Integrate

The API can be used independent of the programming language and platform. You can choose the best way to integrate your webshop to the Rabo Smart Pay API:

• For commonly used web shops (such as Magento, WooCommerce, etc) a plug-ins is available, which can be easily installed and configured without the need of coding.
• For the languages PHP, .NET, and Java, SDK's (software development kits) are available that use our API under the hood and takes away complexity from a programmer.

For more information on the plug-ins and SDK's, read our Rabo Smart Pay manual.

Before you begin

Make sure you have a working sandbox account in the Rabobank developer portal, read Get Started to set up an account. You also require a valid refresh token and a signing key, you can obtain these:

• If you are successfully registered with Rabo Smart Pay, you can copy these from the Rabo Smart Pay dashboard.
• If you are not developing for a specific merchant then contact our Support Team.

Switching from sandbox to live

After you have successfully integrated using the sandbox environment, you can make the switch to the live environment by:

1. Changing the base path of each call from /omnikassa-api-sandbox to /omnikassa-api.
2. Replacing the sandbox refresh token and signing key with the refresh token and signing key for the live environment.

Payment journey

A single payment consists of the following steps:

1. Your web shop makes a refresh call to the Rabo Smart Pay API to obtain an access token.

   If your previously obtained access token is valid then you can skip this step.

2. After receiving an access token, the web shop makes an order announce call to announce an order.
3. Your web shop then redirects the user to Rabo Smart Pay.
4. The user makes the payment. and is redirected back to the web shop.
5. Rabo Smart Pay API makes a notification call notifying the web shop of order status update.
6. Your web shop makes a status pull call to request the latest order status.

Refresh call

Your web shop must be authorized to initiate online payments, this is done using a refresh call.

Using a refresh token your webshop makes a refresh call to obtain an access token from Rabo Smart Pay.

After receiving, the access token is valid for limited time (number of hours). If the web shop no longer has a valid access token, a refresh token should be used to retrieve a new access token. Your web shop is expected to keep track of how long an access token is valid, and when a new access token should be retrieved.

You are required to cache the access token in a secure manner as long as it is valid.

Payment brands call

This call can be performed to get the available payment brands and their corresponding statuses.

Order announce call

You can use this call to initiate a payment by announcing an order. You should provide order details in the request.

Rabo Smart Pay API responds with a unique ID assigned to the order and a payment page URL to redirect the user. The user can then choose a payment brand and complete or cancel the payment and return to the web shop.

In the order announcement call it is possible to add a User-Agent and a partner reference. This can be done in the X-Api-User-Agent header. The User-Agent should follow the standard string format found here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent.

VAT calculation

If order lines are supplied with VAT information then you should ensure that the total order amount is consistent with the order lines. The order amount (including VAT) must be equal to the sum over all order items of the piece price (including VAT) multiplied by the quantity.

Depending on how this is calculated, rounding errors can occur resulting in differences. We therefore recommend to base the total VAT amount on the VAT of the piece price instead of the total order amount excluding VAT.

Example:

A piece price of an order item (excluding VAT) is € 12.98 and a VAT rate of 21% applies. The piece price including VAT equals € 12.98 + 21% = € 15.71 (rounded to 2 decimals). If a consumer orders 7 pieces, the order amount (including VAT) to be specified in the announcement equals 7 x € 15.71 = € 109.97.

Discounts

A discount can be provided by an order item in the order details with a negative amount and (if applicable) a negative tax amount.

Required fields per payment brand

Regardless of the payment brand, the current date/time, merchant order ID, order amount, and the return URL should be included in each order.

Depending on the payment method, additional information should be included in the order as specified in the table below:

If for a payment brand the mandatory additional information is missing, then the consumer cannot use this method to fulfil the payment request. If the payment brand was included in the order using the paymentBrand field then the announcement is refused by the Rabo Smart Pay API.

Customer returns to the web shop

When the customer returns to the web shop, additional parameters are added to the return URL containing information on the status of the order.

The URL parameters are specified in the table below:

Possible values for the order status:

• COMPLETED: The payment was successful.
• EXPIRED: The consumer has not paid within the stipulated time period.
• IN_PROGRESS: The payment has not yet been completed. This can occur as a result of a breakdown or delay in the hinterland of payment processing. This is a possible outcome of an iDEAL or credit card payment.
• CANCELLED: The consumer chose not to pay and cancelled the order.

To verify the integrity of the request it is highly recommended that the web shop verifies the signature using the HMAC-SHA512 cryptographic algorithm. This can be done by:

1. Constructing the payload by concatenating the values of the order_id and the status parameters in a comma-separated string, e.g.: order123,COMPLETED

   Make sure that the values are specified in this order without any spaces, otherwise the signature validation fails.

2. Next, initialize a HMAC-SHA512 computation by supplying the (secret) signing key.

   The signing key is supplied in a base64 encoded format and must be decoded to the corresponding byte sequence.

   Subsequently, the UTF-8 byte representation of the payload is presented to the HMAC-SHA512 to arrive at the signature in byte representation. To compare this with the expected value in the signature parameter of the return URL, it must be encoded to (lowercase) hexadecimal string.

   If the values are equal then the request to return to the web shop is authentic, otherwise the request should be rejected by the web shop.

Below are code examples in PHP, Java, and C# to further illustrate the signature computation:

PHP

$payload = 'order123,COMPLETED'; $signingKey = '<signing key as copied from Rabo Omnikassa DashboardIn the PHP, Java & C#, those thexts aren't changed? If that's easy to do, please do (and do it here as well), would look like: "$signingKey = '<signing key as copied from Rabo Smart Pay (OmniKassa) Dashboard>';">'; $signingKeyDecoded = base64_decode($signingKey); $signature = hash_hmac('sha512', $payload, $signingKeyDecoded);

Java

String payload = "order123,COMPLETED"; String signingKey = "<signing key as copied from Rabo Omnikassa DashboardSee above php>"; byte\[\] signingKeyDecoded = Base64.getDecoder().decode(signingKey); Mac macAlgorithm = Mac.getInstance("HmacSHA512"); Key secretKey = new SecretKeySpec(signingKeyDecoded , "HmacSHA512"); macAlgorithm.init(secretKey); byte\[\] result = macAlgorithm.doFinal(payload.getBytes(UTF_8)); String signature = Hex.encodeHexString(result);

C#

String payload = "order123,COMPLETED"; String signingKey = "<signing key as copied from Rabo Omnikassa DashboardSee abve php>"; byte\[\] signingKeyDecoded = Convert.FromBase64String(signingKey); string signature = ""; using (var hmacsha512 = new HMACSHA512(signingKeyDecoded)) { var stream = new MemoryStream(Encoding.UTF8.GetBytes(payload)); foreach (var b in hmacsha512.ComputeHash(stream)) { signature = signature + $"{b:x2}"; } }

Notification call

A notification is a message sent from Rabo Smart Pay API to the web shop announcing that one or more new orders are processed. This notification serves as an invitation for the web shop to retrieve the order statuses with a status pull call. The web shop is free to do this immediately (even before an answer has been given to the notification) or at a later time. If an order has been paid using Sofort, it is important to mention that two notifications are being sent to retrieve the order status: once when the transaction has status ACCEPTED and once when the transaction has status SUCCESS. In both cases the status of the order is set to COMPLETED, and the order details show the actual status of the transaction.

The notification contains a token that must be used in the status pull call, this token has a limited validity (minutes). If the web shop does not make a status update call, Rabo Smart Pay sends a new notification.

The notification is cryptographically signed by Rabo Smart Pay using the same approach as the return URL so that the web shop can verify its integrity.

It is highly recommended that your web shop verifies the signature before accepting the notification. If more than one signing key is active for the web shop, Rabo Smart Pay sends a separate notifications to the web shop, each signed with a different key. This is because Rabo Smart Pay does not have the knowledge on which key is actually used within the web shop. The web shop can carry out a successful verification of the signature with one signing key.

The body of the notification is a JSON object containing the following fields:

The signature of the notification message is calculated in a similar way as the signature of the return URL. The fields for the payload are used are in the following order:

• authentication
• expiry
• eventName
• poiId

For example:

eyJraWQiOiJOTyIsImFsZyI6IkVTMjU2In0.eyJubyMiOjEyMywibWtpZCI6NSwibm8kIjoibWVyY2hhbnQub3JkZXIuc3RhdHVzLmNoYW5nZWQiLCJjaWQiOiJhYmNkLTEyMzQiLCJleHAiOjE0ODg0NjQ1MDN9.MEUCIHtPFoKmXAc7JNQjj0U5rWpl0zR9RsQvgj_n-ckHBngHAiEAmbtgrxaiy4cS3BTHd0DJ8md3Rn7V13Nv35m5DurY1wI,2016-11-25T09:53:46.765+01:00,merchant.order.status.changed,123

The signature is then computed by applying HMAC-SHA512 with the base64 decoded signing key and the payload above decoded to a UTF-8 byte sequence. For code examples that demonstrate the use of HMAC-SHA512, check Customer returns to the web shop.

If the computed signature is equal to the signature in the notification then the notification can be trusted and further processed, otherwise the notification should be rejected by the web shop.

On successful receipt of the notification, Rabo Smart Pay expects a HTTP status code 200 in return. If another status code is sent in response to the notification, Rabo Smart Pay assumes that the notification could not be processed and does not try to send the notification again until a new order is processed.

Status pull call

With this call, your web shop retrieves the final statuses for the newly processed order(s) using a token in the authentication field of the notification message.

The response of this call is cryptographically signed by Rabo Smart Pay using the same approach as the return URL so that the web shop can verify the integrity.

For example, consider the following response:

{ "signature": "99ca2487243fbad72bbaa456a3219db7b0d2a19777f436cedb3c045e999b86c05001bb0837b43caa3d1757321d00959ac2a161f473a103af72bf440db5147b4a", "moreOrderResultsAvailable": false, "orderResults": \[ { "merchantOrderId": "order00001", "omnikassaOrderId": "1d0a95f4-2589-439b-9562-c50aa19f9caf", "poiId": "2004", "orderStatus": "CANCELLED", "orderStatusDateTime": "2016-11-25T13:20:03.157+01:00", "errorCode": "", "paidAmount": { "currency": "EUR", "amount": "0" }, "totalAmount": { "currency": "EUR", "amount": "4999" } }, { "merchantOrderId": "order00002", "omnikassaOrderId": "5a89e364-9800-11e9-bc42-526af7764f64", "poiId": "2004", "orderStatus": "COMPLETED", "orderStatusDateTime": "2016-11-25T13:20:45.654+01:00", "errorCode": "", "paidAmount": { "currency": "EUR", "amount": "8999" }, "totalAmount": { "currency": "EUR", "amount": "8999" }, "transactions" : \[{ "id" : "1", "paymentBrand" : "IDEAL", "type" : "PAYMENT", "status" : "SUCCESS", "amount" : { "currency" : "EUR", "amount" : "100" }, "confirmedAmount" : { "currency" : "EUR", "amount" : "100" }, "startTime" : "2016-07-28T12:51:15.574+01:00", "lastUpdateTime" : "2016-07-28T12:51:15.574+01:00" }, { "id" : "2", "paymentBrand" : "IDEAL", "type" : "PAYMENT", "status" : "SUCCESS", "amount" : { "currency" : "EUR", "amount" : "200" }, "confirmedAmount" : { "currency" : "EUR", "amount" : "200" }, "startTime" : "2016-07-28T12:51:15.574+01:00", "lastUpdateTime" : "2016-07-28T12:51:15.574+01:00" } ] } ] }

To verify the signature, the payload is constructed by concatenating the fields into a comma-separated string in the following order:

• moreOrderResultsAvailable
• orderResults

where each element of orderResult is expanded to a comma-separated string in the following order:

• merchantOrderId
• omnikassaOrderId
• poiId
• orderStatus
• orderStatusDateTime
• errorCode
• paidAmount currency
• paidAmount amount
• totalAmount currency
• totalAmount amount

followed by a list of transactions, each in order:

• id
• paymentBrand
• type
• status
• amount currency
• amount amount
• confirmedAmount currency
• confirmedAmount amount
• startTime
• lastUpdateTime

Below are some examples of the payload for a completed and cancelled order:

Successful order and transaction

false,order00002,5a89e364-9800-11e9-bc42-526af7764f64,2004,COMPLETED,2016-11-25T13:20:45.654+01:00,,EUR,100,EUR,100,1,IDEAL,PAYMENT,SUCCESS,EUR,100,EUR,100,2016-07-28T12:51:15.574+01:00,2016-07-28T12:51:15.574+01:00,2,IDEAL,PAYMENT,SUCCESS,EUR,200,EUR,200,2016-07-28T12:51:15.574+02:00,2016-07-28T12:51:15.574+02:00

Cancelled order and transaction

false,order00003,5a89e364-9800-11e9-bc42-526af7764f65,2004,CANCELLED,2016-11-25T13:20:45.654+01:00,,EUR,0,EUR,100,1,IDEAL,PAYMENT,CANCELLED,EUR,100,,,2016-07-28T12:51:15.574+01:00,2016-07-28T12:51:15.574+01:00,2,IDEAL,PAYMENT,CANCELLED,EUR,200,,,2016-07-28T12:51:15.574+02:00,2016-07-28T12:51:15.574+02:00

The signature is then computed by applying HMAC-SHA512 with the base64 decoded signing key. The payload above is decoded to a UTF-8 byte sequence. 

If the computed signature equals the value of the signature field, then the response is authentic and further processing can continue, if not then the response should be rejected.

For code examples that demonstrate the use of HMAC-SHA512, check Customer returns to the web shop.

Like mentioned before, in case of a Sofort payment, two notifications are being sent. When the web shop makes the status update call, it will always receive the latest information. This means that the transaction status might be already updated to SUCCESS when the merchant makes the first status update call.

Refund API

After a transaction is successful, it is possible to initiate a refund. The refund API exposes the same functionality for refunds as the Rabo Smart Pay dashboard. For more functional documentation about refunds see the Rabo Smart Pay manual.

The Refund API contains three endpoints for:

• Initiating a refund
• Retrieving details such as the status of a refund.
• Retrieving the refundable amount of a transaction.

Additionally, the webhook mechanism now also exposes a transaction ID. This transaction ID must be used to initiate or request the status of a refund.

For more details about the endpoints, see the Rabo Smart Pay Online Payment API documentation.

Refund on the sandbox environment

On the sandbox environment, it is possible to simulate different scenarios based on the refund amount provided when initiating a refund. Additionally, setting a specific transaction ID or refund ID can also trigger one of the following scenarios.

Initiate refund request

Amounts:

• Amount equal or below 50 euro: successful refund creation
• Amount above 50 euro: MAXIMUM_REFUNDABLE_AMOUNT_EXCEEDED

Transaction ID:

• 6a07e870-8b11-11ec-a6a1-a7d4188ce7f8: UNKNOWN API EXCEPTION
• 83d4788c-8b1a-11ec-a720-074492bc17bb: NON EXISTING TRANSACTION

Any other transaction ID triggers a successful refund.

Retrieve refund details

Depending on the amount of the initiate refund request, we simulate different behaviours when the status of the refund is requested:

• The default is to simulate a successful refund.
• When the amount is 4,00 euro then we simulate a pending refund.
• When the amount is 5,00 euro then we simulate a failed refund.
• When the amount is 6,00 euro then we simulate an unknown status.

Refund ID:

• 4762858c-8b11-11ec-92d1-0fb764705fe6: REFUND NOT FOUND EXCEPTION

Any other refund ID triggers one of the scenarios described above, depending on the amount.

Transaction ID:

• 6a07e870-8b11-11ec-a6a1-a7d4188ce7f8: UNKNOWN API EXCEPTION
• 83d4788c-8b1a-11ec-a720-074492bc17bb: NON EXISTING REFUND

Any other transaction ID triggers one of the scenarios described above.

Retrieve refundable details

The following transaction IDs can be used to retrieve a refundable details response:

• 6a07e870-8b11-11ec-a6a1-a7d4188ce7f8: UNKNOWN API EXCEPTION
• 83d4788c-8b1a-11ec-a720-074492bc17bb: NON EXISTING REFUND

Any other transaction ID returns a refundable amount of 50,00 euro.