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.
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.
- 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.
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
grossTotalAmount
s 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 thehostedPaymentPageUrl
provided in the response body. Using a hosted checkout page requires that you specify thereturnUrl
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 theurl
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) withshipping.costSpecified
set totrue
before the customer can complete a purchase. Defaults tofalse
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 tofalse
, 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 totrue
.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 isfalse
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 isfalse
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 aprivatePerson
or acompany
, 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 istrue
when using aHostedPaymentPage
.showOrderSummarybooleanoptional
If set to
true
, displays the order summary above the checkout. Default value istrue
when using aHostedPaymentPage
.
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'.
- 201
- 400
- 500
{ "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
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'.
- 200
- 400
- 500
{ "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'.
- 400
- 500
{ "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'.
- 400
- 500
{ "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'.
- 400
- 500
{ "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'.
- 400
- 500
{ "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'.
- 400
- 500
{ "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 theorderItems
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'.
- 201
- 400
- 402
- 500
{ "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'.
- 200
- 400
- 500
{ "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 theorderItems
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'.
- 201
- 400
- 500
{ "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'.
- 201
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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'.
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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.
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 anexternalReference
, 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
grossTotalAmount
s 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'.
- 202
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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 anexternalReference
, 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'.
- 202
- 400
- 500
{ "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.
This method supports pagination. Specify the range of subscriptions to retrieve by using either skip
and take
or pageNumber
together with pageSize
. The boolean property named more
in the response body, indicates whether there are more subscriptions beyond the requested range.
Parameters
Authorizationstringrequired
The secret API key.
bulkIdstringrequired
The identifier of the bulk verification operation that was returned from the Verify 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'.
- 200
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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'.
- 200
- 400
- 500
{ "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
grossTotalAmount
s 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'.
- 200
- 400
- 500
{ "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.
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 anexternalReference
, 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
grossTotalAmount
s 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'.
- 202
- 400
- 500
{ "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.
This method supports pagination. Specify the range of subscriptions to retrieve by using either skip
and take
or pageNumber
together with pageSize
. The boolean property named more
in the response body, indicates whether there are more subscriptions beyond the requested range.
Parameters
Authorizationstringrequired
The secret API key.
bulkIdstringrequired
The identifier of the bulk charge operation that was returned from the Bulk charge unscheduled subscriptions method.
skipinteger (int32)optional
The number of subscription entries to skip from the start. Use this property in combination with the
take
property.takeinteger (int32)optional
The maximum number of subscriptions to be retrieved. Use this property in combination with the
skip
property.pageNumberinteger (int32)optional
The page number to be retrieved. Use this property in combination with the
pageSize
property.pageSizeinteger (int32)optional
The size of each page when specify the range of subscriptions using the
pageNumber
property.
Retrieve bulk unscheduled charges
- 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'.
- 200
- 400
- 500
{ "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 anexternalReference
, 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'.
- 202
- 400
- 500
{ "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.
This method supports pagination. Specify the range of subscriptions to retrieve by using either skip
and take
or pageNumber
together with pageSize
. The boolean property named more
in the response body, indicates whether there are more subscriptions beyond the requested range.
Parameters
Authorizationstringrequired
The secret API key.
bulkIdstringrequired
The identifier of the bulk verification operation that was returned from the Verify unscheduled subscriptions method.
skipinteger (int32)optional
The number of unscheduled subscription entries to skip from the start. Use this property in combination with the
take
property.takeinteger (int32)optional
The maximum number of unscheduled subscriptions to be retrieved. Use this property in combination with the
skip
property.pageNumberinteger (int32)optional<