A.P.I dokumentation

(API: Application Programming Interface)

Godkendelse af forespørgsler

Alle forespørgsler ind i vores REST API skal godkendes!

For alle forespørgsler skal medsendes et JSON godkendelsesobjekt i forespørgslens header.
Denne side foreklarer beregningsproceduren for objektet og hvordan det indsættes i anmodningen.


Der oprettes et JSON godkendelsesobjekt som nedenfor. JSON objektet sendes med alle HTTP 1.1 GET/POST forespørgsler som et UTF-8 kodet byte array i Base64 format. Værdien indsættes i HTTP 1.1 Authorization header værdien.

For betalingsanmodninger (POST) oprettes et hash objekt for hver transaktion
For GET forespørgsler (status, kontoudtog m.m.) oprettes kun et hash objekt hvor "id" sættes til værdien i "requestId".

{
  "serviceProvider": "<ERP Navn>",
  "account": "<Kunde Konto>",
  "time": "<UTC Tidspunkt>",
  "requestId": "<Request ID>",
  "user": "<ERP's ID af bruger>" (valgfri),
  "hash": [
    {
      "id": "<Payment ID>",
      "hash": "<HMAC-Base64>"
    },
    {
      "id": "<Payment ID>",
      "hash": "<HMAC-Base64>"
    }
  ]
}

For hver transaktion i betalingsanmodningen beregnes en hash værdi som indsættes i godkendelsesobjektets hash-array.
Alle dele af strengen (Payload) adskilles af et # (pound). Blanke/tomme værdier medtages.

Først sammensættes payload strengen af dels de værdier som der findes i transaktionen og dels af de øverste værdier.

  • En token streng af kundens password som en SHA256 hash over et UTF-8 kodet byte array formateret i HEX.
  • Kundens konto nr. formateres til BBAN (14 cifre)
  • Betalingsdato formateres til YYYYMMDD (Y=år, M=måned, D=dato)
  • Beløb formatet med to decimaler og punktum som decimal seperator (ingen tusindtals adskiller)
  • Valuta formateres til ISO valuta kode (som DKK eller USD)
  • Konto eller betalings ID hentes fra request objekt
  • ERP udbyders navn/kode indsættes
  • Betalings ID fra transaktion indsættes
  • Det aktuelle UTC tidspunkt fomateres til YYYYMMDDHHmmSS (Y=år, M=måned, D=dato, H=time (24h), m=minut, S=sekund)

Over hver payload streng (som UTF-8 kodet byte array) genereres nu en HMAC/SHA256 hash med ERP udbyders API-nøgle som nøgle.
HMAC værdien indsættes sammen med <PaymentId> og HMAC som Base64 streng

Beregning af hver hash er vist herunder i pseudo kode

var token = Sha256(<Kunde Kode>.ToUtf8Bytes()).ToHexChars();
var custacc = <Kunde Konto>.ToBBAN(); // XXXXYYYYYYYYYY, X=Reg nr. og Y=Konto nr.
var currency = <Valuta>.ToIso3Letter();
var reqid = <Request ID>;
var paydate = <Betalings Dato>.Format('YYYYMMDD');
var amount = <Beløb>.Format('0.00');
var credacc = <Modtager IBAN/BBAN/GI/FI/CPR/CVR>;
var erp = <ERP Navn/Kode>;
var payid = <Payment ID>;
var now = <UTC Tidspunkt>.Format('YYYYMMDDHHmmSS');

var payload = "<token># \
	<custacc># \
	<currency># \
	<reqid># \
	<paydate># \
	<amount># \
	<credacc># \
	<erp># \
	<payid># \
	<now>";

var payloadBuffer = payload.ToUtf8Bytes();
var erpKey = Guid(<ErpApiKey>).ToBytes();
var hmac = Hmac('SHA256', erpKey, payloadBuffer).ToBase64();

Eksempel beregning

Du kan ændre værdierne ovenfor til dine egne test værdier. Gør du det så gemmes værdierne indtil du genindlæser siden.
Tryk på "Gem" for at bruge dine egne værdier.