Acceptico Dokumentacija

Autentifikacija za Pozivanje Integracionih Servisa

Za potrebe autentifikacije pri korišćenju integracionih servisa koristi se JWT standard (JSON Web Token). Ovaj standard obezbeđuje siguran prenos informacija između klijenta (trgovca) i servera uz potpisivanje i verifikaciju tokena. Za dodatne informacije, primere koda i biblioteke dostupne za različite programske jezike, posetite jwt.io

Opis Mehanizma Autentifikacije

Proces autentifikacije uz upotrebu JWT tokena uključuje dve strane:

  • A - Trgovac (vaša aplikacija)
  • B - Server (Acceptico)

Između ove dve strane vrši se razmena simetricnih ključeva koje Acceptico d.o.o. dostavlja trgovcu.

Koraci za Pozivanje Servisa uz JWT Autentifikaciju

Generisanje JWT tokena:

  • Trgovac generiše JWT token potpisivanjem JSON payload-a koristeći svoj privatni ključ.
  • Minimalni zahtev za sadržaj payload-a je naziv trgovca (varijabla MerchantUsername), kao i vrednost koja određuje vreme isteka tokena (varijabla exp).
  • Algoritam potpisivanja koji se koristi je HS256.

Pozivanje servisa:

  • Trgovac (A) šalje zahtev serveru (B) JWT token. Token mora biti prosleđen metodom (GET/POST) u zavisnosti od servisa koji se poziva.

Verifikacija tokena:

  • Server (B) proverava da li je token zaista potpisao trgovac, koristeći svoju kopiju privatnog ključa.
  • Nakon uspešne verifikacije, server čita sve potrebne podatke iz tokena za dalje procesiranje.
  • Server (B) daje dogovor Trgovcu (A) sa takodje potpisanim JWT tokenom kako bi trgovac bio siguran da je dogovor dosao zaista od servera, a ne od nekog drugog.

Napomene

  • Servis koristi simetrične (tajne) ključeve za potpisivanje i verifikaciju tokena.
  • Tajni ključevi se dostavljaju trgovcu putem Viber/Signal poruka za testno i produkciono okruženje, nakon čega se poruke brišu radi sigurnosti.

Ovo uputstvo pruža osnovne informacije potrebne za uspostavljanje bezbedne JWT autentifikacije između trgovca i servera za sve pozive integracionih servisa.

Rezervisi svoj termin za besplatne konsultacije!

IPS Prodaja - Full API Integracija

Putem ovog servisa možete primati IPS, odnosno uplatu pomocu skinaranja QR koda na bilo kojem internet portalu ili prodavnici.

URL Servisa:

POST /ips-connect

x-www-form-urlencoded => token = {generated_token}

{token} - JWT token koji u sebi sadrži payload sa navedenim obaveznim/opcionim poljima.

Struktura JWT Tokena za Naplatu i Transfer

Polje Obavezno/
Opcionalno		 Tip Opis
jwtUsername Required String Username koji dobijate od iPay-a za pristup i autentikaciju na API servise.
uniqueMerchantTransactionId Required String
Max 32 char.		 Unikatni identifikator iz sistema trgovca.
amount Required Integer Ukupan iznos za isplatu izražen bez decimalnih mesta.
exponent Required Integer
1 digit		 Ekponent parametra amount za računanje decimalnih mesta (primer: amount 1000 + exponent 2 = 10.00).
currencyCode Required Integer
3 digits		 Trocifrena ISO 4217 šifra valute (primer: 941 za RSD).
ipsStoreId Required String
Max 10 char.		 Identifikator prodajnog mesta.
lang Optional String
Max 2 char.		 Indikator odabira jezika. Dozvoljene vrednosti: "sr", "en"
notificationUrl Required URL URL na koji se salje informacija o konacnom statusu transakcije.
paymentPurposeCode Required Integer
3 digits		 Šifra svrhe plaćanja.
paymentDescription Required String Svrha plaćanja prilikom isplate sredstava na račun.
reference Required String
Max 100 char.		 Meta podaci koji se upisuju i prosleđuju u transakciji.
clientIp Required String
max. 15 char.		 IPv4 adresa klijenta. Primer: 111.111.111.111
exp Required Integer Vreme isteka tokena.

