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 Nexi Group 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. Checkout enables customers to collect customer data if the customer's consent is obtained. This data makes future purchases easier. Checkout 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.

C#PHPNodeShell

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. \n\n Important note: By default, our system does not automatically charge/capture the amount which has been reserved. Depending on your business model, you should decide on the way how to handle this process. It is our recommendation to do the setup for immediate charge/capture.

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. Entering the amount 100 corresponds to 1 unit of the currency entered, such as e.g. 1 NOK. 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 Nexi Group. 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.
Charge set to true so you can enable autocapture for subscriptions.

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

C#
PHP
Node
Shell

var client = new RestClient("https://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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - quantitynumber (double)required
    The quantity of the product. The value can not be negative.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
  - unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
  - taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
  - imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
- amountinteger (int32)required
  The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.) Must be higher than 0.
- currencystringrequired
  The currency of the payment, for example 'SEK'. The following special characters are not supported: <, >, ', ", &, \
- referencestringoptional
  A reference to recognize this order. Usually a number sequence (order number). The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
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. The maximum length is 256 characters. The following special characters are not supported: `<,>,’,”,\
- integrationTypestringoptional
  Determines whether the checkout should be embedded in your webshop or if the checkout should be hosted by Nexi Group 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 initiating the consumer data of the payment object. See also the property merchantHandlesConsumerData which controls what fields to show on the checkout page.
  - referencestringoptional
    The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &,
    ///
  - emailstringoptional
    The email address.
  - shippingAddressobjectoptional
    The address of a customer (private or business). This parameter will become required whenever the shippingAddress is being used.
    addressLine1stringoptional
    The primary address line. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    addressLine2stringoptional
    An additional address line. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    postalCodestringoptional
    The postal code. Postal codes per each country: NOR, NO - A four-digit code, for example, 0025. SWE, SE - A five-digit code, for example, 11455. DNK, DK - A four-digit code, for example, 2600. Other - Must be between 1 and 12 characters, the following special characters are not supported: <, >, ', ", &, \
    citystringoptional
    The city. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    countrystringoptional
    A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported countries. The following special characters are not supported: <, >, ', ", &, \
  - billingAddressobjectoptional
    The address of a customer (private or business). This parameter will become required whenever the shippingAddress is being used.
    addressLine1stringoptional
    The primary address line. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    addressLine2stringoptional
    An additional address line. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    postalCodestringoptional
    The postal code. Postal codes per each country: NOR, NO - A four-digit code, for example, 0025. SWE, SE - A five-digit code, for example, 11455. DNK, DK - A four-digit code, for example, 2600. Other - Must be between 1 and 12 characters, the following special characters are not supported: <, >, ', ", &, \
    citystringoptional
    The city. Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    countrystringoptional
    A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported countries. The following special characters are not supported: <, >, ', ", &, \
  - phoneNumberobjectoptional
    An international phone number.
    prefixstringoptional
    The country calling code, for example 001. Pattern: @ ^[+]\\d{1,3}$.
    numberstringoptional
    The phone number (without the country code prefix). Pattern: @ ^[0-9]*$
  - privatePersonobjectoptional
    The name of a natural person.
    firstNamestringoptional
    The first name (also known as given name). Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    lastNamestringoptional
    The last name (also known as surname/family name). Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
  - companyobjectoptional
    A business consumer.
    namestringoptional
    The name of the company. Must be between 1 and 128 characters.
    contactobjectoptional
    The name of a natural person.
    firstNamestringoptional
    The first name (also known as given name). Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
    lastNamestringoptional
    The last name (also known as surname/family name). Must be between 1 and 128 characters. The following special characters are not supported: <, >, ', ", &, \
- termsUrlstringrequired
  The URL to the terms and conditions of your webshop. The following special characters are not supported: <,>,’,”,\\
- merchantTermsUrlstringoptional
  The URL to the privacy and cookie settings of your webshop. The following special characters are not supported: `<,>,’,”,\
