Skip to content

    Payment API

    The Easy Payment API provides methods for managing one-time payments and subscriptions (recurring payments).

    Payment objects are the main entities that the Easy platform centers around. Whenever a customer initiates either a one-time purchase or a subscription, a new payment object is created. See the Create payment method for more details.

    A payment object is always associated with the following entities:

    • Merchant - the webshop that sells products. You provide the merchant identity by using the integration keys associated with your merchant account. Or, if you are a Nets partner and use the keys belonging to a partner account, you can provide an optional merchantNumber to identify the merchant.
    • Customer - a private or a business consumer that places the order. Nets Easy enables customers to collect customer data if the customer's consent is obtained. This data makes future purchases easier. Nets Easy collects customer data directly from the customer. However, it is also possible for you to provide customer data that will initiate consumer information for the payment.
    • Order - defines what the customer will be charged for. The order is always provided by you when creating a payment object and can later be updated during the checkout using the update order method.

    A payment object also contains information about the checkout, such as shipping options, payment methods, and currencies.

    You can track the status changes of a payment by using webhooks. The events that can be subscribed to roughly correspond to the different states you can find in the payment section in Easy Portal. If you are new to Easy, we recommend spending some time in the Easy Portal to familiarize yourself with the platform and what to expect from the API.

    Scroll down for code samples, example requests and responses.
    Select a language for code samples from the tabs or the mobile navigation menu.

    Payments

    The methods listed under this section handle a single payment object. Create a new payment object whenever your customer places a new order. This will reserve the amount specified in the order. The payment object can be updated during the checkout using the methods: Update reference information and Update order.

    When you ship the order, you should charge the payment. And if you need, the API also allows you to cancel a payment or refund a customer.

    Create payment

    POST /v1/payments

    Initializes a new payment object that becomes the object used throughout the checkout flow for a particular customer and order. Creating a payment object is the first step when you intend to accept a payment from your customer. Typically you provide the following information:

    • The order details including order items, total amount, and currency.
    • Checkout page settings, which specify what type of integration you want: a checkout page embedded on your site or a pre-built checkout page hosted by Nets. You can also specify data about your customer so that your customer only needs to provide payment details on the checkout page.

    Optionally, you can also provide information regarding:
    • Notifications if you want to be notified through webhooks when the status of the payment changes.
    • Fees added when using payment methods such as invoice.

    On success, this method returns a paymentId that can be used in subsequent requests to refer to the newly created payment object. Optionally, the response object will also contain a hostedPaymentPageUrl, which is the URL you should redirect to if using a hosted pre-built checkout page.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Create payment

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • orderobjectrequired

      Specifies an order associated with a payment. An order must contain at least one order item. The amount of the order must match the sum of the specified order items.

      • itemsarrayrequired

        A list of order items. At least one item must be specified.

        • referencestringrequired

          A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

        • namestringrequired

          The name of the product.

        • quantitynumber (double)required

          The quantity of the product.

        • unitstringrequired

          The defined unit of measurement for the product, for example pcs, liters, or kg.

        • unitPriceinteger (int32)required

          The price per unit excluding VAT.

        • taxRateinteger (int32)optional

          The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

        • taxAmountinteger (int32)optional

          The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

        • grossTotalAmountinteger (int32)required

          The total amount including VAT (netTotalAmount + taxAmount).

        • netTotalAmountinteger (int32)required

          The total amount excluding VAT (unitPrice * quantity).

      • amountinteger (int32)required

        The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.)

      • currencystringrequired

        The currency of the payment, for example 'SEK'.

      • referencestringoptional

        A reference to recognize this order. Usually a number sequence (order number).

    • checkoutobjectrequired

      Defines the behavior and style of the checkout page.

      • urlstringoptional

        Specifies where the checkout will be loaded if using an embedded checkout page. See also the integrationType property.

      • integrationTypestringoptional

        Determines whether the checkout should be embedded in your webshop or if the checkout should be hosted by Nets on a separate page. Valid values are: 'EmbeddedCheckout' (default) or 'HostedPaymentPage'. Please note that the string values are case sensitive.If set to 'HostedPaymentPage', your website should redirect the customer to the hostedPaymentPageUrl provided in the response body. Using a hosted checkout page requires that you specify the returnUrl property.If set to 'EmbeddedCheckout', the checkout page will be embedded within an iframe on your website using the Checkout JS SDK. Using an embedded checkout page requires that you also specify the url property.

      • returnUrlstringoptional

        Specifies where your customer will return after a completed payment when using a hosted checkout page. See also the integrationType property.

      • cancelUrlstringoptional

        Specifies where your customer will return after a canceled payment when using a hosted checkout page. See also the integrationType property.

      • consumerobjectoptional

        Contains information about the customer. If provided, this information will be used for initating the consumer data of the payment object. See also the property merchantHandlesConsumerData which controls what fields to show on the checkout page.

        • referencestringoptional
        • emailstringoptional

          The email address.

        • shippingAddressobjectoptional

          The address of a customer (private or business).

          • addressLine1stringoptional

            The primary address line.

          • addressLine2stringoptional

            An additional address line.

          • postalCodestringoptional

            The postal code.

          • citystringoptional

            The city.

          • countrystringoptional

            A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported languages.

        • phoneNumberobjectoptional

          An international phone number.

          • prefixstringoptional

            The country calling code, for example 001.

          • numberstringoptional

            The phone number (without the country code prefix).

        • privatePersonobjectoptional

          The name of a natural person.

          • firstNamestringoptional

            The first name (also known as given name).

          • lastNamestringoptional

            The last name (also known as surname/family name).

        • companyobjectoptional

          A business consumer.

          • namestringoptional

            The name of the company.

          • contactobjectoptional

            The name of a natural person.

            • firstNamestringoptional

              The first name (also known as given name).

            • lastNamestringoptional

              The last name (also known as surname/family name).

      • termsUrlstringrequired

        The URL to the terms and conditions of your webshop.

      • merchantTermsUrlstringoptional

        The URL to the privacy and cookie settings of your webshop.

      • shippingCountriesarrayoptional

        An array of countries that limits the set of countries available for shipping. If left unspecified, all countries supported by Easy Checkout will be available for shipping on the checkout page.

      • shippingobjectoptional
        • countriesarrayoptional
        • merchantHandlesShippingCostbooleanoptional

          If set to true, the payment order is required to be updated (using the Update order method) with shipping.costSpecified set to true before the customer can complete a purchase. Defaults to false if not specified.

        • enableBillingAddressbooleanoptional

          If set to true, the customer is provided an option to specify separate addresses for billing and shipping on the checkout page. If set to false, the billing address is used as the shipping address.

      • consumerTypeobjectoptional

        Configures which consumer types should be accepted. Defaults to 'B2C'.These options are ignore if the property merchantHandlesConsumerData is set to true.

        • defaultstringoptional

          The checkout form defaults to this consumer type when first loaded.

        • supportedTypesarrayoptional

          The array of consumer types that should be supported on the checkout page. Allowed values are: 'B2B' and 'B2C'.

      • chargebooleanoptional

        If set to true, the transaction will be charged automatically after the reservation has been accepted. Default value is false if not specified.

      • publicDevicebooleanoptional

        If set to true, the checkout will not load any user data, and also the checkout will not remember the current consumer on this device. Default value is false if not specified.

      • merchantHandlesConsumerDatabooleanoptional

        Allows you to initiate the checkout with customer data so that your customer only need to provide payment details. If set to true, you also need to specify a consumer object (either a privatePerson or a company, not both).

      • appearanceobjectoptional

        Defines the appearance of the checkout page.

        • displayOptionsobjectoptional

          Controls what is displayed on the checkout page.

          • showMerchantNamebooleanoptional

            If set to true, displays the merchant name above the checkout. Default value is true when using a HostedPaymentPage.

          • showOrderSummarybooleanoptional

            If set to true, displays the order summary above the checkout. Default value is true when using a HostedPaymentPage.

        • textOptionsobjectoptional

          Controls what text is displayed on the checkout page.

          • completePaymentButtonTextstringoptional

            Overrides payment button text. The following predefined values are allowed: pay, purchase, order, book, reserve, signup, subscribe, accept. The payment button text is localized.

      • countryCodestringoptional

        Merchant's three-letter checkout country code (ISO 3166-1), for example GBR. See also the list of supported languages.

    • merchantNumberstringoptional

      The merchant number. Use this header only if you are a Nets partner and initiating the checkout with your partner keys. If you are using the integration keys for your webshop, there is no need to specify this header.

    • notificationsobjectoptional

      Notifications allow you to subscribe to status updates for a payment.

      • webHooksarrayoptional

        The list of webhooks. The maximum number of webhooks is 32.

        • eventNamestringoptional

          The name of the event you want to subscribe to. See webhooks for the complete list of events.

        • urlstringoptional

          The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.

        • authorizationstringoptional

          The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.

    • subscriptionobjectoptional

      Defines the duration and interval when creating or updating a subscription.

      • subscriptionIdstring (uuid)optional

        The identifier of the subscription to be updated. If omitted, a new subscription will be created.

      • endDatestring (date-time)optional

        The date and time when the subscription expires. It is not possible to charge this subscription after this date. The field has three components: date, time, and time zone (offset from GMT). For example: 2021-07-02T12:00:00.0000+02:00

      • intervalinteger (int32)optional

        Defines the minimum number of days between each recurring charge. This interval commences from either the day the subscription was created or the most recent subscription charge, whichever is later. An interval value of 0 means that there are no payment interval restrictions.

    • unscheduledSubscriptionobjectoptional

      Defines the payment as one that should initiate or update an unscheduled card on file agreement

      • createbooleanoptional

        A flag indicating if a new unscheduled card on file agreement should be created. Can be omitted when updating an existing unscheduled card on file agreement.

      • unscheduledSubscriptionIdstring (uuid)optional

        The identifier of the unscheduled card on file agreement to be updated. If omitted, a new unscheduled card on file agreement will be created.

    • paymentMethodsConfigurationarrayoptional

      Specifies payment methods configuration to be used for this payment, ignored if empty or null.

      • namestringoptional

        The name of the payment method or payment type to be configured, if the specified payment method is not configured correctly in the merchant configurations then this won't take effect. Payment type cannot be specified alongside payment methods that belong to it, if it happens the request will fail with an error. Possible payment methods values: "Visa", "MasterCard", "Dankort", "AmericanExpress", "PayPal", "Vipps", "MobilePay", "Swish", "Arvato", "EasyInvoice", "EasyInstallment", "EasyCampaign", "RatePayInvoice", "RatePayInstallment", "RatePaySepa", "Sofort", "Trustly". Possible payment types values: "Card", "Invoice", "Installment", "A2A", "Wallet".

      • enabledbooleanoptional

        Indicates that the specified payment method/type is allowed to be used for this payment, defaults to true. If one or more payment method/type is configured in the parent array then this value will be considered false for any other payment method that the parent array doesn't cover.

    • paymentMethodsarrayoptional
      • namestringoptional

        The name of the payment method. Possible value currently is: 'easy-invoice'.

      • feeobjectoptional

        Represents a line of a customer order. An order item refers to a product that the customer has bought. A product can be anything from a physical product to an online subscription or shipping.

        • referencestringrequired

          A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

        • namestringrequired

          The name of the product.

        • quantitynumber (double)required

          The quantity of the product.

        • unitstringrequired

          The defined unit of measurement for the product, for example pcs, liters, or kg.

        • unitPriceinteger (int32)required

          The price per unit excluding VAT.

        • taxRateinteger (int32)optional

          The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

        • taxAmountinteger (int32)optional

          The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

        • grossTotalAmountinteger (int32)required

          The total amount including VAT (netTotalAmount + taxAmount).

        • netTotalAmountinteger (int32)required

          The total amount excluding VAT (unitPrice * quantity).

    • myReferencestringoptional

      Merchant payment reference

    Request body

    {
        "order": {
            "items": [
                {
                    "reference": "string",
                    "name": "string",
                    "quantity": 0,
                    "unit": "string",
                    "unitPrice": 0,
                    "taxRate": 0,
                    "taxAmount": 0,
                    "grossTotalAmount": 0,
                    "netTotalAmount": 0
                }
            ],
            "amount": 0,
            "currency": "string",
            "reference": "string"
        },
        "checkout": {
            "url": "string",
            "integrationType": "string",
            "returnUrl": "string",
            "cancelUrl": "string",
            "consumer": {
                "reference": "string",
                "email": "string",
                "shippingAddress": {
                    "addressLine1": "string",
                    "addressLine2": "string",
                    "postalCode": "string",
                    "city": "string",
                    "country": "string"
                },
                "phoneNumber": {
                    "prefix": "string",
                    "number": "string"
                },
                "privatePerson": {
                    "firstName": "string",
                    "lastName": "string"
                },
                "company": {
                    "name": "string",
                    "contact": {
                        "firstName": "string",
                        "lastName": "string"
                    }
                }
            },
            "termsUrl": "string",
            "merchantTermsUrl": "string",
            "shippingCountries": [
                {
                    "countryCode": "string"
                }
            ],
            "shipping": {
                "countries": [
                    {
                        "countryCode": "string"
                    }
                ],
                "merchantHandlesShippingCost": true,
                "enableBillingAddress": true
            },
            "consumerType": {
                "default": "string",
                "supportedTypes": [
                    "string"
                ]
            },
            "charge": true,
            "publicDevice": true,
            "merchantHandlesConsumerData": true,
            "appearance": {
                "displayOptions": {
                    "showMerchantName": true,
                    "showOrderSummary": true
                },
                "textOptions": {
                    "completePaymentButtonText": "string"
                }
            },
            "countryCode": "string"
        },
        "merchantNumber": "string",
        "notifications": {
            "webHooks": [
                {
                    "eventName": "string",
                    "url": "string",
                    "authorization": "string",
                    "headers": null
                }
            ]
        },
        "subscription": {
            "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
            "endDate": "2019-08-24T14:15:22Z",
            "interval": 0
        },
        "unscheduledSubscription": {
            "create": true,
            "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03"
        },
        "paymentMethodsConfiguration": [
            {
                "name": "string",
                "enabled": true
            }
        ],
        "paymentMethods": [
            {
                "name": "string",
                "fee": {
                    "reference": "string",
                    "name": "string",
                    "quantity": 0,
                    "unit": "string",
                    "unitPrice": 0,
                    "taxRate": 0,
                    "taxAmount": 0,
                    "grossTotalAmount": 0,
                    "netTotalAmount": 0
                }
            }
        ],
        "myReference": "string"
    }

    Responses

    • 201Successoptional
      • paymentIdstringrequired

        The identifier (UUID) of the newly created payment object. Use this identifier in subsequent request when referring to the new payment.

      • hostedPaymentPageUrlstringoptional

        The URL your website should redirect to if using a hosted pre-built checkout page.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "paymentId": "string",
        "hostedPaymentPageUrl": "string"
    }

    Retrieve payment

    GET /v1/payments/{paymentId}

    Retrieves the details of an existing payment. The paymentId is obtained from Nets when creating a payment object.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Retrieve payment

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • paymentobjectoptional

        Contains all information about a payment.

        • paymentIdstring (uuid)required

          The payment identifier (a UUID).

        • summaryobjectoptional

          Summarizes the reserved, charged, refunded, and canceled amounts associated with a payment.

          • reservedAmountinteger (int32)optional

            The amount that has been reserved in the customer's bank account at the time of the purchase to make sure there are sufficient funds to charge the payment. See also the Create payment method.

          • chargedAmountinteger (int32)optional

            The charged amount. See also the Charge payment method.

          • refundedAmountinteger (int32)optional

            The amount that has been refunded. See also the Refund payment method.

          • cancelledAmountinteger (int32)optional

            The amount that has been canceled. See also the Cancel payment method.

        • consumerobjectoptional
          • shippingAddressobjectoptional
            • addressLine1stringoptional

              The primary address line.

            • addressLine2stringoptional

              An additional address line.

            • receiverLinestringoptional

              The name (or company name) of the customer.

            • postalCodestringoptional

              The postal code.

            • citystringoptional

              The city.

            • countrystringoptional

              A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported languages.

          • companyobjectoptional
            • merchantReferencestringoptional
            • namestringoptional

              The company name.

            • registrationNumberstringoptional
            • contactDetailsobjectoptional

              Information about the contact person for a company.

              • firstNamestringoptional

                The first name (also known as given name).

              • lastNamestringoptional

                The last name (also known as surname/family name).

              • emailstringoptional

                The email address.

              • phoneNumberobjectoptional

                An international phone number.

                • prefixstringoptional

                  The country calling code, for example 001.

                • numberstringoptional

                  The phone number (without the country code prefix).

          • privatePersonobjectoptional
            • merchantReferencestringoptional
            • dateOfBirthstring (date-time)optional

              The date on which the customer was born.

            • firstNamestringoptional

              The first name (also known as given name).

            • lastNamestringoptional

              The last name (also known as surname/family name).

            • emailstringoptional

              The email address.

            • phoneNumberobjectoptional

              An international phone number.

              • prefixstringoptional

                The country calling code, for example 001.

              • numberstringoptional

                The phone number (without the country code prefix).

          • billingAddressobjectoptional
            • addressLine1stringoptional

              The primary address line.

            • addressLine2stringoptional

              An additional address line.

            • receiverLinestringoptional

              The name (or company name) of the customer.

            • postalCodestringoptional

              The postal code.

            • citystringoptional

              The city.

            • countrystringoptional

              A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported languages.

        • paymentDetailsobjectoptional
          • paymentTypestringoptional

            The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.

          • paymentMethodstringoptional

            The payment method, for example Visa or Mastercard.

          • invoiceDetailsobjectoptional
            • invoiceNumberstringoptional
            • ocrstringoptional

              A reference number.

            • pdfLinkstringoptional
            • dueDatestring (date-time)optional
          • cardDetailsobjectoptional
            • maskedPanstringoptional

              A masked version of the PAN (Primary Account Number). At maximum, only the first six and last four digits of the account number are displayed.

            • expiryDatestringoptional

              The four-digit expiration date of the payment card. The format should be: YYMM.

        • orderDetailsobjectrequired
          • amountinteger (int32)required

            The total amount of the order, for example 10000.

          • currencystringrequired

            The currency of the payment, for example 'SEK'.

          • referencestringoptional

            The reference to recognize this order. Usually a number sequence provided when creating or updating the payment.

        • checkoutobjectrequired
          • urlstringrequired

            The URL to the hosted or embedded checkout page.

          • cancelUrlstringoptional

            The URL to the page responsible for handling a canceled checkout.

        • createdstring (date-time)required

          The date and time when the payment was initiated.

        • refundsarrayoptional

          An array of all the refunds associated with this payment.

          • refundIdstring (uuid)optional

            A unique identifier of this refund.

          • amountinteger (int32)optional

            The total amount of the refund.

          • statestringoptional

            The current state of the refund. Possible values are: 'Pending', 'Cancelled', 'Failed', 'Completed', 'Expired'.

          • lastUpdatedstring (date-time)optional

            The date and time when the refund was last updated.

          • orderItemsarrayoptional

            The list of returned and canceled order items that are associated with the refund. At least one order item is required.

            • referencestringrequired

              A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

            • namestringrequired

              The name of the product.

            • quantitynumber (double)required

              The quantity of the product.

            • unitstringrequired

              The defined unit of measurement for the product, for example pcs, liters, or kg.

            • unitPriceinteger (int32)required

              The price per unit excluding VAT.

            • taxRateinteger (int32)optional

              The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

            • taxAmountinteger (int32)optional

              The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

            • grossTotalAmountinteger (int32)required

              The total amount including VAT (netTotalAmount + taxAmount).

            • netTotalAmountinteger (int32)required

              The total amount excluding VAT (unitPrice * quantity).

        • chargesarrayoptional
          • chargeIdstring (uuid)optional

            A unique identifier of the charge.

          • amountinteger (int32)optional

            The total amount of this charge.

          • createdstring (date-time)optional

            The date and time when the charge was initiated.

          • orderItemsarrayoptional

            The array of order items associated with the charge.

            • referencestringrequired

              A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

            • namestringrequired

              The name of the product.

            • quantitynumber (double)required

              The quantity of the product.

            • unitstringrequired

              The defined unit of measurement for the product, for example pcs, liters, or kg.

            • unitPriceinteger (int32)required

              The price per unit excluding VAT.

            • taxRateinteger (int32)optional

              The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

            • taxAmountinteger (int32)optional

              The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

            • grossTotalAmountinteger (int32)required

              The total amount including VAT (netTotalAmount + taxAmount).

            • netTotalAmountinteger (int32)required

              The total amount excluding VAT (unitPrice * quantity).

        • terminatedstring (date-time)optional

          The date and time of termination. Only present if the payment has been terminated.

        • subscriptionobjectoptional

          The subscription identifier.

          • idstring (uuid)optional

            The subscription identifier (a UUID).

        • unscheduledSubscriptionobjectoptional

          The unscheduled subscription identifier.

          • unscheduledSubscriptionIdstring (uuid)optional

            The unscheduled subscription identifier (a UUID).

        • myReferencestringoptional

          Merchant payment reference

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "payment": {
            "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
            "summary": {
                "reservedAmount": 0,
                "chargedAmount": 0,
                "refundedAmount": 0,
                "cancelledAmount": 0
            },
            "consumer": {
                "shippingAddress": {
                    "addressLine1": "string",
                    "addressLine2": "string",
                    "receiverLine": "string",
                    "postalCode": "string",
                    "city": "string",
                    "country": "string"
                },
                "company": {
                    "merchantReference": "string",
                    "name": "string",
                    "registrationNumber": "string",
                    "contactDetails": {
                        "firstName": "string",
                        "lastName": "string",
                        "email": "string",
                        "phoneNumber": {
                            "prefix": "string",
                            "number": "string"
                        }
                    }
                },
                "privatePerson": {
                    "merchantReference": "string",
                    "dateOfBirth": "2019-08-24T14:15:22Z",
                    "firstName": "string",
                    "lastName": "string",
                    "email": "string",
                    "phoneNumber": {
                        "prefix": "string",
                        "number": "string"
                    }
                },
                "billingAddress": {
                    "addressLine1": "string",
                    "addressLine2": "string",
                    "receiverLine": "string",
                    "postalCode": "string",
                    "city": "string",
                    "country": "string"
                }
            },
            "paymentDetails": {
                "paymentType": "string",
                "paymentMethod": "string",
                "invoiceDetails": {
                    "invoiceNumber": "string",
                    "ocr": "string",
                    "pdfLink": "string",
                    "dueDate": "2019-08-24T14:15:22Z"
                },
                "cardDetails": {
                    "maskedPan": "string",
                    "expiryDate": "string"
                }
            },
            "orderDetails": {
                "amount": 0,
                "currency": "string",
                "reference": "string"
            },
            "checkout": {
                "url": "string",
                "cancelUrl": "string"
            },
            "created": "2019-08-24T14:15:22Z",
            "refunds": [
                {
                    "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
                    "amount": 0,
                    "state": "string",
                    "lastUpdated": "2019-08-24T14:15:22Z",
                    "orderItems": [
                        {
                            "reference": "string",
                            "name": "string",
                            "quantity": 0,
                            "unit": "string",
                            "unitPrice": 0,
                            "taxRate": 0,
                            "taxAmount": 0,
                            "grossTotalAmount": 0,
                            "netTotalAmount": 0
                        }
                    ]
                }
            ],
            "charges": [
                {
                    "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640",
                    "amount": 0,
                    "created": "2019-08-24T14:15:22Z",
                    "orderItems": [
                        {
                            "reference": "string",
                            "name": "string",
                            "quantity": 0,
                            "unit": "string",
                            "unitPrice": 0,
                            "taxRate": 0,
                            "taxAmount": 0,
                            "grossTotalAmount": 0,
                            "netTotalAmount": 0
                        }
                    ]
                }
            ],
            "terminated": "2019-08-24T14:15:22Z",
            "subscription": {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "unscheduledSubscription": {
                "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03"
            },
            "myReference": "string"
        }
    }

    Update reference information

    PUT /v1/payments/{paymentId}/referenceinformation

    Updates the specified payment object with a new reference string and a checkoutUrl.

    If you instead want to update the order of a payment object, use the Update order method.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Update reference information

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/referenceinformation");
    var request = new RestRequest(Method.PUT);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • checkoutUrlstringrequired
    • referencestringrequired

    Request body

    {
        "checkoutUrl": "string",
        "reference": "string"
    }

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Update order

    PUT /v1/payments/{paymentId}/orderitems

    Updates the order for the specified payment. This endpoint makes it possible to change the order on the checkout page after the payment object has been created. This is typically used when managing destination-based shipping costs at the checkout.

    This endpoint can only be used as long as the checkout has not yet been completed by the customer. (See the payment.checkout.completed event.)

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstring (uuid)required

      The payment identifier.

    Update order

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/orderitems");
    var request = new RestRequest(Method.PUT);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • amountinteger (int32)optional

      The amount, for example 10000.

    • itemsarrayoptional

      The array of order items.

      • referencestringrequired

        A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

      • namestringrequired

        The name of the product.

      • quantitynumber (double)required

        The quantity of the product.

      • unitstringrequired

        The defined unit of measurement for the product, for example pcs, liters, or kg.

      • unitPriceinteger (int32)required

        The price per unit excluding VAT.

      • taxRateinteger (int32)optional

        The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

      • taxAmountinteger (int32)optional

        The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

      • grossTotalAmountinteger (int32)required

        The total amount including VAT (netTotalAmount + taxAmount).

      • netTotalAmountinteger (int32)required

        The total amount excluding VAT (unitPrice * quantity).

    • shippingobjectoptional
      • costSpecifiedbooleanoptional
    • paymentMethodsarrayoptional

      Specifies an array of invoice fees added to the total price when invoice is used as the payment method.

      • namestringoptional
      • feeobjectoptional

        Represents a line of a customer order. An order item refers to a product that the customer has bought. A product can be anything from a physical product to an online subscription or shipping.

        • referencestringrequired

          A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

        • namestringrequired

          The name of the product.

        • quantitynumber (double)required

          The quantity of the product.

        • unitstringrequired

          The defined unit of measurement for the product, for example pcs, liters, or kg.

        • unitPriceinteger (int32)required

          The price per unit excluding VAT.

        • taxRateinteger (int32)optional

          The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

        • taxAmountinteger (int32)optional

          The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

        • grossTotalAmountinteger (int32)required

          The total amount including VAT (netTotalAmount + taxAmount).

        • netTotalAmountinteger (int32)required

          The total amount excluding VAT (unitPrice * quantity).

    Request body

    {
        "amount": 0,
        "items": [
            {
                "reference": "string",
                "name": "string",
                "quantity": 0,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0
            }
        ],
        "shipping": {
            "costSpecified": true
        },
        "paymentMethods": [
            {
                "name": "string",
                "fee": {
                    "reference": "string",
                    "name": "string",
                    "quantity": 0,
                    "unit": "string",
                    "unitPrice": 0,
                    "taxRate": 0,
                    "taxAmount": 0,
                    "grossTotalAmount": 0,
                    "netTotalAmount": 0
                }
            }
        ]
    }

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Terminate payment

    PUT /v1/payments/{paymentId}/terminate

    Terminates an ongoing checkout session. A payment can only be terminated before the checkout has completed (see the payment.checkout event). Use this method to prevent a customer from having multiple open payment sessions simultaneously.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Terminate payment

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/terminate");
    var request = new RestRequest(Method.PUT);
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 405Method Not Allowedoptional
    • 409Conflictoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Cancel payment

    POST /v1/payments/{paymentId}/cancels

    Cancels the specified payment. When a payment is canceled, the reserved amount of the payment will be released to the customer's payment card.

    Note that:

    • Only full cancels are allowed. The amount must always match the total amount of the order.
    • Once a payment has been charged (fully or partially), the payment cannot be canceled.
    • It is not possible to change the status of a payment once it has been canceled.
    • Nets will not charge a fee for a canceled payment.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Cancel payment

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/cancels");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • amountinteger (int32)optional

      The amount to be canceled.

    • orderItemsarrayoptional

      The order items to be canceled. Note! Since only full cancels are currently supported, you need to provide all order items or completely avoid specifying any order items.

      • referencestringrequired

        A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

      • namestringrequired

        The name of the product.

      • quantitynumber (double)required

        The quantity of the product.

      • unitstringrequired

        The defined unit of measurement for the product, for example pcs, liters, or kg.

      • unitPriceinteger (int32)required

        The price per unit excluding VAT.

      • taxRateinteger (int32)optional

        The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

      • taxAmountinteger (int32)optional

        The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

      • grossTotalAmountinteger (int32)required

        The total amount including VAT (netTotalAmount + taxAmount).

      • netTotalAmountinteger (int32)required

        The total amount excluding VAT (unitPrice * quantity).

    Request body

    {
        "amount": 0,
        "orderItems": [
            {
                "reference": "string",
                "name": "string",
                "quantity": 0,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0
            }
        ]
    }

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Charge payment

    POST /v1/payments/{paymentId}/charges

    Charges the specified payment. Charge a payment on the same day as you ship the matching order.A payment can be fully charged or partially charged:

    • Full charge: Your customer will be charged the total amount of the payment. The amount must be specified in the request body and is required to match the total amount of the payment.
    • Partial charge: Only charge for a subset of the order items. In this case you have to provide the amount and the orderItems you want to charge in the request body.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • Idempotency-Keystringoptional

      A string that uniquely identifies the charge you are attempting. Must be between 1 and 64 characters.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Charge payment

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/charges");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Idempotency-Key", "SOME_STRING_VALUE");
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • amountinteger (int32)required

      The amount to be charged.

    • orderItemsarrayoptional

      The order items list to charge for. Only required for partial charges.

      • referencestringrequired

        A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

      • namestringrequired

        The name of the product.

      • quantitynumber (double)required

        The quantity of the product.

      • unitstringrequired

        The defined unit of measurement for the product, for example pcs, liters, or kg.

      • unitPriceinteger (int32)required

        The price per unit excluding VAT.

      • taxRateinteger (int32)optional

        The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

      • taxAmountinteger (int32)optional

        The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

      • grossTotalAmountinteger (int32)required

        The total amount including VAT (netTotalAmount + taxAmount).

      • netTotalAmountinteger (int32)required

        The total amount excluding VAT (unitPrice * quantity).

    • shippingobjectoptional
      • trackingNumberstringoptional
      • providerstringoptional
    • finalChargebooleanoptional

      Flag to release remaining reservation

    • myReferencestringoptional

      Merchant payment reference

    Request body

    {
        "amount": 0,
        "orderItems": [
            {
                "reference": "string",
                "name": "string",
                "quantity": 0,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0
            }
        ],
        "shipping": {
            "trackingNumber": "string",
            "provider": "string"
        },
        "finalCharge": true,
        "myReference": "string"
    }

    Responses

    • 201Successoptional
      • chargeIdstringrequired
      • invoiceobjectoptional
        • invoiceNumberstringoptional

          The invoice number.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 402Client Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "chargeId": "string",
        "invoice": {
            "invoiceNumber": "string"
        }
    }

    Retrieve charge

    GET /v1/charges/{chargeId}

    Retrieves the details of an existing charge operation. The chargeId is obtained from Nets when creating a new charge. The primary usage of this method is to retrieve invoice details of a charge.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • chargeIdstringrequired

      The identifier of the existing charge (a UUID).

    Retrieve charge

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/charges/%7BchargeId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • chargeIdstring (uuid)required

        The charge identifier (a UUID).

      • amountinteger (int32)required

        The amount, for example 10000.

      • invoiceDetailsobjectoptional

        Information about an publicly accessible invoice.

        • linkstringoptional

          The URL of an invoice that is publicly accessible.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640",
        "amount": 0,
        "invoiceDetails": {
            "link": "string"
        }
    }

    Refund charge

    POST /v1/charges/{chargeId}/refunds

    Refunds a previously settled transaction (a charged payment). The refunded amount will be transferred back to the customer's account. The required chargeId is returned from the Charge payment method

    A settled transaction can be fully or partially refunded:

    • Full refund requires only the amount to be specified in the request body.
    • Partial refund requires the amount and the orderItems to be refunded.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • chargeIdstringrequired
    • Idempotency-Keystringoptional

      A string that uniquely identifies the refund you are attempting. Must be between 1 and 64 characters.

    Refund charge

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/charges/%7BchargeId%7D/refunds");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Idempotency-Key", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • amountinteger (int32)required

      The amount, for example 10000.

    • orderItemsarrayoptional
      • referencestringrequired

        A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

      • namestringrequired

        The name of the product.

      • quantitynumber (double)required

        The quantity of the product.

      • unitstringrequired

        The defined unit of measurement for the product, for example pcs, liters, or kg.

      • unitPriceinteger (int32)required

        The price per unit excluding VAT.

      • taxRateinteger (int32)optional

        The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

      • taxAmountinteger (int32)optional

        The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

      • grossTotalAmountinteger (int32)required

        The total amount including VAT (netTotalAmount + taxAmount).

      • netTotalAmountinteger (int32)required

        The total amount excluding VAT (unitPrice * quantity).

    Request body

    {
        "amount": 0,
        "orderItems": [
            {
                "reference": "string",
                "name": "string",
                "quantity": 0,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0
            }
        ]
    }

    Responses

    • 201Successoptional
      • refundIdstringrequired
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "refundId": "string"
    }

    Retrieve refund

    GET /v1/refunds/{refundId}

    Retrieves the details of an existing refund. The refundId is obtained from Nets when creating a new refund. The primary usage of this method is to retrieve invoice details of a refund.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • refundIdstringrequired

      The identifier of the existing refund (a UUID).

    Retrieve refund

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/refunds/%7BrefundId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • refundIdstring (uuid)required

        The refund identifier (a UUID).

      • amountinteger (int32)required

        The amount, for example 10000.

      • invoiceDetailsobjectoptional

        Information about an publicly accessible invoice.

        • linkstringoptional

          The URL of an invoice that is publicly accessible.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "refundId": "3324897f-393a-4bf6-b3af-0b999cbc2521",
        "amount": 0,
        "invoiceDetails": {
            "link": "string"
        }
    }

    Cancel pending refund

    POST /v1/pending-refunds/{refundId}/cancel

    Cancels a pending refund. A refund can be in a pending state when there are not enough funds in the merchant's account to make the refund.

    The refundId is returned when creating a new refund.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • refundIdstringrequired

      The identifier of the pending refund (a UUID).

    Cancel pending refund

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/pending-refunds/%7BrefundId%7D/cancel");
    var request = new RestRequest(Method.POST);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Update myReference

    PUT /v1/payments/{paymentId}/myreference

    Updates myReference field on payment.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • paymentIdstringrequired

      The payment identifier.

    • CommercePlatformTagstringoptional

      An identifier of the ecommerce platform.

    Update myReference

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/payments/%7BpaymentId%7D/myreference");
    var request = new RestRequest(Method.PUT);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • myReferencestringoptional

      Merchant payment reference

    Request body

    {
        "myReference": "string"
    }

    Responses

    • 204Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 405Method Not Allowedoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "errors": {
            "property1": [
                "string"
            ],
            "property2": [
                "string"
            ]
        }
    }

    Subscriptions

    Subscriptions allow you to charge your customers on a regular basis, for example a monthly subscription for a product the customer must pay for every month.

    When a subscription is charged, a new payment object is created to represent the purchase of the subscription product.

    It is possible to verify and charge multiple subscriptions in bulk using the Bulk charge subscriptions method.

    Retrieve subscription

    GET /v1/subscriptions/{subscriptionId}

    Retrieves an existing subscription by a subscriptionId. The subscriptionId can be obtained from the Retrieve payment method.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • subscriptionIdstring (uuid)required

      The subscription identifier (a UUID).

    • MerchantNumberstringoptional

      The merchant number. Use this header only if you are a Nets partner and initiating the checkout with your partner keys. If you are using the integration keys for your webshop, there is no need to specify this header.

    Retrieve subscription

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions/%7BsubscriptionId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("MerchantNumber", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • subscriptionIdstring (uuid)required

        The subscription identifier.

      • frequencyinteger (int32)optional
      • intervalinteger (int32)required

        Defines the minimum number of days between each recurring charge. This interval commences from either the day the subscription was created or the most recent subscription charge, whichever is later. An interval value of 0 means that there are no payment interval restrictions.

      • endDatestring (date-time)required

        Refers to the date and time the subscription will expire. The field has three components: date, time, and time zone (offset from GMT), for example: 2021-07-02T12:00:00.0000+02:00.

      • paymentDetailsobjectrequired
        • paymentTypestringrequired

          The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.

        • paymentMethodstringrequired

          The payment method. For example Visa or Mastercard.

        • cardDetailsobjectrequired
          • expiryDatestringrequired

            The four-digit expiration date of the payment card. The format should be: YYMM.

          • maskedPanstringrequired

            A masked version of the PAN (Primary Account Number). At maximum, only the first six and last four digits of the account number are displayed.

      • importErrorobjectoptional

        Represents an error that occurred during the import of a subscription from an external ecommerce system.

        • importStepsResponseCodestringoptional

          The error code.

        • importStepsResponseSourcestringoptional

          The source of the error.

        • importStepsResponseTextstringoptional

          The error message.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
        "frequency": 0,
        "interval": 0,
        "endDate": "2019-08-24T14:15:22Z",
        "paymentDetails": {
            "paymentType": "string",
            "paymentMethod": "string",
            "cardDetails": {
                "expiryDate": "string",
                "maskedPan": "string"
            }
        },
        "importError": {
            "importStepsResponseCode": "string",
            "importStepsResponseSource": "string",
            "importStepsResponseText": "string"
        }
    }

    Retrieve subscription by external reference

    GET /v1/subscriptions

    Retrieves a subscription matching the specified externalReference. This method can only be used for retrieving subscriptions that have been imported from a payment platform other than Nets Easy. Subscriptions created within Nets Easy do not have an externalReference value set.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • externalReferencestringoptional

      The external reference to search for.

    • MerchantNumberstringoptional

      The merchant number. Use this header only if you are a Nets partner and initiating the checkout with your partner keys. If you are using the integration keys for your webshop, there is no need to specify this header.

    Retrieve subscription by external reference

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions?externalReference=SOME_STRING_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("MerchantNumber", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • subscriptionIdstring (uuid)required

        The subscription identifier.

      • frequencyinteger (int32)optional
      • intervalinteger (int32)required

        Defines the minimum number of days between each recurring charge. This interval commences from either the day the subscription was created or the most recent subscription charge, whichever is later. An interval value of 0 means that there are no payment interval restrictions.

      • endDatestring (date-time)required

        Refers to the date and time the subscription will expire. The field has three components: date, time, and time zone (offset from GMT), for example: 2021-07-02T12:00:00.0000+02:00.

      • paymentDetailsobjectrequired
        • paymentTypestringrequired

          The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.

        • paymentMethodstringrequired

          The payment method. For example Visa or Mastercard.

        • cardDetailsobjectrequired
          • expiryDatestringrequired

            The four-digit expiration date of the payment card. The format should be: YYMM.

          • maskedPanstringrequired

            A masked version of the PAN (Primary Account Number). At maximum, only the first six and last four digits of the account number are displayed.

      • importErrorobjectoptional

        Represents an error that occurred during the import of a subscription from an external ecommerce system.

        • importStepsResponseCodestringoptional

          The error code.

        • importStepsResponseSourcestringoptional

          The source of the error.

        • importStepsResponseTextstringoptional

          The error message.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
        "frequency": 0,
        "interval": 0,
        "endDate": "2019-08-24T14:15:22Z",
        "paymentDetails": {
            "paymentType": "string",
            "paymentMethod": "string",
            "cardDetails": {
                "expiryDate": "string",
                "maskedPan": "string"
            }
        },
        "importError": {
            "importStepsResponseCode": "string",
            "importStepsResponseSource": "string",
            "importStepsResponseText": "string"
        }
    }

    Bulk charge subscriptions

    POST /v1/subscriptions/charges

    Charges multiple subscriptions at once. The request body must contain:

    • A unique string that identifies this bulk charge operation
    • A set of subscription identifiers that should be charged.

    To get status updates about the bulk charge you can subscribe to the webhooks for charges and refunds (payment.charges.* and payments.refunds.*). See also the webhooks documentation.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • MerchantNumberstringoptional

      The merchant number. Use this header only if you are a Nets partner and initiating the checkout with your partner keys. If you are using the integration keys for your webshop, there is no need to specify this header.

    Bulk charge subscriptions

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions/charges");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("MerchantNumber", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • externalBulkChargeIdstringoptional

      A string that uniquely identifies the bulk charge operation. Use this property for enabling safe retries. Must be between 1 and 64 characters.

    • notificationsobjectoptional

      Notifications allow you to subscribe to status updates for a payment.

      • webHooksarrayoptional

        The list of webhooks. The maximum number of webhooks is 32.

        • eventNamestringoptional

          The name of the event you want to subscribe to. See webhooks for the complete list of events.

        • urlstringoptional

          The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.

        • authorizationstringoptional

          The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.

    • subscriptionsarrayoptional

      The array of subscriptions that should be charged. Each item in the array should define either a subscriptionId or an externalReference, but not both.

      • subscriptionIdstring (uuid)optional

        The subscription identifier (a UUID) returned from the Retrieve payment method.

      • externalReferencestringoptional

        An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

      • orderobjectrequired

        Specifies an order associated with a payment. An order must contain at least one order item. The amount of the order must match the sum of the specified order items.

        • itemsarrayrequired

          A list of order items. At least one item must be specified.

          • referencestringrequired

            A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

          • namestringrequired

            The name of the product.

          • quantitynumber (double)required

            The quantity of the product.

          • unitstringrequired

            The defined unit of measurement for the product, for example pcs, liters, or kg.

          • unitPriceinteger (int32)required

            The price per unit excluding VAT.

          • taxRateinteger (int32)optional

            The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

          • taxAmountinteger (int32)optional

            The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

          • grossTotalAmountinteger (int32)required

            The total amount including VAT (netTotalAmount + taxAmount).

          • netTotalAmountinteger (int32)required

            The total amount excluding VAT (unitPrice * quantity).

        • amountinteger (int32)required

          The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.)

        • currencystringrequired

          The currency of the payment, for example 'SEK'.

        • referencestringoptional

          A reference to recognize this order. Usually a number sequence (order number).

    Request body

    {
        "externalBulkChargeId": "string",
        "notifications": {
            "webHooks": [
                {
                    "eventName": "string",
                    "url": "string",
                    "authorization": "string",
                    "headers": null
                }
            ]
        },
        "subscriptions": [
            {
                "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
                "externalReference": "string",
                "order": {
                    "items": [
                        {
                            "reference": "string",
                            "name": "string",
                            "quantity": 0,
                            "unit": "string",
                            "unitPrice": 0,
                            "taxRate": 0,
                            "taxAmount": 0,
                            "grossTotalAmount": 0,
                            "netTotalAmount": 0
                        }
                    ],
                    "amount": 0,
                    "currency": "string",
                    "reference": "string"
                }
            }
        ]
    }

    Responses

    • 202Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "bulkId": "50490f2b-98bd-4782-b08d-413ee70aa1f7"
    }

    Retrieve bulk charges

    GET /v1/subscriptions/charges/{bulkId}

    Retrieves charges associated with the specified bulk charge operation. The bulkId is returned from Nets in the response of the Bulk charge subscriptions method.

    This method supports pagination. Specify the range of subscriptions to retrieve by using either skip and take or pageNumber together with pageSize. The boolean property named more in the response body, indicates whether there are more subscriptions beyond the requested range.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • bulkIdstringrequired

      The identifier of the bulk charge operation that was returned from the Bulk charge subscriptions method.

    • skipinteger (int32)optional

      The number of subscription entries to skip from the start. Use this property in combination with the take property.

    • takeinteger (int32)optional

      The maximum number of subscriptions to be retrieved. Use this property in combination with the skip property.

    • pageNumberinteger (int32)optional

      The page number to be retrieved. Use this property in combination with the pageSize property.

    • pageSizeinteger (int32)optional

      The size of each page when specify the range of subscriptions using the pageNumber property.

    • MerchantNumberstringoptional

      The merchant number. Use this header only if you are a Nets partner and initiating the checkout with your partner keys. If you are using the integration keys for your webshop, there is no need to specify this header.

    Retrieve bulk charges

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions/charges/%7BbulkId%7D?skip=SOME_INTEGER_VALUE&take=SOME_INTEGER_VALUE&pageNumber=SOME_INTEGER_VALUE&pageSize=SOME_INTEGER_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("MerchantNumber", "SOME_STRING_VALUE");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • pagearrayoptional
        • subscriptionIdstring (uuid)required

          The subscription identifier (a UUID) returned from the Retrieve payment method.

        • paymentIdstring (uuid)optional

          The payment identifier.

        • chargeIdstring (uuid)optional

          The charge identifier (a UUID) returned from the Charge payment method.

        • statusstringrequired

          The current processing status of the subscription. Possible values are: 'Pending', 'Succeeded', and 'Failed'.

        • messagestringoptional
        • codestringoptional
        • sourcestringoptional
        • externalReferencestringoptional

          An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

      • morebooleanoptional

        Indicates whether there are more subscriptions beyond the requested range.

      • statusstringoptional

        Indicates whether the operation has completed or is still processing subscriptions. Possible values are 'Done' and 'Processing'.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "page": [
            {
                "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
                "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
                "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640",
                "status": "string",
                "message": "string",
                "code": "string",
                "source": "string",
                "externalReference": "string"
            }
        ],
        "more": true,
        "status": "string"
    }

    Verify subscriptions

    POST /v1/subscriptions/verifications

    Verifies the specified set of subscriptions in bulk. The bulkId returned from a successful request can be used for querying the status of the subscriptions.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    Verify subscriptions

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions/verifications");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • externalBulkVerificationIdstringoptional

      A string that uniquely identifies the verification operation. Use this property for enabling safe retries. Must be between 1 and 64 characters.

    • subscriptionsarrayoptional

      The set of subscriptions that should be verified. Each item in the array should define either a subscriptioId or an externalReference, but not both.

      • subscriptionIdstring (uuid)optional

        The identifier of the subscription (a UUID). The subscriptionId can be obtained using the Retrieve payment method.

      • externalReferencestringoptional

        An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

    Request body

    {
        "externalBulkVerificationId": "string",
        "subscriptions": [
            {
                "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
                "externalReference": "string"
            }
        ]
    }

    Responses

    • 202Successoptional
      • bulkIdstring (uuid)required
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "bulkId": "50490f2b-98bd-4782-b08d-413ee70aa1f7"
    }

    Retrieve bulk verifications

    GET /v1/subscriptions/verifications/{bulkId}

    Retrieves verifications associated with the specified bulk verification operation. The bulkId is returned from Nets in the response of the Verify subscriptions method.

    This method supports pagination. Specify the range of subscriptions to retrieve by using either skip and take or pageNumber together with pageSize. The boolean property named more in the response body, indicates whether there are more subscriptions beyond the requested range.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • bulkIdstringrequired

      The identifier of the bulk verification operation that was returned from the erfiy subscriptions method.

    • skipinteger (int32)optional

      The number of subscription entries to skip from the start. Use this property in combination with the take property.

    • takeinteger (int32)optional

      The maximum number of subscriptions to be retrieved. Use this property in combination with the skip property.

    • pageNumberinteger (int32)optional

      The page number to be retrieved. Use this property in combination with the pageSize property.

    • pageSizeinteger (int32)optional

      The size of each page when specify the range of subscriptions using the pageNumber property.

    Retrieve bulk verifications

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/subscriptions/verifications/%7BbulkId%7D?skip=SOME_INTEGER_VALUE&take=SOME_INTEGER_VALUE&pageNumber=SOME_INTEGER_VALUE&pageSize=SOME_INTEGER_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • pagearrayoptional
        • subscriptionIdstring (uuid)required

          The identifier of the subscription (a UUID).

        • externalReferencestringoptional

          An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

        • statusstringrequired

          The current processing status of the subscription. Possible values are: 'Pending', 'Succeeded', and 'Failed'.

        • paymentIdstring (uuid)optional

          The payment identifier (a UUID).

      • morebooleanoptional

        Indicates whether there are more subscriptions beyond the requested range.

      • statusstringoptional

        Indicates whether the operation has completed or is still processing subscriptions. Possible values are 'Done' and 'Processing'.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "page": [
            {
                "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",
                "externalReference": "string",
                "status": "string",
                "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7"
            }
        ],
        "more": true,
        "status": "string"
    }

    UnscheduledSubscriptions

    Unscheduled subscriptions allow you to charge your customers at an unscheduled time interval with a variable amount, for example an automatic top-up agreement for a rail-card when the consumer drops below a certain stored value.

    When an unscheduled subscription is charged, a new payment object is created to represent the purchase of the unscheduled subscription product.

    It is possible to verify and charge multiple unscheduled subscriptions in bulk using the Bulk charge unscheduled subscriptions method.

    Retrieve unscheduled subscription

    GET /v1/unscheduledsubscriptions/{unscheduledSubscriptionId}

    Retrieves an existing unscheduled subscription by a unscheduledSubscriptionId. The unscheduledSubscriptionId can be obtained from the Retrieve payment method.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • unscheduledSubscriptionIdstring (uuid)required

      The unscheduled subscription identifier (a UUID).

    Retrieve unscheduled subscription

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/%7BunscheduledSubscriptionId%7D");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • unscheduledSubscriptionIdstring (uuid)required

        The unscheduled subscription identifier.

      • paymentDetailsobjectrequired
        • paymentTypestringrequired

          The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.

        • paymentMethodstringrequired

          The payment method. For example Visa or Mastercard.

        • cardDetailsobjectrequired
          • expiryDatestringrequired

            The four-digit expiration date of the payment card. The format should be: YYMM.

          • maskedPanstringrequired

            A masked version of the PAN (Primary Account Number). At maximum, only the first six and last four digits of the account number are displayed.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
        "paymentDetails": {
            "paymentType": "string",
            "paymentMethod": "string",
            "cardDetails": {
                "expiryDate": "string",
                "maskedPan": "string"
            }
        }
    }

    Retrieve unscheduled subscription by external reference

    GET /v1/unscheduledsubscriptions

    Retrieves an unscheduled subscription matching the specified externalReference. This method can only be used for retrieving unscheduled subscriptions that have been imported from a payment platform other than Nets Easy. Unscheduled subscriptions created within Nets Easy do not have an externalReference value set.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • externalReferencestringoptional

      The external reference to search for.

    Retrieve unscheduled subscription by external reference

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions?externalReference=SOME_STRING_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • unscheduledSubscriptionIdstring (uuid)required

        The unscheduled subscription identifier.

      • paymentDetailsobjectrequired
        • paymentTypestringrequired

          The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.

        • paymentMethodstringrequired

          The payment method. For example Visa or Mastercard.

        • cardDetailsobjectrequired
          • expiryDatestringrequired

            The four-digit expiration date of the payment card. The format should be: YYMM.

          • maskedPanstringrequired

            A masked version of the PAN (Primary Account Number). At maximum, only the first six and last four digits of the account number are displayed.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
        "paymentDetails": {
            "paymentType": "string",
            "paymentMethod": "string",
            "cardDetails": {
                "expiryDate": "string",
                "maskedPan": "string"
            }
        }
    }

    Charge unscheduled subscription

    POST /v1/unscheduledsubscriptions/{unscheduledSubscriptionId}/charges

    Charges a single unscheduled subscription. The unscheduledSubscriptionId can be obtained from the Retrieve payment method. On success, this method creates a new payment object and performs a charge of the specified amount. Both the new paymentId and chargeId are returned in the response body.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • unscheduledSubscriptionIdstring (uuid)required

      The unscheduled subscription identifier (a UUID) returned from the Retrieve payment method.

    Charge unscheduled subscription

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/%7BunscheduledSubscriptionId%7D/charges");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • orderobjectrequired

      Specifies an order associated with a payment. An order must contain at least one order item. The amount of the order must match the sum of the specified order items.

      • itemsarrayrequired

        A list of order items. At least one item must be specified.

        • referencestringrequired

          A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

        • namestringrequired

          The name of the product.

        • quantitynumber (double)required

          The quantity of the product.

        • unitstringrequired

          The defined unit of measurement for the product, for example pcs, liters, or kg.

        • unitPriceinteger (int32)required

          The price per unit excluding VAT.

        • taxRateinteger (int32)optional

          The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

        • taxAmountinteger (int32)optional

          The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

        • grossTotalAmountinteger (int32)required

          The total amount including VAT (netTotalAmount + taxAmount).

        • netTotalAmountinteger (int32)required

          The total amount excluding VAT (unitPrice * quantity).

      • amountinteger (int32)required

        The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.)

      • currencystringrequired

        The currency of the payment, for example 'SEK'.

      • referencestringoptional

        A reference to recognize this order. Usually a number sequence (order number).

    • notificationsobjectoptional

      Notifications allow you to subscribe to status updates for a payment.

      • webHooksarrayoptional

        The list of webhooks. The maximum number of webhooks is 32.

        • eventNamestringoptional

          The name of the event you want to subscribe to. See webhooks for the complete list of events.

        • urlstringoptional

          The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.

        • authorizationstringoptional

          The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.

    Request body

    {
        "order": {
            "items": [
                {
                    "reference": "string",
                    "name": "string",
                    "quantity": 0,
                    "unit": "string",
                    "unitPrice": 0,
                    "taxRate": 0,
                    "taxAmount": 0,
                    "grossTotalAmount": 0,
                    "netTotalAmount": 0
                }
            ],
            "amount": 0,
            "currency": "string",
            "reference": "string"
        },
        "notifications": {
            "webHooks": [
                {
                    "eventName": "string",
                    "url": "string",
                    "authorization": "string",
                    "headers": null
                }
            ]
        }
    }

    Responses

    • 200Successoptional
      • paymentIdstring (uuid)required

        The payment identifier of the new payment object created when charging for the unscheduled subscription.

      • chargeIdstring (uuid)required

        A unique identifier of the charge.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 402Client Erroroptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
        "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640"
    }

    Bulk charge unscheduled subscriptions

    POST /v1/unscheduledsubscriptions/charges

    Charges multiple unscheduled subscriptions at once. The request body must contain:

    • A unique string that identifies this bulk charge operation
    • A set of unscheduled subscription identifiers that should be charged.

    To get status updates about the bulk charge you can subscribe to the webhooks for charges and refunds (payment.charges.* and payments.refunds.*). See also the webhooks documentation.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    Bulk charge unscheduled subscriptions

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/charges");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • externalBulkChargeIdstringoptional

      A string that uniquely identifies the bulk charge operation. Use this property for enabling safe retries. Must be between 1 and 64 characters.

    • notificationsobjectoptional

      Notifications allow you to subscribe to status updates for a payment.

      • webHooksarrayoptional

        The list of webhooks. The maximum number of webhooks is 32.

        • eventNamestringoptional

          The name of the event you want to subscribe to. See webhooks for the complete list of events.

        • urlstringoptional

          The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.

        • authorizationstringoptional

          The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.

    • unscheduledSubscriptionsarrayoptional

      The array of unscheduled subscriptions that should be charged. Each item in the array should define either a subscriptionId or an externalReference, but not both.

      • unscheduledSubscriptionIdstring (uuid)optional

        The subscription identifier (a UUID) returned from the Retrieve payment method.

      • externalReferencestringoptional

        An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

      • orderobjectrequired

        Specifies an order associated with a payment. An order must contain at least one order item. The amount of the order must match the sum of the specified order items.

        • itemsarrayrequired

          A list of order items. At least one item must be specified.

          • referencestringrequired

            A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc).

          • namestringrequired

            The name of the product.

          • quantitynumber (double)required

            The quantity of the product.

          • unitstringrequired

            The defined unit of measurement for the product, for example pcs, liters, or kg.

          • unitPriceinteger (int32)required

            The price per unit excluding VAT.

          • taxRateinteger (int32)optional

            The tax/VAT rate (in percentage times 100). For examlpe, the value 2500 corresponds to 25%. Defaults to 0 if not provided.

          • taxAmountinteger (int32)optional

            The tax/VAT amount (unitPrice * quantity * taxRate / 10000). Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.

          • grossTotalAmountinteger (int32)required

            The total amount including VAT (netTotalAmount + taxAmount).

          • netTotalAmountinteger (int32)required

            The total amount excluding VAT (unitPrice * quantity).

        • amountinteger (int32)required

          The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.)

        • currencystringrequired

          The currency of the payment, for example 'SEK'.

        • referencestringoptional

          A reference to recognize this order. Usually a number sequence (order number).

    Request body

    {
        "externalBulkChargeId": "string",
        "notifications": {
            "webHooks": [
                {
                    "eventName": "string",
                    "url": "string",
                    "authorization": "string",
                    "headers": null
                }
            ]
        },
        "unscheduledSubscriptions": [
            {
                "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
                "externalReference": "string",
                "order": {
                    "items": [
                        {
                            "reference": "string",
                            "name": "string",
                            "quantity": 0,
                            "unit": "string",
                            "unitPrice": 0,
                            "taxRate": 0,
                            "taxAmount": 0,
                            "grossTotalAmount": 0,
                            "netTotalAmount": 0
                        }
                    ],
                    "amount": 0,
                    "currency": "string",
                    "reference": "string"
                }
            }
        ]
    }

    Responses

    • 202Successoptional
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "bulkId": "50490f2b-98bd-4782-b08d-413ee70aa1f7"
    }

    Retrieve bulk unscheduled charges

    GET /v1/unscheduledsubscriptions/charges/{bulkId}

    Retrieves charges associated with the specified bulk charge operation. The bulkId is returned from Nets in the response of the Bulk charge unscheduled subscriptions method.

    This method supports pagination. Specify the range of subscriptions to retrieve by using either skip and take or pageNumber together with pageSize. The boolean property named more in the response body, indicates whether there are more subscriptions beyond the requested range.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • bulkIdstringrequired

      The identifier of the bulk charge operation that was returned from the Bulk charge unscheduled subscriptions method.

    • skipinteger (int32)optional

      The number of subscription entries to skip from the start. Use this property in combination with the take property.

    • takeinteger (int32)optional

      The maximum number of subscriptions to be retrieved. Use this property in combination with the skip property.

    • pageNumberinteger (int32)optional

      The page number to be retrieved. Use this property in combination with the pageSize property.

    • pageSizeinteger (int32)optional

      The size of each page when specify the range of subscriptions using the pageNumber property.

    Retrieve bulk unscheduled charges

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/charges/%7BbulkId%7D?skip=SOME_INTEGER_VALUE&take=SOME_INTEGER_VALUE&pageNumber=SOME_INTEGER_VALUE&pageSize=SOME_INTEGER_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • pagearrayoptional
        • unscheduledSubscriptionIdstring (uuid)required

          The unscheduled subscription identifier (a UUID) returned from the Retrieve bulk unscheduled subscription charges method.

        • paymentIdstring (uuid)optional

          The payment identifier.

        • chargeIdstring (uuid)optional

          The charge identifier (a UUID) returned from the Charge payment method.

        • statusstringrequired

          The current processing status of the subscription. Possible values are: 'Pending', 'Succeeded', and 'Failed'.

        • messagestringoptional
        • codestringoptional
        • sourcestringoptional
        • externalReferencestringoptional

          An external reference to identify a set of imported subscriptions. This parameter is only used if your unscheduled subscriptions have been imported from a payment platform other than Nets Easy.

      • morebooleanoptional

        Indicates whether there are more subscriptions beyond the requested range.

      • statusstringoptional

        Indicates whether the operation has completed or is still processing subscriptions. Possible values are 'Done' and 'Processing'.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "page": [
            {
                "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
                "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
                "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640",
                "status": "string",
                "message": "string",
                "code": "string",
                "source": "string",
                "externalReference": "string"
            }
        ],
        "more": true,
        "status": "string"
    }

    Verify cards for unscheduled subscriptions

    POST /v1/unscheduledsubscriptions/verifications

    Verifies the specified set of unscheduled subscriptions in bulk. The bulkId returned from a successful request can be used for querying the status of the unscheduled subscriptions.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    Verify cards for unscheduled subscriptions

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/verifications");
    var request = new RestRequest(Method.POST);
    request.AddHeader("content-type", "application/*+json");
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    request.AddParameter("application/*+json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);

    Request body

    • externalBulkVerificationIdstringoptional

      A string that uniquely identifies the verification operation. Use this property for enabling safe retries. Must be between 1 and 64 characters.

    • unscheduledSubscriptionsarrayoptional

      The set of unscheduled subscriptions that should be verified. Each item in the array should define either a unscheduledSubscriptionId or an externalReference, but not both.

      • unscheduledSubscriptionIdstring (uuid)optional

        The identifier of the unscheduled subscription (a UUID). The unscheduledSubscriptionId can be obtained using the Retrieve payment method.

      • externalReferencestringoptional

        An external reference to identify a set of imported subscriptions. This parameter is only used if your subscriptions have been imported from a payment platform other than Nets Easy.

    Request body

    {
        "externalBulkVerificationId": "string",
        "unscheduledSubscriptions": [
            {
                "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
                "externalReference": "string"
            }
        ]
    }

    Responses

    • 202Successoptional
      • bulkIdstring (uuid)required
    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "bulkId": "50490f2b-98bd-4782-b08d-413ee70aa1f7"
    }

    Retrieve bulk verifications for unscheduled subscriptions

    GET /v1/unscheduledsubscriptions/verifications/{bulkId}

    Retrieves verifications associated with the specified bulk unscheduled verification operation. The bulkId is returned from Nets in the response of the Verify unscheduled subscriptions method.

    This method supports pagination. Specify the range of subscriptions to retrieve by using either skip and take or pageNumber together with pageSize. The boolean property named more in the response body, indicates whether there are more subscriptions beyond the requested range.

    Parameters

    • Authorizationstringrequired

      The secret API key.

    • bulkIdstringrequired

      The identifier of the bulk verification operation that was returned from the Verify unscheduled subscriptions method.

    • skipinteger (int32)optional

      The number of unscheduled subscription entries to skip from the start. Use this property in combination with the take property.

    • takeinteger (int32)optional

      The maximum number of unscheduled subscriptions to be retrieved. Use this property in combination with the skip property.

    • pageNumberinteger (int32)optional

      The page number to be retrieved. Use this property in combination with the pageSize property.

    • pageSizeinteger (int32)optional

      The size of each page when specify the range of unscheduled subscriptions using the pageNumber property.

    Retrieve bulk verifications for unscheduled subscriptions

    var client = new RestClient("https://dev-api.dibspayment.eu/v1/unscheduledsubscriptions/verifications/%7BbulkId%7D?skip=SOME_INTEGER_VALUE&take=SOME_INTEGER_VALUE&pageNumber=SOME_INTEGER_VALUE&pageSize=SOME_INTEGER_VALUE");
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
    IRestResponse response = client.Execute(request);

    Responses

    • 200Successoptional
      • pagearrayoptional
        • unscheduledSubscriptionIdstring (uuid)required

          The identifier of the unscheduled subscription (a UUID).

        • externalReferencestringoptional

          An external reference to identify a set of imported unscheduled subscriptions. This parameter is only used if your unscheduled subscriptions have been imported from a payment platform other than Nets Easy.

        • statusstringrequired

          The current processing status of the unscheduled subscription. Possible values are: 'Pending', 'Succeeded', and 'Failed'.

        • paymentIdstring (uuid)optional

          The payment identifier (a UUID).

      • morebooleanoptional

        Indicates whether there are more subscriptions beyond the requested range.

      • statusstringoptional

        Indicates whether the operation has completed or is still processing subscriptions. Possible values are 'Done' and 'Processing'.

    • 400Bad Requestoptional
      • errorsobjectoptional

        An array of error messages.

    • 401Unauthorizedoptional
    • 404Not Foundoptional
    • 500Server Erroroptional
      • messagestringoptional

        An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.

      • codestringoptional

        A numeric error code to be used for debugging purposes.

      • sourcestringoptional

        The source of the error, for example: 'internal'.

    {
        "page": [
            {
                "unscheduledSubscriptionId": "92143051-9e78-40af-a01f-245ccdcd9c03",
                "externalReference": "string",
                "status": "string",
                "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7"
            }
        ],
        "more": true,
        "status": "string"
    }

    Webhooks

    Webhooks are configured per payment and can be specified in the request body of the following methods:


    For a complete reference of all available webhooks in Nets Easy, please see the Webhooks reference page. There is also a guide dedicated to webhooks.