IPS Prodaja - Payment Page Integracija

Putem ovog servisa možete primati IPS, odnosno uplatu pomocu skinaranja QR koda na bilo kojem internet portalu ili prodavnici putem nase Payment Page stranice gde vam je pre generisan izgled stranice za IPS placanje.

IPS Prodaja - UML Dijagram:

URL Servisa:

POST /ips-sale

x-www-form-urlencoded => token = {generated_token}

{token} - JWT token koji u sebi sadrži payload sa navedenim obaveznim/opcionim poljima.

Struktura JWT Tokena za Naplatu i Transfer

Polje Obavezno/
Opcionalno		 Tip Opis
jwtUsername Required String Username koji dobijate od iPay-a za pristup i autentikaciju na API servise.
uniqueMerchantTransactionId Required String
Max 32 char.		 Unikatni identifikator iz sistema trgovca.
amount Required Integer Ukupan iznos za isplatu izražen bez decimalnih mesta.
exponent Required Integer
1 digit		 Ekponent parametra amount za računanje decimalnih mesta (primer: amount 1000 + exponent 2 = 10.00).
currencyCode Required Integer
3 digits		 Trocifrena ISO 4217 šifra valute (primer: 941 za RSD).
ipsStoreId Required String
Max 10 char.		 Identifikator prodajnog mesta.
lang Optional String
Max 2 char.		 Indikator odabira jezika. Dozvoljene vrednosti: "sr", "en"
cancelUrl Required URL URL na koji se redirektuje korisnik ukoliko odkaze transakciju.
successUrl Required URL URL na koji se redirektuje i saljem korisnik nakon uspesne transakcije.
failUrl Required URL URL na koji se redirektuje i saljem korisnik nakon neuspesne transakcije.
notificationUrl Required URL URL na koji se salje informacija o konacnom statusu transakcije.
notificationEmail Required Email Email na koji se salje informacija o konacnom statusu transakcije.
paymentPurposeCode Required Integer
3 digits		 Šifra svrhe plaćanja.
paymentDescription Required String Svrha plaćanja prilikom isplate sredstava na račun.
reference Required String
Max 100 char.		 Meta podaci koji se upisuju i prosleđuju u transakciji.
OrderId Required String
Max 100 char.		 Broj porudzbine trgovca.
clientIp Required String
max. 15 char.		 IPv4 adresa klijenta. Primer: 111.111.111.111
operaterId Required String
max. 10 char.		 ID Operatera
uiType Required String
max. 15 char.		 Tip payment page stranice. Dozvoljeni parametri: "full", "qr-only"
exp Required Integer Vreme isteka tokena.

Primer Tokena:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqd3RVc2VybmFtZSI6Iklwc19BY2NlcHRpY28iLCJpcHNTdG9yZUlkIjoiMzgxNTEyMDQyOSIsIm9wZXJhdGVySWQiOiI0NTM1MTk5MTE1IiwidW5pcXVlTWVyY2hhbnRUcmFuc2FjdGlvbklkIjoiNjcyOTM4NGI3M2NiNyIsImFtb3VudCI6MzAwMDAwLCJleHBvbmVudCI6MiwiY3VycmVuY3lDb2RlIjoiOTQxIiwicGF5bWVudENvZGUiOiIyODkiLCJwYXltZW50RGVzY3JpcHRpb24iOiJJUFMgUHJvZGFqYSAtIFRlc3QiLCJsYW5nIjoic3IiLCJ1aVR5cGUiOiJxci1vbmx5IiwicmVmZXJlbmNlIjoiUHJvaXp2b2xqbmEgcmVmZXJlbmNhIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8vYXBpLmFjY2VwdGljby5jb20vYXBpL3ZvaWQiLCJmYWlsVXJsIjoiaHR0cHM6Ly9hcGkuYWNjZXB0aWNvLmNvbS9hcGkvdm9pZCIsImNhbmNlbFVybCI6Imh0dHBzOi8vYXBpLmFjY2VwdGljby5jb20vYXBpL3ZvaWQiLCJleHAiOjE3MzA3NzI2MzV9.HQi-geomIF6is58QQBj8iXaNJGEUeCRCcGm3YXQaBGc