- 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.
  - countryCodestringoptional
    A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported countries. Important: For Klarna payments, the countryCode field is mandatory. If not provided, Klarna will not be available as a payment method. The following special characters are not supported: <, >, ', ", &, \
- shippingobjectoptional
  - countriesarrayoptional
    countryCodestringoptional
    A three-letter country code (ISO 3166-1), for example GBR. See also the list of supported countries. Important: For Klarna payments, the countryCode field is mandatory. If not provided, Klarna will not be available as a payment method. The following special characters are not supported: <, >, ', ", &, \
  - 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. It is possible to exclude all consumer and company information from the payment (only for certain payment methods) when it is set to true. If you still want to add consumer information to the payment you need to use the 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. Important: For Klarna payments, the countryCode field is mandatory. If not provided, Klarna will not be available as a payment method. The following special characters are not supported: <, >, ', ", &, \
merchantNumberstringoptional
The merchant number. Use this header only if you are a Nexi Group 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.
  - eventNamestringrequired
    The name of the event you want to subscribe to. See webhooks for the complete list of events. The following special characters are not supported: <, >, ', ", &, \
  - urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. The maximum allowed length of the URL is 256 characters. The following special characters are not supported: <, >, ', ", &, \
  - authorizationstringoptional
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 64 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. All available and configured payment methods are enabled by default.
- namestringoptional
  The name of the payment method or payment type to be configured for payment. 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", "Forbrugsforeningen", "PayPal", "Vipps", "MobilePay", "Swish", "Arvato", "EasyInvoice", "EasyInstallment", "EasyCampaign", "RatePayInvoice", "RatePayInstallment", "RatePaySepa", "Sofort", "Trustly", "ApplePay", "Klarna", "GooglePay". 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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - quantitynumber (double)required
    The quantity of the product. The value can not be negative.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
  - unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
  - taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
  - imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
myReferencestringoptional
Merchant payment reference The maximum length is 36 characters. The following special characters are not supported: <, >, ', ", &, \
additionalPaymentMethodDataobjectoptional
- rivertyobjectoptional
  - orderReferencestringoptional
    Optional order reference that is later mapped to the parentTransactionReference in Riverty. It must be unique across all payments and have a length less than 128 characters.
- payPalobjectoptional
  - orderReferencestringoptional
    Order reference that is later mapped to the InvoiceId in PayPal. If not provided we will generate it ourselves. It must be unique across all payments and have a length less than 128 characters.

Request body

{
    "order": {
        "items": [
            {
                "reference": "string",
                "name": "string",
                "quantity": 0.1,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0,
                "imageUrl": "string"
            }
        ],
        "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"
            },
            "billingAddress": {
                "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.1,
                "unit": "string",
                "unitPrice": 0,
                "taxRate": 0,
                "taxAmount": 0,
                "grossTotalAmount": 0,
                "netTotalAmount": 0,
                "imageUrl": "string"
            }
        }
    ],
    "myReference": "string",
    "additionalPaymentMethodData": {
        "riverty": {
            "orderReference": "string"
        },
        "payPal": {
            "orderReference": "string"
        }
    }
}

Responses

201Createdoptional
- 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
500Internal Server 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 Nexi Group when creating a payment object.

Parameters

Authorizationstringrequired
The secret API key.
paymentIdstringrequired
The payment identifier.
CommercePlatformTagstringoptional
An identifier of the ecommerce platform.

