Datastring Parameters

Essential parameters 

The JSON posts that are sent to our API consists of several input parameters which are listed on this page. The parameter type string is limited to 128 characters and you are able to find a complete list of all supported characters here. The parameter type int has a max value of 2,147,483,647 and can not be negative.

 

Items

Parameter Type Description
reference string

The order item reference is usually the SKU (stock keeping unit) of the product.

name string

Define the name of the product.

quantity int

Quantity of the specific product in the order.

unit string

Indicate the quantity of the product.

unitPrice int Price of each product unit. This value should always be sent excluding VAT.
taxRate int

Indicate the VAT rate of the product. The value '2500' is intepreted as 25%. This parameter or 'taxAmount' must be included in your request. Only use one of them.

taxAmount int

This is the total VAT amount for the order line. '10000' is interpreted as '100.00'. This parameter or 'taxRate' must be included in your request. Only use one of them.

grossTotalAmount int

Order line total amount including VAT.

netTotalAmount int

Order line total amount excluding VAT.

 

 

Order

Parameter Type Description
amount int

Total amount for the order including VAT. Please note that the order amount must match the sum of all grossTotalAmount in order.

currency string

Currency of the amount. Use the 3-letter (ISO-4217) code.

reference string

Order ID which will be visible in Easy administration.

 

 

Checkout

Parameter Type Description
url string

This is the URL where the checkout is located at, and where we will send the user after they have preformed a 3-D Secure verification. Read more about the checkout integration at -insert link here- .

 

 

Consumer

Parameter Type Description
reference string

...

email string

The consumer email address.

postalCode string

The consumer postal code (zip code). Maximum of 12 characters.

country string

The consumer country.

 

 

Phone

Parameter Type Description
prefix string

The international prefix of the phone number, such as +46 for Swedish telephone numbers.

number string

The rest of the telephone number excluding the prefix. Example: 701234567

postalCode string

The consumer postal code (zip code). Maximum of 12 characters.

country string

The consumer country.

 

 

Webhooks

Parameter Type Description
eventName string

The event that should trigger the webHook.

url string

The URL which will be triggered when the event is fired.

 

 

Example request

POST /payments
{
	[Required]
  "order": {
    [1..N]
	"items": [
      {
        "reference": "",
        "name": "Product 1",
        "quantity": 0,
        "unit": "",
        "unitPrice": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "grossTotalAmount": "",
        "netTotalAmount": ""
      }
    ],
	[Required]
	//total amount for order (Number to be displayed in checkout)
    "amount": 133700,
	[Required]
	//Currency for payment
	"currency": "SEK",
    [Required]
	//Order reference provided by merchant  
	"reference": "Merchant Order Ref"
  },
  [Required]
  "checkout": {
    [Required]
	//Used for security purposes, and used to redirect consumer back after 3D-secure
	"url": "foobar",
    //consumer information
	"consumer": {
	  //merchant consumer reference
      "reference": "Test",
      //consumer email
	  "email": "test@test.com",
      //consumer phone number
	  "phone": "+46909090",
      //consumer postalCode
	  "postalCode": "12345",
      //consumer country
	  "country": "SE"
    }
  },
  //Used by partner to specify merchant
  "merchantId": "",
  //Notifications for various events
  "notifications": {
    "webHooks": [
      {
        //Predefined event type
		[Required if webHooks is used]
		"eventName": "consumer.added",
        //endpoint to be notified about the event
		[Required if webHooks is used]
		"url": "http://url.com"
      }
    ]
  }
}

return 
{
//Used to initiate embedded payment 
  "paymentId": "string"
}




GET /payments/{paymentId}

{
  "payment": {
    "summary": {
      "reservedAmount": 0,
      "chargedAmount": 0,
      "refundedAmount": 0,
      "cancelledAmount": 0
    },
    "consumer": {
      "billingAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "receiverLine": "string",
        "postalCode": "string",
        "city": "string",
        "country": "string"
      },
      "shippingAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "receiverLine": "string",
        "postalCode": "string",
        "city": "string",
        "country": "string"
      },
      "company": {
        "name": "string",
        "organisationNumber": "string",
        "email": "string",
        "phoneNumber": "string",
		//reference to logged in consumer on merchant site
        "merchantReference": "string"
      },
      "privatePerson": {
        "dateOfBirth": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNumber": "string",
		//reference to logged in consumer on merchant site
        "merchantReference": "string"
      }
    },
    "paymentDetails": {
	  //Card or invoice
      "paymentType": "string",
	  //If card - MasterCard/Visa, if invoice - Arvato
      "paymentMethod": "string",
      //Returned if invoice
	  "invoiceDetails": {
        "invoiceNumber": "string",
        "ocr": "string",
        "pdfLink": "string",
        "dueDate": "2016-11-04T13:26:25.723Z"
      },
	  //Returned if card
      "cardDetails": {
        "maskedPan": "string",
        "expiryDate": "string"
      }
    }
  }
}

POST /charges/{chargeId}/refunds

{
  [Required]
  //Amount to be cancelled
  "amount": 0,
  [Required]
  //Used to specify items to be cancelled
  "orderItems": [
    {
      "reference": "string",
      "name": "string",
      "quantity": 0,
      "unit": "string",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": "string",
      "netTotalAmount": "string"
    }
  ]
}
return
{
 //Used to cancel a pending refund 
  "refundId": "string"
}


POST /payments/{paymentId}/charges
{
  [Required]
  //specify amount to be charged
  "amount": 0,
  [Required]
  //Specify which items are being charged
  "orderItems": [
    {
      "reference": "string",
      "name": "string",
      "quantity": 0,
      "unit": "string",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": "string",
      "netTotalAmount": "string"
    }
  ]
}

return
{
  //Used to refund a charge
  "chargeId": "string",
  //Returned if invoice is the payment method
  "invoice": {
    "invoiceNumber": "string"
  }
}


POST /payments/{paymentId}/cancel
{
  [Required]
  //Amount to be cancelled
  "amount": 0,
  [Required]
  //Specify which items are being cancelled
  "orderItems": [
    {
      "reference": "string",
      "name": "string",
      "quantity": 0,
      "unit": "string",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": "string",
      "netTotalAmount": "string"
    }
  ]
}


POST pending-refunds/{refundId}/cancel
Do you have question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00