Introduction
Welcome to Dinit's API documentation page!
This page contains descriptions of procedures that allow selected 3rd party partners to access the information required for their further business operations.
Please contact us through your project mananger if you have any additional questions regarding APIs usage.
We kindly ask you to use APIs responsibly and promptly report any unexpected behaviour, data leaks or security issues. Our goal is to keep the platform as open as possible to enable smooth development on your side, but at the same time our priority remains safety of our customers. We hope that our priorities align for the benefit of all stakeholders!
Dinit d.o.o. Dev Team!
This API documentation page was created with Slate
API Versioning
Each request contains an API version description. We denote palceholder for this description with <VERSION>
. Versions will be denoted by the letter v
and an incremental number: v1
, v2
, etc.
Example: <BASE_URL>/stateless/api/v1/…
Information about changes and API documentation for new versions will be provided on this page.
How to Form URL?
There are 4 elements that are present in all URL's. These are:
BASE_URL
: URL where the API is hosted, example:https://apisubdomain.dinitcs.com/
. Value for each environment (dev, uat, prod) will be provided to the project mananger.VERSION
: Version number (something likev1
), see API versioning for more.BANK_SIGN
: Unique Bank ID. Curently applicable values aredcChChf
anddcChEur
. Single customer may have accounts and hence cards with severalBANK_SIGN
values.CUSTOMER_CODE
: Unique customer ID. This value is used to determine which information can be returned to the caller.
Naming Conventions
Here we will document frequently used words and describe any obscure fields should they appear.
- AS - Authorization System
- DCMS - Dinit Card Managment System
Response Format
Standard paginated output:
{
"output": [
{
"RequestedObjectNumber": 1
},
{
"RequestedObjectNumber": 2
},
{
"RequestedObjectNumber": 3
}
],
"perPage": 3,
"pageNumber": 1,
"total": 100
}
Response body is formatted in the JSON
format.
Pagination
Sometimes queries return amount of data that is too big to be sent via single response (e.g. corporate accouts with thousands of cards). Because of this GET APIs that return multiple objects return them in a paginated response. These APIs always have an optional pageNumber
and perPage
query parameters.
Pagination Query Parameters:
Parameter | Type | Default Value | Description |
---|---|---|---|
pageNumber |
int | 1 | Which page to return. Counter starts at 1 |
perPage |
int | 5 | Number of objects returned in one response |
Note
- API returns objects in range [(pageNumber-1)*perPage+1, pageNumber*perPage]
- API will return empty response if the return range is bigger than the
total
number of objects available
Authentication
Every request requires following headers
Key | Type | Value |
---|---|---|
ts |
dateTime | dateTime when the request is made |
user |
string | ID of the caller |
token |
string | Authentication token |
Token generation is disscused through secure channels.
Accounts
This endpoint provides information about customer's accounts and returns data needed for further queries about cards and transactions.
Customer can have several accounts and each account can have several cards linked to it. Custumer can be a person using card for private purposes (private customer) or a business entity (corporate customer).
Get All Accounts
API returns JSON structured like this:
{
"output": [
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"currency": "CHF",
"rights": {
"canSeePayments": true,
"canSeeRewards": false,
"canSeeStatements": true,
"hasPaperless": false,
}
},
{
"bankSign": "dcChChf",
"accountNumber": "1230000022",
"customerCode": "992500123456",
"currency": "CHF",
"rights": {
"canSeePayments": false,
"canSeeRewards": false,
"canSeeStatements": true,
"hasPaperless": false,
}
},
{
"bankSign": "dcChChf",
"accountNumber": "1230000033",
"customerCode": "992500123456",
"currency": "CHF",
"rights": {
"canSeePayments": true,
"canSeeRewards": true,
"canSeeStatements": true,
"hasPaperless": true,
}
}
],
"perPage": 3,
"pageNumber": 1,
"total": 20
}
This endpoint retreives all accounts based on the custumer code.
Optionally query can be narrowed down to a set of account numbers by appending one or more accountNumber=<ACCOUNT_NUMBER>
parameters to the URL.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/accounts/<BANK_SIGN>/<CUSTOMER_CODE>
Optional Query Parameters
Parameter | Type | Default | Description |
---|---|---|---|
accountNumber |
string | all accounts | Uniqe account ID. Length depends on the franchise |
pageNumber |
int | 1 | see pagination input |
perPage |
int | 5 | see pagination input |
Get a Specific Account
API returns JSON structured like this:
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"currency": "CHF",
"rights": {
"canSeePayments": true,
"canSeeRewards": false,
"canSeeStatements": true,
"hasPaperless": false,
}
}
This endpoint retrieves a specific account based on the account number.
Simply append the desired account number to the URL of the request above.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/accounts/<BANK_SIGN>/<CUSTOMER_CODE>/<ACCOUNT_NUMBER>
URL Parameters
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID. Length depends on the franchise |
Account API Field Description
Field | Type | Description |
---|---|---|
bankSign |
string | Unique bank ID. See BANK_SIGN |
accountNumber |
string | Unique account ID. |
customerCode |
string | Unique customer ID, this is the ID of the account's owner. See CUSTOMER_CODE for more details |
currency |
string | Primary currency for the account. 3 letter code according to ISO 4217 |
Account Rights Field Description
Field | Type | Description |
---|---|---|
canSeePayments |
bool | Not Applicable |
canSeeRewards |
bool | Not Applicable |
canSeeStatements |
bool | Not Applicable |
hasPaperless |
bool | Not Applicable |
Balance
This endpoint provides information about account balance.
Balance is always connected to an account and not to a specific card! In credit card business positive balance means the amount spent on the credit card, this is the opposite of the banking sense where balance is the amount of money on the account!
Get Balance for a Specific Account
API returns JSON structured like this:
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"currency": "CHF",
"balance": 1013.99,
"pendingBalance": 514.20,
"openToBuy": 1471.81
}
This endpoint retrieves balance information for a specific account based on the account number. Simply append /balance
to the URL of the request above.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/accounts/<BANK_SIGN>/<CUSTOMER_CODE>/<ACCOUNT_NUMBER>/balance
URL Parameters
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID. Length depends on the franchise |
Balance API Field Description
Fields are same as in the Account API Field Description. New fields:
Field | Type | Description |
---|---|---|
balance |
string | Current outstanding balance: sum of all transactions and fees |
pendingBalance |
string | Pending balance: sum of all authorizations amounts |
openToBuy |
string | How much can be spent on the account based on the current information about balance, pending balance and limit. open to buy = limit - (balance + pending balace) |
Cards
This endpoint provides all the necessary information about cards.
Customer can have several types of cards linked to different accounts and vice versa account can have several cards linked to it, furthermore each of those cards can have a different customer as its owner.
Get All Cards
API returns JSON structured like this:
{
"output": [
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"cardCustomerCode": "982500789123",
"cardToken": "3609611000000010005",
"isVirtual":false,
"embosing": {
"ownerName": "JOHN DOE",
"embosingOptional": "MEGA CORP INC.",
"productName": "Business Exclusive",
"imageUrl": "api/cardimages/CH/businesexclusive.png",
"creationDate": "2013-11-28T00:00:00+01:00",
"expiryDate": "2019-11-30T00:00:00+01:00",
},
"rights": {
"canChangePin": true,
"hasSmsAlert": true,
"canSetBlock": true,
},
"status": {
"status": "active",
"ValidUntil": "2019-11-30T00:00:00+01:00"
}
},
{
"bankSign": "dcChChf",
"accountNumber": "1230000022",
"customerCode": "992500123456",
"cardCustomerCode": "979500789456",
"cardToken": "3609611000000015556",
"isVirtual":true,
"embosing": {
"ownerName": "EMIL NIELSEN",
"embosingOptional": "MEGA CORP INC.",
"productName": "Business Exclusive",
"imageUrl": "api/cardimages/CH/businesexclusive.png",
"creationDate": "2013-11-28T00:00:00+01:00",
"expiryDate": "2019-11-30T00:00:00+01:00",
},
"rights": {
"canChangePin": true,
"hasSmsAlert": true,
"canSetBlock": true,
},
"status": {
"status": "blocked",
"ValidUntil": "2100-01-01T00:00:00+01:00"
}
}
],
"perPage": 2,
"pageNumber": 4,
"total": 20
}
This endpoint retreives all cards for the customer (corporate customer) based on the custumer code.
Optionally query can be narrowed down to a set of account numbers by appending one or more accountNumber=<ACCOUNT_NUMBER>
parameters to the URL.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/cards/<BANK_SIGN>/<CUSTOMER_CODE>
Optional Querry Parameters
Parameter | Type | Default | Description |
---|---|---|---|
accountNumber |
string | all accounts | Unique Account ID. Length depends on the franchise |
pageNumber |
int | 1 | see pagination input |
perPage |
int | 5 | see pagination input |
Get a Specific Card
API returns JSON structured like this:
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"cardCustomerCode": "982500789123",
"cardToken": "3609611000000010005",
"isVirtual":false,
"embosing": {
"ownerName": "JOHN DOE",
"embosingOptional": "MEGA CORP INC.",
"productName": "Business Exclusive",
"imageUrl": "api/cardimages/CH/businesexclusive.png",
"creationDate": "2013-11-28T00:00:00+01:00",
"expiryDate": "2019-11-30T00:00:00+01:00",
},
"rights": {
"canChangePin": true,
"hasSmsAlert": false,
"canSetBlock": true,
},
"status": {
"status": "active",
"validUntil": "2019-11-30T00:00:00+01:00"
}
}
This endpoint retrieves a specific card based on the card token.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/cards/<BANK_SIGN>/<CUSTOMER_CODE>/<ACCOUNT_NUMBER>/<CARD_TOKEN>
URL Parameters
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID |
CARD_TOKEN |
string | Unique card ID |
Card API Field Description
Field | Type | Description |
---|---|---|
bankSign |
string | Unique bank ID. See BANK_SIGN |
accountNumber |
string | Unique account ID. |
cardCustomerCode |
string | Unique customer ID. Warning! This is card owner's customer code, it is not the same as the customer code in the accounts API and in the URL. It cannot be used to further query the API except for the demographics data. |
cardToken |
string | Masked card number |
isVirtual |
bool | True if card is just a virtual card, false if card physically exists |
Card Embosing Field Description
Field | Type | Description |
---|---|---|
ownerName |
string | Cards owner's name. This name is embossed on the physical card. |
embosingOptional |
string | Data that can be optionally embossed under ownerName , on corporate cards this is ussualy corporation's name. |
productName |
string | Card product name |
imageUrl |
string | Card image is stored at location: <BASE_URL> + imageUrl |
creationDate |
dateTime | Card creation date. |
expiryDate |
dateTime | Card Expiry date. Always displays the newest date. |
Card Rights Field Description
Field | Type | Description |
---|---|---|
canChangePin |
bool | Does the card support the PIN change? |
hasSmsAlert |
bool | Is safety sms message enabled? |
canSetBlock |
bool | If true than a soft block can be set on a card, otherwise this is not possible, either because card does not support this option, or because card was hard blocked. |
Card status from AS Field Description
Field | Type | Description |
---|---|---|
status |
string | Values: active - card can do "business", inactive - card was blockd by the bank or some "higher" authority it cannot do "business", blocked - card was "soft blocked" by somebody this block can be removed. |
ValidUntil |
dateTime | Current status is valid until this dateTime if status was set in the AS. Afterwards it is reset to the default status. |
Notes about Cards
When a new card is issued (due to theft, mechanical damage, etc.) transactions made with the old card are not automatically linked to it. Users usually expect new card to be "clean".
Embossing
This endpoint provides additional embossing data (such as CVV2) for a specific virtual card.
Get Embossing
API returns JSON structured like this:
{
"bankSign": "dcChEur",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"cardCustomerCode": "982500789123",
"cardToken": "3609611000000010005",
"basicEmbossing": {
"ownerName": "ERIK NIELSEN",
"embosingOptional": "MEGA CORP INC.",
"productName": "Business Exclusive",
"imageUrl": "api/cardimages/CH/businesexclusive.png",
"creationDate": "2013-11-28T00:00:00+01:00",
"expiryDate": "2019-11-30T00:00:00+01:00",
},
"additionalEmbossing": {
"cvv2": "123",
"cardNumber": "11111111111111",
"memberFrom": "2011-11-28T00:00:00+01:00",
}
}
This endpoint provides embossing data based on the account number and card token.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/embossing/<BANK_SIGN>/<CUSTOMER_CODE>/<ACCOUNT_NUMBER>/<CARD_TOKEN>
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID |
CARD_TOKEN |
string | Unique card ID |
Embossing API Field Description
Field names and values are same as in the card API field description. This is a description of the fields specific to the Embossing API.
Field | Type | Description |
---|---|---|
memberFrom |
dateTime | Date when the card owner became DCI member. |
cardNumber |
string | Real card number (PAN) |
cvv2 |
string | CVV2 |
Block
Block a Specific Card
API returns JSON structured like this:
{
"bankSign": "dcChChf",
"accountNumber": "1230000011",
"customerCode": "992500123456",
"cardCustomerCode": "982500789123",
"cardToken": "3609611000000010005",
"isVirtual":false,
"embosing": {
"ownerName": "JOHN DOE",
"embosingOptional": "MEGA CORP INC.",
"productName": "Business Exclusive",
"imageUrl": "api/cardimages/CH/businesexclusive.png",
"creationDate": "2013-11-28T00:00:00+01:00",
"expiryDate": "2019-11-30T00:00:00+01:00",
},
"rights": {
"canChangePin": true,
"hasSmsAlert": false
},
"status": {
"status": "blocked",
"ValidUntil": "2018-06-14T11:25:24+01:00"
}
}
This endpoint puts a soft block on a specific card.
HTTP Request
PUT <BASE_URL>/stateless/api/<VERSION>/block/<BANK_SIGN>/<CUSTOMER_CODE>/<ACCOUNT_NUMBER>/<CARD_TOKEN>/<STATUS>?validUntil=<DATE_TIME>
URL Parameters
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID. Length depends on the franchise |
CARD_TOKEN |
string | Unique card ID. Length = 15 |
STATUS |
string | New card status (status to be set with this request). Options: active or suspended |
Mandatory Query Parameter
Parameter | Type | Description |
---|---|---|
validUntil |
dateTime | When will the new status expire and change back to the current one. Max value = 2100-01-01T00:00:00 (convert your datetime to UTC+1) |
Block API Field Description
Block api returns the same JSON as the Cards API with updates to the blocks part of the JSON.
Transactions
This endpoint provides all the necessary information about transactions, authorizations and payments.
Name "transactions" can be misleading so keep this in mind while reading field value documentation. For example merchantCountryCode
is documented under Transaction Merchant Field Description but it will also return merchant data for authorizations.
Difference: (in plain language)
- Authorization: Card was used.
- Transaction (Clearing): Card was used and the issuing bank paid for the expense to the acquirer.
- Payment: Customer has covered his outstanding balance.
Get All Transactions
API returns JSON structured like this:
{
"output": [
{
"bankSign": "dcChEur",
"accountNumber": "2000000001",
"cardToken": "3000000000000000008",
"source": "transaction",
"isFee": false,
"billed": false,
"amount":{
"amount": 104,
"amountWithFees": 104.55,
"currency": "EUR",
"originalAmount": 104,
"originalCurrency": "EUR",
"exchangeRate": 1,
"transactionFees": [
{
"amount": 0.55,
"currency": "EUR",
"description": "DINERS NADOMESTILO BENCINSKI SERVIS: 8.1. OB 1.175513 +0.55",
"descriptionTranslated": "Diners Gas Station fee: 8.1. at 1.175513 +0.55",
"postingDate": "2018-01-10T00:00:00+01:00",
"merchantName": "PETROL SLOVENIJA"
}
],
},
"merchant":{
"merchantCountryCode": 705,
"merchantCountryDescription": "SLOVENIA",
"merchantLocation": "Koper/Capodistria, SLOVENIA",
"merchantLocationFull": "CENTER, Koper/Capodistria, SLOVENIA",
"description": "PETROL BS KOPER",
"descriptionTranslated": "PETROL GAS STATION KOPER",
"merchantId": "456789",
"terminalId": "124314414",
"mccCode": "9999",
"type": "gasStations",
},
"offers": {
"offerStatus": "unavailable",
"installmentsNumber": 0,
"financeStatus": "",
"offerExpirationDate": null,
"cfAmortizationPlanId": 0,
},
"authorization": {
"authorizationId": 12345,
"date": "2018-01-08T00:00:00+01:00",
},
"transaction": {
"transactionId": 90000000007,
"postingDate": "2018-01-09T00:00:00+01:00",
},
"payment": {
"paymentId": null,
"paymentDate": null,
"paymentProcessingStatus": ""
},
"transactionRights": {
"hasFinancing": false
},
},
{
"bankSign": "dcChEur",
"accountNumber": "2000000001",
"cardToken": "3000000000000000008",
"source": "authorization",
"isFee": false,
"billed": false,
"amount":{
"amount": 32,
"amountWithFees": 32,
"currency": "EUR",
"originalAmount": 238.19,
"originalCurrency": "DKK",
"exchangeRate": 0.134997,
"transactionFees": [],
},
"merchant":{
"merchantCountryCode": 208,
"merchantCountryDescription": "DENMARK",
"merchantLocation": "København, DENMARK",
"merchantLocationFull": "Vimmelskaftet 37, 1161 København, DENMARK",
"description": "LEGO store DK",
"descriptionTranslated": "LEGO store DK",
"merchantId": "123456",
"terminalId": "1232425345",
"mccCode": "9977",
"type": "shopping",
},
"offers": {
"offerStatus": "unavailable",
"installmentsNumber": 0,
"financeStatus": "",
"offerExpirationDate": null,
"cfAmortizationPlanId": 0,
},
"authorization": {
"authorizationId": 12345,
"date": "2018-01-08T00:00:00+01:00",
},
"transaction": {
"transactionId": null,
"postingDate": null,
},
"payment": {
"paymentId": null,
"paymentDate": null,
"paymentProcessingStatus": ""
},
"transactionRights": {
"hasFinancing": false
}
}
],
"perPage": 2,
"pageNumber": 1,
"total": 100
}
This endpoint retreives all transactions for the customer (corporate customer) based on the custumer code.
Optionally query can be narrowed down to a set of account numbers or card tokens by appending one or more accountNumber=<ACCOUNT_NUMBER>
or cardToken=<CARD_TOKEN>
parameters to the URL. However mixing of account numbers and card tokens in a single request is not supported.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/transactions/<BANK_SIGN>/<CUSTOMER_CODE>
Optional Query Parameters
Parameter | Type | Default | Description |
---|---|---|---|
accountNumber |
string | all accounts | Unique Account ID. Length depends on the franchise |
cardToken |
string | all cards | Unique Account ID. Length depends on the franchise |
includePay |
bool | false | Return payments |
includeAuth |
bool | false | Return authorizations |
includeTrx |
bool | true | Return transactions |
pageNumber |
int | 1 | see pagination input |
perPage |
int | 5 | see pagination input |
getExactTotal |
bool | false | see notice below |
transactionDateFrom |
date | none | filters response to AUTHORIZATIONS after certain date (name change is planned to authDateFrom ) |
transactionDateTo |
date | none | filters response to AUTHORIZATIONS before certain date (name change is planned authDateTo ) |
postingDateFrom |
date | none | filters response to TRANSACTIONS after certain date (name change is planned to trxDateFrom ) |
postingDateTo |
date | none | filters response to TRANSACTIONS before certain date (name change is planned to trxDateTo ) |
Get a Specific Transaction
The above command returns JSON structured like this:
{
"bankSign": "dcChEur",
"accountNumber": "2000000001",
"cardToken": "3000000000000000008",
"source": "authorization",
"isFee": false,
"billed": false,
"amount":{
"amount": 32,
"amountWithFees": 32,
"currency": "EUR",
"originalAmount": 238.19,
"originalCurrency": "DKK",
"exchangeRate": 0.134997,
"transactionFees": []
},
"merchant":{
"merchantCountryCode": 208,
"merchantCountryDescription": "DENMARK",
"merchantLocation": "København, DENMARK",
"merchantLocationFull": "Vimmelskaftet 37, 1161 København, DENMARK",
"description": "LEGO store DK",
"descriptionTranslated": "LEGO store DK",
"merchantId": "123456",
"terminalId": "1232425345",
"mccCode": "9977",
"type": "shopping",
},
"offers": {
"offerStatus": "unavailable",
"installmentsNumber": 0,
"financeStatus": "",
"offerExpirationDate": null,
"cfAmortizationPlanId": 0,
},
"authorization": {
"authorizationId": 12345,
"date": "2018-01-08T00:00:00+01:00",
},
"transaction": {
"transactionId": null,
"postingDate": null,
},
"payment": {
"paymentId": null,
"paymentDate": null,
"paymentProcessingStatus": ""
},
"transactionRights": {
"hasFinancing": false
}
}
This endpoint retrieves a specific transaction based on the transaction id.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/transactions/<BANK_SIGN>/<CUSTOMER_CODE>/<ID>
URL Parameters
Parameter | Type | Description |
---|---|---|
ID |
int | transaction or authorization or payment unique ID |
Transaction API Field Description
All data for transactions and payments comes from the DCMS, data for authorizations always comes from the AS.
Field | Type | Description |
---|---|---|
bankSign |
string | Uniqe bank ID |
accountNumber |
string | Unique account ID. (Will be 0 for authorizations) |
cardToken |
string | Unique card ID |
source |
string | Is this a transaction , authorization or payment ? |
isFee |
bool | Is this just a system fee or an event when customer used the card? |
billed |
bool | Was customer already billed for this purchase? |
Transaction Amount Field Description
Amount can change between an authorization and a transaction. API will return the amount from the AS for an authorization and the amount from the DCMS once the clearing comes thorugh.
Amount display depends on the franchise. Some display only the amount, others display amount with fees.
Field | Type | Description |
---|---|---|
amount |
decimal | Purchase amount in account's "native" currency |
amountWithFees |
decimal | Full amount: Purchase amount + sum of fees |
currency |
string | Account's native currency |
originalAmount |
decima | Amount in original currency (currency in which the purchase was made) |
originalCurrency |
string | Currency in which the purchase was made |
exchangeRate |
decimal | Rate that was used to convert the originalAmount into the amount |
Transaction Merchant Field Description
Field | Type | Description |
---|---|---|
merchantCountryCode |
int | 3 digit country code according to ISO 3166-1 numeric |
merchantCountryDescription |
string | Full country name |
merchantLocation |
string | Mercant city and country |
merchantLocationFull |
string | Full merchant address |
description |
string | Merchant name |
descriptionTranslated |
string | Translated marchant name (translations depend on the franchise) |
merchantId |
string | Merchant ID |
terminalId |
string | Terminal ID |
mccCode |
string | Merchant category code |
type |
string | Internal Dinit's categorization |
Transaction Consumer Finance Field Description
Internal Dinit's Consumer Finance information.
Field | Type | Description |
---|---|---|
offerStatus |
string | Not Applicable |
installmentsNumber |
int | Not Applicable |
financeStatus |
string | Not Applicable |
offerExpirationDate |
dateTime | Not Applicable |
cfAmortizationPlanId |
int | Not Applicable |
Authorization Field Description
Authorization ID from the AS. Both fields will be empty in case of payments.
Field | Type | Description |
---|---|---|
authorizationId |
int | Authorization ID |
date |
dateTime | Date when the card was used (date when the purchase was authorized) |
Transaction Field Description
Transaction ID from the DCMS. Both fields will be empty in case of authorizations.
Field | Type | Description |
---|---|---|
transactionId |
int | Transaction ID |
postingDate |
dateTime | Date when the clearing for the authorization came through |
Payments Field Description
Field | Type | Description |
---|---|---|
paymentId |
int | Payment ID |
paymentDate |
dateTime | Date when the payment was made |
paymentProcessingStatus |
string | DIP: To be provided if applicable |
Transaction Rights Field description
Field | Type | Description |
---|---|---|
hasFinancing |
book | Not Applicable |
Demographics
Get Demographics for a Specific Card Owner
API returns JSON structured like this:
{
"cardCustomerCode": "979500789456",
"type": "private",
"username": "EmilFNielsen@dayrep.com ",
"defaultLangauge": "en",
"personalDetails": {
"firstName": "EMIL",
"lastName": "F. NIELSEN",
"name": "EMIL F. NIELSEN",
"birthDate": " 1964-01-19T00:00:00+02:00",
},
"address": {
"city": " KØBENHAVN",
"country": "DENMARK",
"county": "KØBENHAVN",
"district": "KØBENHAVN V",
"houseNumber": null,
"postalCode": "1705",
"street": "Sønderstræde 13"
},
"contact": {
"cellPhone": "1901640927",
"smsNumber": "888999777888",
"homePhone": "0041912200230",
"email": " EmilFNielsen@dayrep.com",
}
}
This endpoint retrieves demographic information for a specific card owner.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/demographics/<BANK_SIGN>/<CUSTOMER_CODE>/<CARD_CUSTOMER_CODE>
URL Parameters
Parameter | Type | Description |
---|---|---|
ACCOUNT_NUMBER |
string | Unique account ID. |
CARD_CUSTOMER_CODE |
string | Unique card owner ID. This customer code belogns to the card owner. First customer code in the request belongs to the corporate customer subscribed to the service. |
Demographics API Field Description
Fields are self explanatory hence detailed description is omitted.
Terminal
This endpoint provides information about Virtual POS Terminal. It provides:
- data needed for payments and reversals via terminal
- history of transactions for particular merchant
Get Transactions
API returns JSON structured like this:
{
"output":[
{
"merchantName":"ACTIVA TEST",
"currencyAlphaCodeAcq":"EUR",
"transactionStatusDescription":"Pending",
"amountIssuing":100.88,
"stan":"557601",
"transactionDate":"2018-08-23T07:32:37+02:00",
"encodedPan":"10000000000000"
},
{
"merchantName":"ACTIVA TEST",
"currencyAlphaCodeAcq":"EUR",
"transactionStatusDescription":"Pending",
"amountIssuing":70.20,
"stan":"23096",
"transactionDate":"2018-08-22T08:20:23+02:00",
"encodedPan":"10000000000000"
}
],
"pageNumber":1,
"perPage":6,
"total":11,
"isSuccessfullRequest":true,
"responseCode":"OK",
"responseMessage":"OK",
}
This endpoint retreives all transaction based on merchant and terminal.
HTTP Request
GET <BASE_URL>/stateless/api/<VERSION>/terminal/transactions/<MERCHANT_ID>
Required parameters
Parameter | Type | Description |
---|---|---|
MERCHANT_ID |
string | Unique merchant ID. |
Optional Query Parameters
Parameter | Type | Default | Description |
---|---|---|---|
transactionType |
string | P | Defines transaction type. Use P for purchase and R for reversal. |
perPage |
int | 11 | see pagination input |
pageNumber |
int | 1 | see pagination input |
New transaction (payment)
This endpoint is used to make a new payment from terminal.
HTTP Request
POST <BASE_URL>/stateless/api/<VERSION>/terminal/payment
Input JSON is structured like this
{
"cardNumber": "11111111111111",
"amount": 300.00,
"currency": "EUR",
"cardCvc2": "100",
"cardExpirationMonth": "12",
"cardExpirationYear": "20",
"merchantId": "123456789",
"installementFactor": 1,
"automaticCapture": false
}
Input parameters
Parameter | Type | Required / Default | Description |
---|---|---|---|
cardNumber |
string | required |
Customer card number. |
amount |
float | required |
Transaction amount. |
currency |
string | required |
Currency code. |
cardCvc2 |
string | required |
Card secure number. |
cardExpirationMonth |
string | required |
Card expiration month. |
cardExpirationYear |
string | required |
Card expiration year. |
merchantId |
string | required |
Unique merchant ID. |
installementFactor |
int | optional / default: 1 |
Specifies the factor for payments in parts. |
automaticCapture |
bool | optional / default: false |
Include automatic capturing. |
API returns JSON structured like this
{
"responseCode": "OK",
"responseText": "OK",
"authorisationCode": "047359",
"isSuccessStatusCode": true
}
Return parameters
Parameter | Type | Description |
---|---|---|
responseCode |
string | Custom response code of request. |
responseMessage |
string | Custom response message of request. |
authorisationCode |
string | Authorisation code. |
isSuccessStatusCode |
bool | True if the request was processed successfully and False otherwise. |
Reverse Transaction
This endpoint is used for transaction reversal.
POST <BASE_URL>/stateless/api/<VERSION>/terminal/reverse_transaction
Input JSON is structured like this:
{
"cardNumber": "1111111111111",
"merchantId": "123456789",
"amount" : 100.88,
"originalStan" : 557601,
"originalLocalTransactionTime" : "2018-08-23T07:32:37+02:00"
}
Input parameters
Parameter | Type | Required / Default | Description |
---|---|---|---|
cardNumber |
string | required |
Number of the card used to make transaction (payment) |
merchantId |
string | required |
Unique merchant ID. |
amount |
float | required |
Transaction amount. |
originalStan |
long | required |
Transaction STAN. |
originalLocalTransactionTime |
datetime | required |
Date and time when the transaction was made. |
Return parameters
API returns JSON structured like this:
{
"responseCode": "OK",
"responseMessage": "OK",
"result": true
}
Parameter | Type | Description |
---|---|---|
responseCode |
string | Custom response code of request. |
responseMessage |
string | Custom response message of request. |
result |
bool | True if the request was successfull and False otherwise |
Response Codes and Errors
200 OK
Successful requests will return response code 200 OK
with body
that contains requested data.
Errors
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid (this will be followed by the body message containing information that will help you make a valid request). |
401 | Unauthorized -- Your access token is wrong. |
403 | Forbidden -- You do not have perrmision to see this data. (Check if you are using the correct CUSTUMER_CODE . You have to use the company's customer code, not the card owner's one) |
404 | Not Found -- The specified account, card or transaction could not be found. |
405 | Method Not Allowed -- You tried to access resources with an invalid method. |
409 | Conflict -- Somebody is trying to write to DB at the same time as you are. |
429 | Too Many Requests -- You're requesting too much data! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Changelog
Here we will document non breaking changes i.e. changes that did not cause a version increase.
date | change |
---|---|
20. 01. 2018 | Initial release of v1 |
12. 02. 2018 | Typos fix, Embossing Api output change, Demographics API URL fixed |
27. 03. 2018 | Block API fix. URL parameter VALID_UNTIL is now mandatory querry parameter validUntil |
17. 09. 2018 | Added "POS Terminal" Api descriptions |
03. 12. 2018 | Added date related queries to transactions, adedd getExactTotal query to transactions |