Retrieve payment

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}");
var request = new RestRequest(Method.GET);
request.AddHeader("CommercePlatformTag", "SOME_STRING_VALUE");
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200OKoptional
- 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.
    phoneNumberobjectoptional
    An international phone number.
    prefixstringoptional
    The country calling code, for example 001. Pattern: @ ^[+]\\d{1,3}$.
    numberstringoptional
    The phone number (without the country code prefix). Pattern: @ ^[0-9]*$
    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. Pattern: @ ^[+]\\d{1,3}$.
    numberstringoptional
    The phone number (without the country code prefix). Pattern: @ ^[0-9]*$
    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. Pattern: @ ^[+]\\d{1,3}$.
    numberstringoptional
    The phone number (without the country code prefix). Pattern: @ ^[0-9]*$
    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.
    phoneNumberobjectoptional
    An international phone number.
    prefixstringoptional
    The country calling code, for example 001. Pattern: @ ^[+]\\d{1,3}$.
    numberstringoptional
    The phone number (without the country code prefix). Pattern: @ ^[0-9]*$
  - 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
    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: MMYY.
  - orderDetailsobjectrequired
    amountinteger (int32)required
    The total amount of the order, for example 10000. Must be higher than 0.
    currencystringrequired
    The currency of the payment, for example 'SEK'. The following special characters are not supported: <, >, ', ", &, \
    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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    quantitynumber (double)required
    The quantity of the product. The value can not be negative.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
    unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
    taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
    imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
  - 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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    quantitynumber (double)required
    The quantity of the product. The value can not be negative.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
    unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
    taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
    imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
  - 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
500Internal Server 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",
                "phoneNumber": {
                    "prefix": "string",
                    "number": "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",
                "phoneNumber": {
                    "prefix": "string",
                    "number": "string"
                }
            }
        },
        "paymentDetails": {
            "paymentType": "string",
            "paymentMethod": "string",
            "invoiceDetails": {
                "invoiceNumber": "string"
            },
            "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.1,
                        "unit": "string",
                        "unitPrice": 0,
                        "taxRate": 0,
                        "taxAmount": 0,
                        "grossTotalAmount": 0,
                        "netTotalAmount": 0,
                        "imageUrl": "string"
                    }
                ]
            }
        ],
        "charges": [
            {
                "chargeId": "aec0aceb-a4db-49fb-b366-75e90229c640",
                "amount": 0,
                "created": "2019-08-24T14:15:22Z",
                "orderItems": [
                    {
                        "reference": "string",
                        "name": "string",
                        "quantity": 0.1,
                        "unit": "string",
                        "unitPrice": 0,
                        "taxRate": 0,
                        "taxAmount": 0,
                        "grossTotalAmount": 0,
                        "netTotalAmount": 0,
                        "imageUrl": "string"
                    }
                ]
            }
        ],
        "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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
405Method Not Allowedoptional
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- namestringrequired
  The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- quantitynumber (double)required
  The quantity of the product. The value can not be negative.
- unitstringrequired
  The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
- unitPriceinteger (int32)required
  The price per unit excluding VAT. Note: The amount can be negative.
- taxRateinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
- grossTotalAmountinteger (int32)required
  The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
- netTotalAmountinteger (int32)required
  The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
- imageUrlstringoptional
  Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - quantitynumber (double)required
    The quantity of the product. The value can not be negative.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
  - unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
  - taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
  - imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.

Request body

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

Responses

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
405Method Not Allowedoptional
500Internal Server 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. The myReference can be used if you want to create a myReference ID that can be used in your own accounting system to keep track of the actions connected to the payment.

Parameters

Authorizationstringrequired
The secret API key.
paymentIdstringrequired
The payment identifier.
CommercePlatformTagstringoptional
An identifier of the ecommerce platform.

Update myReference

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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 The maximum length is 36 characters. The following special characters are not supported: <, >, ', ", &, \

Request body

{
    "myReference": "string"
}

Responses

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
405Method Not Allowedoptional
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
405Method Not Allowedoptional
409Conflictoptional
500Internal Server 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.
Nexi Group 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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)required
The amount to be canceled. Must be higher than 0.
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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- namestringrequired
  The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- quantitynumber (double)required
  The quantity of the product. The value can not be negative.
- unitstringrequired
  The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
