NAV Navbar
  • Introduction
  • Authentication
  • Accounts
  • Balance
  • Cards
  • Embossing
  • Block
  • Transactions
  • Demographics
  • Terminal
  • Response Codes and Errors
  • Changelog
  • 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:

    Naming Conventions

    Here we will document frequently used words and describe any obscure fields should they appear.

    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

    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)

    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