Primer Podataka Unutar Tokena Zahteva:

{
    "jwtUsername": "Ips_Acceptico",
    "ipsStoreId": "3815120429",
    "operaterId": "4535199115",
    "uniqueMerchantTransactionId": "6729384b73cb7",
    "amount": 300000,
    "exponent": 2,
    "currencyCode": "941",
    "paymentCode": "289",
    "paymentDescription": "IPS Prodaja - Test",
    "lang": "sr",
    "uiType": "qr-only",
    "reference": "Proizvoljna referenca",
    "successUrl": "https://api.acceptico.com/api/void",
    "failUrl": "https://api.acceptico.com/api/void",
    "cancelUrl": "https://api.acceptico.com/api/void",
    "exp": 1730772635
}

Primer Odgovora Servisa:

Primer Podataka Unutar Tokena Odgovora:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqd3RVc2VybmFtZSI6Iklwc19BY2NlcHRpY28iLCJvayI6eyJzdGF0dXMiOiJTIiwiaXBzQ29ubmVjdElkIjoiaXBzLnNhbGUuMjAyNDExMDQyMjEwMzUuNjcyOTM4NGJhMmRkYTMuMDI5NDM3NjEiLCJpcHNTdG9yZUlkIjoiMzgxNTEyMDQyOSIsIm9wZXJhdGVySWQiOiI0NTM1MTk5MTE1IiwidW5pcXVlTWVyY2hhbnRUcmFuc2FjdGlvbklkIjoiNjcyOTM4NGI3M2NiNyIsImFtb3VudCI6IjMwMDAwMCIsImV4cG9uZW50IjoiMiIsImFjY291bnROdW1iZXIiOiIxMTEyNzEwMzEwMDEzNzYzMTMiLCJjdXJyZW5jeUNvZGUiOiI5NDEiLCJwYXltZW50Q29kZSI6IjI4OSIsInBheW1lbnREZXNjcmlwdGlvbiI6IklQUyBQcm9kYWphIC0gVGVzdCIsInJlZmVyZW5jZSI6IlByb2l6dm9sam5hIHJlZmVyZW5jYSIsInByb2Nlc3NvcklkIjoiU1JCQVNFQVNFIiwidGVybWluYWxJZCI6IkFjY2VwdDAxIiwicHJvY2Vzc29yUmVzcG9uc2VDb2RlIjoiMDAiLCJwcm9jZXNzb3JUcmFuc2FjdGlvbklkIjoiTzU4ZjdoR2tlQ3FSenc4YUZMeU8iLCJwcm9jZXNzb3JUZXJtaW5hbElkIjoiTzU4ZjdoR2siLCJwcm9jZXNzb3JBcHByb3ZhbENvZGUiOiJhVmVMRldZWUEzIiwicHJvY2Vzc29yU3RhdHVzRGVzY3JpcHRpb24iOiIwWnJ5Zjk2SnhOeGlVZVVxQ2JpVWF2T3M1aWRpRWMiLCJpbml0aWFsaXphdGlvblRpbWVzdGFtcCI6IjIwMjQtMTEtMDQgMjE6MTA6MzUifSwiZXhwIjoxNzMwNzU2NDQyfQ.4-vTLXCyuQ_DAiCV9TuntiUDz7BVeVG_Le0l7uj5jM8

Primer Podataka Unutar Tokena Odgovora:

