Skip to Main Content
Riverty Docs
    • Get Started
    • Login
    riverty logo Docs

    PHP - SOAP to RESTful

    Introduction

    All Dutch and Belgian Riverty connections need to upgrade from Riverty’s old SOAP API to the new RESTful Checkout API before August 1, 2024. This is also applicable for all old PHP-library connected clients whom are still utilizing the old SOAP-connection. Failure to update the RESTful connection will result in the rejection of all incoming orders starting on August 1, 2024.

    The Benefits of the RESTful Checkout API

    1. Faster response times improve your customers' shopping experience
    2. No more need to ask 'gender,' so 1 less step at the checkout
    3. Images of the products in your online shop become visible in the Riverty app and the MyRiverty web portal
    4. Supported new products, such as Pay-In-3, available only via RESTful Checkout API.
    5. Riverty’s Strong Customer Authentication solution is only available via RESTful API
    6. The RESTful Checkout API expands available markets to the Netherlands, Belgium, Germany, Austria, Switzerland, Norway, Finland, Sweden and Denmark
    7. The RESTful Checkout API reliable connection in use since 2016

    Support

    In case you require assistance at any point in the process, please reach out to support@riverty.com.

    7 Steps to Upgrade from SOAP to RESTful API

    Group 21671.png

    Step 1: Confirm PHP-Library Version (version 4.4.0)

    Validation Instructions

    1. To validate the PHP Library version, utilize Composer. To check the version of the module, execute the command:
    composer show payintegrator/afterpay

    1. We recommend using the PHP Library version 4.4.0. If your current version is older or lower than 4.4.0, please update to this latest version before proceeding.

    2. For updating the PHP Library, use Composer.

    Composer Instructions

    Include the package in your composer.json file

    {
    "require": {
        "payintegrator/afterpay": "^4.4.0"
    }
}

    Run composer update and load the composer autoloader:

    <?php
require 'vendor/autoload.php';
// ...

    Step 2: Retrieve Your Shop’s TEST API Key(s)

    The legacy SOAP connection utilizes a username, consisting of a Merchant ID and Portfolio ID, along with a password. This method is replaced by a REST connection, which requires an API Key for authentication. You can locate your TEST API Key on our Test Merchant Portal.

    NOTE: API Keys are specific to each country, payment method, and webshop. For instance, if you provide a 14-day invoice option in both the Netherlands and Belgium, you will need to obtain and utilize two distinct API Keys. Ensure to repeat the retrieval steps for each unique combination.

    Group 20079 (10).png

    1. Open the left menu
    2. Choose Developer Info in the left menu
    3. Show your TEST API Key (This is only visible to Merchant Portal users with rights 'Administrator')

    In case you require assistance at any point in the process, please reach out to support@riverty.com.

    Step 3: Enable PHP-Library RESTful Order-Flow

    Important Note: Steps 3 & 4 must be completed for each country, payment method, and webshop. For instance, if you provide a 14-day invoice option in both the Netherlands and Belgium, you will need to acquire and use two distinct API keys. Ensure to repeat the retrieval steps for each unique combination.
    Ensure that the command for creating an 'Empty Object' is modified to begin using the RESTful Order-flow.

    To create an empty object, you may use the following example:

    $riverty = new \Afterpay\Afterpay();
$riverty->setRest();

    The newly created RESTful object will store your order information and facilitate sending the order to the Riverty REST-API.

    Step 4: Required Configuration Changes

    1. Enter Your TEST API Key: Obtain your TEST API Key from the TEST Merchant Portal and incorporate it into your PHP integration as follows:
    $authorisation['apiKey'] = '';
    • For testing purposes, you have to use your Test API Key from the TEST Merchant Portal, as mentioned previously. To do so, set the mode to test by adjusting the following variable. For production(Step 7), change this to 'live':
    $modus = 'test'; // for production set to 'live'

    1. Adjust Order Line Details: It's necessary to update the below Pricing/Amount and Product/Image-URL fields for each item or product line within your order to align with the REST flow.
      The fields requiring adjustments include:

      • $grossUnitPrice
      • $vatAmount
      • productUrl
      • $imageUrl

    2. Utilize the $riverty->create_order_line function to define the specifications for each order line. An example of specifying an order line for a product is provided below.

    $sku = 'PRODUCT-001';
$name = 'Product name 1';
$qty = 3;
$grossUnitPrice = 2000; // in cents, including TAX (for discounts, use a negative number)
$vatAmount = 347; //in cents
$productUrl = "https://www.riverty.com/products/brown_wool_hat.jpg";
$imageUrl = "https://www.riverty.com/images/brown_wool_hat.jpg";
$riverty->create_order_line( $sku, $name, $qty, $grossUnitPrice, null, $vatAmount, null, null, $productUrl, $imageUrl );

    Step 5: Test the RESTful Connection

    To ensure the changes made in steps 3 and 4 are correctly implemented, we recommend placing several test orders for each payment method.

    Each test order should ideally include:

    • Multiple products
    • A discount (if applicable)
    • Shipping fees (if applicable)
    • An alternate delivery address

    For example customer test data that can be used in these tests, please visit the following information page: Test Consumer Data

    Step 6: Retrieve Your Shop’s Live/Production API Key(s)

    Access your Live/Production API Key(s) through our Merchant Portal.

    NOTE: API Keys are specific to each country, payment method, and webshop. For instance, if you provide a 14-day invoice option in both the Netherlands and Belgium, you will need to obtain and use two distinct API Keys. Ensure to follow these steps for each unique setup.

    Group 20079 (11).png

    1. Open the left menu on the Merchant Portal.
    2. Choose Developer Info from the menu options(left).
    3. Your TEST API Key will be displayed here. Note that this information is only visible to Merchant Portal users with 'Administrator' rights.

    In case you require assistance at any point in the process, please reach out to support@riverty.com.

    Step 7: Enable & validate LIVE(Production) Connection

    1. Enter Your Production API Key: Insert your Production API Key obtained from the Merchant Portal into your PHP library
      $authorisation['apiKey'] = '';

    2. Switch to Live Mode: Change the operation mode to live by adjusting the following variable. For testing purposes, this should be set to 'test': $modus = 'live'; // for test set to 'test'

    3. Testing the Connection: Now, with Riverty activated in live mode, the next step is to ensure that orders are processed correctly. Test this by attempting to place an order that should be rejected:

      • STEP 1: Navigate to the webshop, select a product, and add it to the shopping cart.
      • STEP 2: Proceed to checkout and enter the required details. For the email address, use rejection@riverty.com.
      • STEP 3: Select Riverty as the payment method and complete the order process.

    Expected Result: The order should be rejected. If the order is not rejected and you encounter a technical or authorization error instead, please contact support@riverty.com for assistance.

    Important: Repeat the specified steps for each webshop, country, and payment method type.