- unitPriceinteger (int32)required
  The price per unit excluding VAT. Note: The amount can be negative.
- taxRateinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
- grossTotalAmountinteger (int32)required
  The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
- netTotalAmountinteger (int32)required
  The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
- imageUrlstringoptional
  Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.

Request body

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

Responses

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
405Method Not Allowedoptional
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- namestringrequired
  The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- quantitynumber (double)required
  The quantity of the product. The value can not be negative.
- unitstringrequired
  The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
- unitPriceinteger (int32)required
  The price per unit excluding VAT. Note: The amount can be negative.
- taxRateinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
- grossTotalAmountinteger (int32)required
  The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
- netTotalAmountinteger (int32)required
  The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
- imageUrlstringoptional
  Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
shippingobjectoptional
- trackingNumberstringoptional
  The maximum length is 255 characters.
- providerstringoptional
  The maximum length is 4 characters.
finalChargebooleanoptional
Flag to release remaining reservation
myReferencestringoptional
Merchant payment reference The maximum length is 36 characters. The following special characters are not supported: <, >, ', ", &, \
paymentMethodReferencestringoptional
An optional unique reference per payment method, its usage and restrictions are relevant to the payment method used in reserving the payment. Ignored if not specified, otherwise it gets passed to the payment method provider during capturing the payment. Currently, it affects the following payment methods:

Riverty/AfterPay/Arvato: It signifies the Riverty invoice number which must be unique and have a maximum character limit of 20.

Request body

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

Responses

201Createdoptional
- chargeIdstringrequired
- invoiceobjectoptional
  - invoiceNumberstringoptional
    The invoice number.
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
402Payment Requiredoptional
- 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'.
500Internal Server 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}

Parameters

Authorizationstringrequired
The secret API key.
chargeIdstringrequired
The identifier of the existing charge (a UUID).

Retrieve charge

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/charges/{chargeId}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200OKoptional
- 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
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/charges/{chargeId}/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 Must be higher than 0.
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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- namestringrequired
  The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- quantitynumber (double)required
  The quantity of the product. The value can not be negative.
- unitstringrequired
  The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
- unitPriceinteger (int32)required
  The price per unit excluding VAT. Note: The amount can be negative.
- taxRateinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
- grossTotalAmountinteger (int32)required
  The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
- netTotalAmountinteger (int32)required
  The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
- imageUrlstringoptional
  Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
myReferencestringoptional
Merchant payment reference

Request body

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

Responses

201Createdoptional
- refundIdstringrequired
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
500Internal Server 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"
}

Refund payment

POST /v1/payments/{paymentId}/refunds

Refunds a previously settled payment. The refunded amount will be transferred back to the customer's account.

A settled payment can be fully or partially refunded, this end-point is not supported for these payment methods:

Arvato
PayPal
RatePayInvoice
RatePaySepa
RatePayInstallment
EasyInvoice
EasyCampaign
EasyInstallment

Parameters

Authorizationstringrequired
The secret API key.
paymentIdstringrequired
Idempotency-Keystringoptional
A string that uniquely identifies the refund you are attempting. Must be between 1 and 64 characters.
CommercePlatformTagstringoptional
An identifier of the ecommerce platform.

Refund payment

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/payments/{paymentId}/refunds");
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, for example 10000 Must be higher than 0.
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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- namestringrequired
  The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
- quantitynumber (double)required
  The quantity of the product. The value can not be negative.
- unitstringrequired
  The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
- unitPriceinteger (int32)required
  The price per unit excluding VAT. Note: The amount can be negative.
- taxRateinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
- grossTotalAmountinteger (int32)required
  The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
- netTotalAmountinteger (int32)required
  The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
- imageUrlstringoptional
  Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
myReferencestringoptional
Merchant payment reference

Request body

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

Responses