{
"jwtUsername": "Ips_Acceptico",
"ok": {
    "status": "S",
    "ipsConnectId": "ips.20241104221035.6729384ba2dda3.02943761",
    "ipsStoreId": "3815120429",
    "operaterId": "4535199115",
    "uniqueMerchantTransactionId": "6729384b73cb7",
    "amount": "300000",
    "exponent": "2",
    "accountNumber": "111271031001376313",
    "currencyCode": "941",
    "paymentCode": "289",
    "paymentDescription": "IPS Prodaja - Test",
    "reference": "Proizvoljna referenca",
    "processorId": "SRBASEASE",
    "terminalId": "Accept01",
    "processorResponseCode": "00",
    "processorTransactionId": "O58f7hGkeCqRzw8aFLyO",
    "processorTerminalId": "O58f7hGk",
    "processorApprovalCode": "aVeLFWYYA3",
    "processorStatusDescription": "0Zryf96JxNxiUeUqCbiUavOs5idiEc",
    "initializationTimestamp": "2024-11-04 21:10:35"
},
"exp": 1730756442
}

Kod Odgovor Komentar
200 
{
    "jwtUsername": "Ips_Acceptico",
    "ok": {
        "status": "S",
        .........
Uspešno plaćanje
200 
{
    "jwtUsername": "Ips_Acceptico",
    "ok": {
        "status": "D",
        .........
Placanje odbijeno
200 
{
    "jwtUsername": "Ips_Acceptico",
    "ok": {
        "status": "T",
        .........
Pokusaj naplate istekao
200 
{
    "jwtUsername": "Ips_Acceptico",
    "error": {
        "message": "Losa stuktura odgovora od servisa.",
        "code": "1254896325741257"
        .........
Error poruka

Servis isplate na tekuci racun

Putem ovog servisa možete izvršiti isplatu ranije deponovanog ili minusom obezbeđenog novca na bilo koji tekući račun u Srbiji.

URL Servisa:

POST /payments

x-www-form-urlencoded => token = {generated_token}

{token} - JWT token koji u sebi sadrži payload sa navedenim obaveznim/opcionim poljima.

Struktura JWT Tokena za Naplatu i Transfer

Polje Obavezno/
Opcionalno		 Tip Opis
merchantUsername Required String Username koji dobijate od iPay-a za pristup i autentikaciju na API servise.
uniqueMerchantTransactionId Required String
Max 32 char.		 Unikatni identifikator iz sistema trgovca.
customerId Required String
Max 100 char.		 Identifikator korisnika usluge.
reference Required String
Max 100 char.		 Meta podaci koji se upisuju i prosleđuju u transakciji.
amount Required Integer Ukupan iznos za isplatu izražen bez decimalnih mesta.
exponent Required Integer
1 digit		 Ekponent parametra amount za računanje decimalnih mesta (primer: amount 1000 + exponent 2 = 10.00).
currencyCode Required Integer
3 digits		 Trocifrena ISO 4217 šifra valute (primer: 941 za RSD).
paymentPurposeCode Optional Integer
3 digits		 Šifra svrhe plaćanja.
paymentType Optional String
1 char.		 Tip izvora sredstava (G - Gotovina, K - Kartica).
accountNumber Optional String
Max 18 char.		 Broj računa po modelu 97.
paymentDescription Required String Svrha plaćanja prilikom isplate sredstava na račun.
beneficiaryName Required String Ime (naziv) klijenta na čiji račun se vrši isplata sredstava.
beneficiaryAddress Required String Adresa klijenta na čiji račun se vrši isplata sredstava.
beneficiaryPlace Required String Mesto klijenta na čiji račun se vrši isplata sredstava.
beneficiaryRefModel Optional Integer Model poziva na broj po kojem se validira broj naloga.
beneficiaryRefNumber Optional String
Max 20 char.		 Poziv na broj po kojem se izvršava isplata.
exp Required Integer Vreme isteka tokena.

Primer poziva isplate na tekuci racun

Token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudFVzZXJuYW1lIjoiSXBzX0FjY2VwdGljbyIsInVuaXF1ZU1lcmNoYW50VHJhbnNhY3Rpb25JZCI6IlVOSVFVRTYyOGU4MzBiMWRmMTkiLCJjdXN0b21lcklkIjoiMTI1NDk2MjQ4NSIsInJlZmVyZW5jZSI6IlByb2l6dm9sam5hIHJlZmVyZW5jYSIsInBheW1lbnRQdXJwb3NlQ29kZSI6IjI4OSIsInBheW1lbnRUeXBlIjoiSyIsInBheW1lbnREZXNjcmlwdGlvbiI6ImRlc2NyaXB0aW9uIHRlc3QiLCJiZW5lZmljaWFyeU5hbWUiOiJiZW4gbmFtZSIsImJlbmVmaWNpYXJ5QWRkcmVzcyI6ImJlbiBhZGRyZXNzIiwiYmVuZWZpY2lhcnlQbGFjZSI6ImJlbiBwbGFjZSIsImJlbmVmaWNpYXJ5UmVmTW9kZWwiOiIiLCJiZW5lZmljaWFyeVJlZk51bWJlciI6InJlZiBudW0iLCJhbW91bnQiOiIzMDAwMDAiLCJleHBvbmVudCI6IjIiLCJjdXJyZW5jeUNvZGUiOiI5NDEiLCJhY2NvdW50TnVtYmVyIjoiMTExNjAwMDAwMDgwMzY0OTM3IiwiZXhwIjoxNjUzNTA4NjI5fQ.YIhMr2NdIjpSSGOTUz9Y5eTkabN4ogWfUn_n60Xbyd4

Primer Podataka Unutar Tokena Zahteva:

{
  "merchantUsername": "Ips_Acceptico",
  "uniqueMerchantTransactionId": "UNIQUE628e830b1df19",
  "customerId": "1254962485",
  "reference": "Proizvoljna referenca",
  "paymentPurposeCode": "221",
  "paymentType": "K",
  "paymentDescription": "description test",
  "beneficiaryName": "ben name",
  "beneficiaryAddress": "ben address",
  "beneficiaryPlace": "ben place",
  "beneficiaryRefModel": "",
  "beneficiaryRefNumber": "ref num",
  "amount": "300000",
  "exponent": "2",
  "currencyCode": "941",
  "accountNumber": "111600000080364937",
  "exp": 1653508629
}

Primer Odgovora Servisa:

Primer Podataka Unutar Tokena Odgovora:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqd3RVc2VybmFtZSI6Iklwc19BY2NlcHRpY28iLCJvayI6eyJzdGF0dXMiOiJTIiwicGF5b3V0SWQiOiJwYXlvdXQuMjAyNDExMDQyMjEwMzUuNjcyOTM4NGJhMmRkYTMuMDI5NDM3NjEiLCJwcm9jZXNzb3JJZCI6IjUwMTgyMjE0NTA2NTc3NzgiLCJhbW91bnRUb1BheSI6IjMwMDAwMC4wMCIsImZlZSI6MCwiZGF0ZSI6IjIwMjItMDUtMjAiLCJtZXNzYWdlIjoiUGxhY2FuamUgdXNwZXNuby4ifSwiZXhwIjoxNjUzNTA4NjMwfQ.QQImUZ-a76AyFGCE40I-SdW-uAkknzKRxj7X7lx9wI0

Primer Podataka Unutar Tokena Odgovora:

{
  "jwtUsername": "Ips_Acceptico",
  "ok": {
    "status":"S",
    "payoutId": "payout.20241104221035.6729384ba2dda3.02943761",
    "processorId": "5018221450657778",
    "amountToPay": "300000.00",
    "fee": 0,
    "date": "2022-05-20",
    "message": "Placanje uspesno."
  },
  "exp": 1653508630
}

Kod Odgovor Komentar
200 
{
  "jwtUsername": "Ips_Acceptico",
  "ok": {
    "status":"S",
Uspešna isplata na tekuci racun
200 
{
  "jwtUsername": "Ips_Acceptico",
  "ok": {
    "status":"D",
        .........
Isplata odbijena
200 
{
    "jwtUsername": "Ips_Acceptico",
    "error": {
        "message": "Losa stuktura odgovora od servisa.",
        "code": "1254896325741257"
        .........
Error poruka

Kontaktirajte nas da saznate više o tome kako Acceptico d.o.o. može unaprediti vaše poslovanje.