Inngangur

Velkomin í skjölun á Kass API v1.

Auðkenning

Hver aðgerð í Kass API notar HTTP Basic Auth auðkenningu (sjá curl -u í dæmum). Aðgangskóði söluaðila er sendur inn sem notandanafn á meðan svæðið fyrir lykilorð er tómt.

-u um2JjfnJbEUJnCpjKiV94jqp:

Stofna rukkun

curl https://api.kass.is/v1/payments \
    -u um2JjfnJbEUJnCpjKiV94jqp: \
    -d @payment_request.json

Dæmi um innsend JSON gögn (payment_request.json)

{
    "amount": 2199,
    "description": "Kass bolur",
    "image_url": "https://photos.kassapi.is/kass/kass-bolur.jpg",
    "order": "ABC123",
    "recipient": "7728440",
    "terminal": 1,
    "expires_in": 90,
    "notify_url": "https://example.com/callbacks/kass"
}

Dæmi um JSON svargögn ef aðgerð tókst

{
    "success": true,
    "id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "created": 1458748385
}

Dæmi um JSON svargögn ef upp kom villa

{
    "success": false,
    "error": {
        "code": "200",
        "key": "recipient_not_found",
        "message": "Viðtakandi fannst ekki"
    }
}

Þessi aðgerð stofnar rukkun og sendir hana samstundis á viðtakanda. Viðtakandinn hefur þá 90 sekúndur til að bregðast við rukkuninni, hvort sem er að greiða eða hafna. Eftir þann tíma rennur rukkunin út og viðtakandi getur ekki lengur greitt.

HTTP

POST https://api.kass.is/v1/payments

Skýring á innsendum svæðum

Skýring á svæðum í svargögnum

Sækja upplýsingar um rukkun

curl https://api.kass.is/v1/payments/3e6975e8-77cb-48b7-7722-3dfe47677bbc \
    -u um2JjfnJbEUJnCpjKiV94jqp:

Dæmi um JSON svargögn

{
    "id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "transaction_id": "a917be59-f35a-478f-a5d9-19bf467972ad",
    "amount": 2199,
    "description": "Kass bolur",
    "image_url": "https://photos.kassapi.is/kass/kass-bolur.jpg",
    "status": "paid",
    "order": "abc123",
    "created": 1458748385,
    "updated": 1458748422,
    "expires": 1458748475
}

Skilar upplýsingum um rukkun. Ef eingöngu er verið að athuga stöðu rukkunar, sjá kaflann Athuga stöðu á rukkun.

HTTP

GET https://api.kass.is/v1/payments/[id]

Skýring á svæðum

Fella niður rukkun

curl -X DELETE https://api.kass.is/v1/payments/3e6975e8-77cb-48b7-7722-3dfe47677bbc \
    -u um2JjfnJbEUJnCpjKiV94jqp:

Dæmi um JSON svargögn

{
    "id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "status": "rejected",
    "expires": 1458748475
}

Fellir niður rukkun samstundis þannig að notandi getur ekki lengur greitt.

HTTP

DELETE https://api.kass.is/v1/payments/[id]

Skýring á svæðum

Athuga stöðu á rukkun

curl https://api.kass.is/v1/payments/3e6975e8-77cb-48b7-7722-3dfe47677bbc/status \
    -u um2JjfnJbEUJnCpjKiV94jqp:

Dæmi um JSON svargögn

{
    "id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "status": "pending",
    "expires": 1458748475
}

Skilar stöðunni á rukkun, þ.e.a.s. hvort hún sé ógreidd, hafi verið greidd, hafi verið hafnað eða sé útrunnin.

HTTP

GET https://api.kass.is/v1/payments/[id]/status

Skýring á svæðum

Sjálfvirk tilkynning frá Kass (notification callback)

Dæmi um JSON gögn

{
    "payment_id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "transaction_id": "a917be59-f35a-478f-a5d9-19bf467972ad",
    "amount": 2199,
    "status": "paid",
    "order": "abc123",
    "completed": 1458748422,
    "signature": "8022cb71924dba2e24f849fdc83596e80a3966465f6b3f1702326afa31229b11"
}

Þegar staðan á rukkun breytist, hvort sem kaupandi greiðir, hafnar eða rukkun rennur út, er POST-að á notify_url slóðina, sem skilgreind var þegar rukkunin var stofnuð, með upplýsingum um greiðsluna. Svarið er undirritað.

Til að koma í veg fyrir misnotkun er mælt með því að staðfesta undirritunina (signature strenginn) og einnig er gott að passa að þú meðhöndlir ekki sama payment_id oftar en einu sinni.

Mikilvægt: Netþjónninn þinn verður að svara með HTTP 200 OK. Að öðru leyti telst svarið ekki gilt og Kass mun því reyna nokkrum sinnum aftur að senda gögnin á netþjóninn þinn.

Skýring á svæðum

Undirritun

Dæmi um samsettan streng

3e6975e8-77cb-48b7-7722-3dfe47677bbc&a917be59-f35a-478f-a5d9-19bf467972ad&abc123&2199&paid&1458748422

Dæmi

** Veldu forritunarmál efst á síðunni **

string key = "um2JjfnJbEUJnCpjKiV94jqp";
string body = "3e6975e8-77cb-48b7-7722-3dfe47677bbc&a917be59-f35a-478f-a5d9-19bf467972ad&abc123&2199&paid&1458748422";
byte[] keyBytes = Encoding.UTF8.GetBytes(key);
HMACSHA256 hasher = new HMACSHA256(keyBytes);
byte[] bodyBytes = hasher.ComputeHash(Encoding.UTF8.GetBytes(body));
string signature = BitConverter.ToString(bodyBytes).Replace("-", "");

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
var key = []byte("um2JjfnJbEUJnCpjKiV94jqp")
var body = "3e6975e8-77cb-48b7-7722-3dfe47677bbc&a917be59-f35a-478f-a5d9-19bf467972ad&abc123&2199&paid&1458748422"
var h = hmac.New(sha256.New, key)
h.Write([]byte(body))
var signature = hex.EncodeToString(h.Sum(nil))

<?php
$key = 'um2JjfnJbEUJnCpjKiV94jqp';
$body = utf8_encode('3e6975e8-77cb-48b7-7722-3dfe47677bbc&a917be59-f35a-478f-a5d9-19bf467972ad&abc123&2199&paid&1458748422');
$signature = hash_hmac('sha256', $body, $key);
?>

require 'openssl'

key = 'um2JjfnJbEUJnCpjKiV94jqp'
body = '3e6975e8-77cb-48b7-7722-3dfe47677bbc&a917be59-f35a-478f-a5d9-19bf467972ad&abc123&2199&paid&1458748422'
digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.hexdigest(digest, key, body)

Dæmi um fullbúna undirritun

8022cb71924dba2e24f849fdc83596e80a3966465f6b3f1702326afa31229b11

Undirritunin er strengur sem er settur saman úr eftirfarandi einingum og síðan hashaður með HMAC SHA256 þar sem aðgangskóðinn er lykillinn.

payment_id&transaction_id&order&amount&status&completed

Mögulegir villukóðar

Kass API styðst við eftirfarandi villukóða:

Sandkassi (prófunargögn)

curl https://api.testing.kass.is/v1/payments \
    -u kass_test_auth_token: \
    -d @payment_request.json

Hægt er að senda rukkanir á prófunarsvæði með því að nota aðgangskóðann kass_test_auth_token. Fyrir neðan má finna lista af símanúmerum sem senda má rukkun á og skýringu á viðbrögðum kerfisins.

HTTP

POST https://api.testing.kass.is/v1/payments