201Createdoptional
- refundIdstringrequired
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
500Internal Server 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 Nexi Group 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/refunds/{refundId}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200OKoptional
- refundIdstring (uuid)required
  The refund identifier (a UUID).
- amountinteger (int32)required
  The amount, for example 10000. Must be higher than 0.
- 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
500Internal Server 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

C#
PHP
Node
Shell

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

Responses

204No Contentoptional
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
405Method Not Allowedoptional
500Internal Server 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 Nexi Group 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

C#
PHP
Node
Shell

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

Responses

200OKoptional
- 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: MMYY.
    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
500Internal Server 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 Checkout. Subscriptions created within Checkout 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 Nexi Group 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

C#
PHP
Node
Shell

var client = new RestClient("https://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

200OKoptional
- 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: MMYY.
    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
500Internal Server 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 Nexi Group 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

C#
PHP
Node
Shell

var client = new RestClient("https://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.
  - eventNamestringrequired
    The name of the event you want to subscribe to. See webhooks for the complete list of events. The following special characters are not supported: <, >, ', ", &, \
  - urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. The maximum allowed length of the URL is 256 characters. The following special characters are not supported: <, >, ', ", &, \
  - authorizationstringoptional
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 64 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 Checkout.
- 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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    quantitynumber (double)required
    The quantity of the product. The value can not be negative.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
    unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
    taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
    imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
  - amountinteger (int32)required
    The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.) Must be higher than 0.
  - currencystringrequired
    The currency of the payment, for example 'SEK'. The following special characters are not supported: <, >, ', ", &, \
  - referencestringoptional
    A reference to recognize this order. Usually a number sequence (order number). The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \

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.1,
                        "unit": "string",
                        "unitPrice": 0,
                        "taxRate": 0,
                        "taxAmount": 0,
                        "grossTotalAmount": 0,
                        "netTotalAmount": 0,
                        "imageUrl": "string"
                    }
                ],
                "amount": 0,
                "currency": "string",
                "reference": "string"
            }
        }
    ]
}

Responses

202Acceptedoptional
- bulkIdstring (uuid)required
  The bulk charge identifier (a UUID). This identifier can be used when retrieving all charges associated with a bulk charge operation.
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
500Internal Server 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 Nexi Group 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 Nexi Group 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/subscriptions/charges/{bulkId}?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

200OKoptional
- 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 Checkout.
- 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
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://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 Checkout.

Request body

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

Responses

202Acceptedoptional
- bulkIdstring (uuid)required
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
500Internal Server 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 Nexi Group in the response of the Verify subscriptions method.

Parameters

Authorizationstringrequired
The secret API key.
bulkIdstringrequired
The identifier of the bulk verification operation that was returned from the Verify 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/subscriptions/verifications/{bulkId}?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

200OKoptional
- 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 Checkout.
  - statusstringrequired
    The current processing status of the subscription. Possible values are: 'Pending', 'Succeeded', and 'Failed'.
  - messagestringoptional
  - codestringoptional
  - 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
500Internal Server 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",
            "message": "string",
            "code": "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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/unscheduledsubscriptions/{unscheduledSubscriptionId}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200OKoptional
- 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: MMYY.
    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
500Internal Server 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 Checkout. Unscheduled subscriptions created within Checkout 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

C#
PHP
Node
Shell

var client = new RestClient("https://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

200OKoptional
- 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: MMYY.
    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
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/unscheduledsubscriptions/{unscheduledSubscriptionId}/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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
  - quantitynumber (double)required
    The quantity of the product. The value can not be negative.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
  - unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
  - taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
  - imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
- amountinteger (int32)required
  The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.) Must be higher than 0.
- currencystringrequired
  The currency of the payment, for example 'SEK'. The following special characters are not supported: <, >, ', ", &, \
- referencestringoptional
  A reference to recognize this order. Usually a number sequence (order number). The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
