Skip to content

    Charge payments

    This guide is for developers who want to charge and manage payments programmatically using the Payment API.

    Complexity: Medium
    Coding: Yes (Backend)
    Platform:

    Overview

    Whenever your customer buys something on your site, a new payment is created in Easy. New payments require your action:

    • When you ship the order, make sure to charge the payment in order to receive the funds from Nets.
    • If the order is canceled by the customer, make sure to cancel the payment in order to release the reservation on the customer's payment card.
    • If you have already charged your customer and need to compensate your customer for a returned order etc, you can refund the charge.

    Payments can be managed in Easy Portal or programmatically through the Payment API. The guide Manage payment describes how to use Easy Portal to manage payments while this guide shows you how to use the Payment API.

    Retrieve payment details

    The Payment API allows you to fetch details about a payment registered in Nets Easy.

    First, load your checkout page and go through the checkout flow so that a new payment is created in Easy. You will need the payment identifier in subsequent requests, so be sure to save the paymentId returned from the create payment method or collect the new payment identifier using webhooks with the [payment.created]((/nets-easy/LOCALE/api/webhooks#created) event.

    See the integration guide for more information about creating a new payment object.

    Once you have the new paymentId, you can query the Payment API for the payment details associated with the new payment:

    Retrieve payment details

    <?php
    
    $curl = curl_init();
    
    curl_setopt_array($curl, [
      CURLOPT_URL => "https://test.api.dibspayment.eu/v1/payments/<PAYMENT_ID>",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => [
        "Authorization: <YOUR_SECRET_API_KEY>"
      ],
    ]);
    
    $response = curl_exec($curl);
    $err = curl_error($curl);
    
    curl_close($curl);
    
    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }

    As always, remember to replace the text <YOUR_SECRET_API_KEY> and any other parameters within <...>. You can find your integration keys in Easy Portal.

    Cancel payment

    When a customer has completed the checkout flow and accepted the payment, the specified amount has been reserved (but not charged) on your customer's payment card.

    If a customer cancels an order before the goods are shipped, you have the possibility to cancel the payment. By canceling a payment, the reserved money will be released to the customer's payment card. To cancel a payment, call the method Cancel payment as demonstrated in the following example:

    It is not possible to cancel a payment that has been already charged. In case you have already charged a payment you need to do a refund. You can read more about refunds below.

    Cancel payment

    <?php
    
    $paymentId = "<PAYMENT_ID>";
    $payload = '{
      "amount": 180000
    }';
    
    $ch = curl_init('https://test.api.dibspayment.eu/v1/payments/' . $paymentId . '/cancels');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                         
            'Content-Type: application/json',
            'Accept: application/json',
            'Authorization: <YOUR_SECRET_API_KEY>'));                                                
    $result = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    $json_pretty = json_encode(json_decode($result), JSON_PRETTY_PRINT);
    echo("Status code: " . $http_code . "\n");
    echo $json_pretty;

    Rember to replace the amount in the payload so that it matches your payment.

    You can subscribe to the following webhook events to track cancel requests associated with a payment:

    It is not possible to cancel a payment that has been already charged. In case you have already charged a payment you need to do a refund. You can read more about charges and refunds in the following sections.

    Charge payment

    When you ship the order to your customer, make sure to charge the payment in order to receive the funds from Nets.

    A payment can be fully charged (default) or partially charged if needed. Note that it is not possible to charge an amount that exceeds the original order. The system will tell when you exceed the limit. Below is the server code to charge a payment:

    Charge payment

    <?php
    
    $secretKey = "<YOUR_SECRET_API_KEY>";
    $paymentId = "<YOUR_PAYMENT_ID>";
    
    $payload = file_get_contents('payload.json');
    assert(json_decode($payload) && json_last_error() == JSON_ERROR_NONE);
    
    $ch = curl_init('https://test.api.dibspayment.eu/v1/payments/' . $paymentId . '/charges');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                
            'Content-Type: application/json',
            'Accept: application/json',
            'Authorization: ' . $secretKey));                                   
    
    $result = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    echo("HTTP code: " . $http_code);
    $json_pretty = json_encode(json_decode($result), JSON_PRETTY_PRINT);
    echo $json_pretty;

    Enable safe retries by using an idempotency key when creating charges. Read more about retries and idempotency keys in the API reference.

    A full charge only requires you to specify the full amount to be charged, like this:

    Charge payment fully

    payload.json
    {
        "amount": 5500
    }

    If you instead want to do a partial charge, you need to specify the order items that you charge for. A partial charge is typically used when you only ship a subset of the items ordered, or if you decide to lower the price of the items. Regardless, you always need to specify a new order so that the registered order of the payment aligns with the charge.

    Charge payment partially

    payload.json
    {
        "amount": 2750,
        "orderItems": [
          {
            "reference": "Sneaky NE2816-82",
            "name": "Sneaky",
            "quantity": 1,
            "unit": "pcs",
            "unitPrice": 2500,
            "netTotalAmount": 2500,
            "grossTotalAmount": 2750
          }
        ]
    }

    You can subscribe to the following webhook events to track charges associated with a payment:

    Refund a charge

    If you need to refund a payment that has been charged, you can use the method Refund charge. It would be more correct to say that it is a specific charge that is being refunded, and therefore you always need a charge identifier when doing a refund. A charge can be fully refunded or partially refunded.

    A full refund only requires the amount to be specified. A partial refund requires a complete order specification. Here follows an example of a partial refund:

    Partial refund

    payload.json
    {
        "amount": 2750,
        "orderItems": [
          {
            "reference": "Sneaky NE2816-82",
            "name": "Sneaky",
            "quantity": 1,
            "unit": "pcs",
            "unitPrice": 2500,
            "netTotalAmount": 2500,
            "grossTotalAmount": 2750
          }
        ]
    }

    You can track the refund events using the webhook events named:

    After a refund has been initiated but still not completed or failed, the refund is in a pending state. It is possible to cancel a pending refund. A refund can be pending for a number of reasons, see the Manage payments guide for more information.