notificationsobjectoptional
Notifications allow you to subscribe to status updates for a payment.
- webHooksarrayoptional
  The list of webhooks. The maximum number of webhooks is 32.
  - eventNamestringrequired
    The name of the event you want to subscribe to. See webhooks for the complete list of events. The following special characters are not supported: <, >, ', ", &, \
  - urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. The maximum allowed length of the URL is 256 characters. The following special characters are not supported: <, >, ', ", &, \
  - authorizationstringoptional
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 64 characters long and contain alphanumeric characters.

Request body

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

Responses

200OKoptional
- 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
402Payment Requiredoptional
404Not Foundoptional
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://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.
  - eventNamestringrequired
    The name of the event you want to subscribe to. See webhooks for the complete list of events. The following special characters are not supported: <, >, ', ", &, \
  - urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. The maximum allowed length of the URL is 256 characters. The following special characters are not supported: <, >, ', ", &, \
  - authorizationstringoptional
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 64 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 unscheduled subscriptions have been imported from a payment platform other than Checkout.
- 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). The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    namestringrequired
    The name of the product. The maximum length is 128 characters. The following special characters are not supported: <,>,\\
    quantitynumber (double)required
    The quantity of the product. The value can not be negative.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg. The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \
    unitPriceinteger (int32)required
    The price per unit excluding VAT. Note: The amount can be negative.
    taxRateinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT rate (in percentage times 100). For example, the value 2500 corresponds to 25%. Defaults to 0 if not provided. Must be between 0 and 99999.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount). Note: The amount can be negative.
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity). Note: The amount can be negative.
    imageUrlstringoptional
    Url to image of the product. Meant to be configured before checkout is completed. Ignored on later operations like charging, refunding etc. Currently affecting: Riverty Invoice. Supported size: width and height between 100 pixels and 1280 pixels. Supported formats: gif, jpeg(jpg), png, webp.
  - amountinteger (int32)required
    The total amount of the order including VAT, if any. (Sum of all grossTotalAmounts in the order.) Must be higher than 0.
  - currencystringrequired
    The currency of the payment, for example 'SEK'. The following special characters are not supported: <, >, ', ", &, \
  - referencestringoptional
    A reference to recognize this order. Usually a number sequence (order number). The maximum length is 128 characters. The following special characters are not supported: <, >, ', ", &, \

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.1,
                        "unit": "string",
                        "unitPrice": 0,
                        "taxRate": 0,
                        "taxAmount": 0,
                        "grossTotalAmount": 0,
                        "netTotalAmount": 0,
                        "imageUrl": "string"
                    }
                ],
                "amount": 0,
                "currency": "string",
                "reference": "string"
            }
        }
    ]
}

Responses

202Acceptedoptional
- bulkIdstring (uuid)required
  The bulk charge identifier (a UUID). This identifier can be used when retrieving all charges associated with a bulk charge operation.
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
401Unauthorizedoptional
404Not Foundoptional
500Internal Server 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 Nexi Group in the response of the Bulk charge unscheduled subscriptions method.

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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/unscheduledsubscriptions/charges/{bulkId}?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

200OKoptional
- 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 Checkout.
- 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
500Internal Server 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

C#
PHP
Node
Shell

var client = new RestClient("https://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 unscheduled subscriptions have been imported from a payment platform other than Checkout.

Request body

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

Responses

202Acceptedoptional
- bulkIdstring (uuid)required
400Bad Requestoptional
- errorsobjectoptional
  An array of error messages.
500Internal Server 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 Nexi Group in the response of the Verify unscheduled subscriptions method.

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

C#
PHP
Node
Shell

var client = new RestClient("https://api.dibspayment.eu/v1/unscheduledsubscriptions/verifications/{bulkId}?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

200OKoptional
- 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'.
  - messagestringoptional
  - codestringoptional
  - 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
500Internal Server 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",
            "message": "string",
            "code": "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:

Create payment using the notifications property.
Charge subscription using the notifications property.

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