Transaction link REST API

1. Historia zmian

Ostatnia aktualizacja dokumentu: 2022-08-23 15:24:38 +0200

Table 1. Historia zmian
wersja	opis
v1	-
v2	format zwracanych odpowiedzi
v3	zmianay w adresach URL
v4	dostosowanie do zmian w VPOS 3.9.6
v5	usunięte pole `merchantCode` z find txn links
v6	find txn links - dł. orderCode zmieniona na 50 znaków
v7	find txn links - dodany status linku
v8	dodana sekcja 'Generator nieaktywny'
v9	register card link - aktualizacja

2. Register transaction link

2.1. Endpoint URL

Method: POST
URL: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/{merchantCode}/links
URL - przykład: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/81102837/links

2.2. Wymagane nagłówki

Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxx

Uwierzytelnienia REST odbywa się za pomocą danych dostępowych do GUI VPOS, gdzie login jest złożony z MID i loginu odzielonego kropką -> 80000000.login
Zalecamy utworzenie odrębnego użytkownika ze wszystkimi rolami do autentykacji żądań REST.

2.3. Body

{
 "posIdentifier":"73666164",
 "paymentMethod":"CARD", # (1)
 "txnLanguage":"PL",
 "amount":"1900",
 "currency":"PLN", # (2)
 "orderCode":"ORDERCODE!",
 "merchantLabel":"merchantlabel",
 "customerBusinessName": "customerBusinessName",
 "customerName":"customerName",
 "customerSurname":"customerSurname",
 "customerEmail":"customerEmail@customerEmail.pl",
 "customerCountry":"PL",
 "expirationDate":"2019-02-21 12:21", # (3)
 "additionalEmail":"additionalEmail@additionalEmail.pl",
 "emailDescription":"emailDescription asfgfsadf",
 "preauth": "false"
}

dopuszczalne wartości to CARD, ETRANSFER, MASTERPASS, PSP. Brak parametru paymentMethod w żądaniu wywoła pamentwall ze wszystkimi, dostepnymi metodami płatności
zawsze PLN
yyyy-MM-dd HH:mm (where HH:mm is optional)

2.4. Walidacja pól

Zgodnie z adnotacjami poniżej.

public class TxnLinkType {

        @NotEmpty(name = "posIdentifier", max = 20)
        @Pattern(regexp = "^[0-9]{1,20}$")
        private String posIdentifier;

        @Length(name = "paymentMethod", max = 10)
        @Pattern(regexp = "^CARD|ETRANSFER|MASTERPASS|PSP$")
        private String paymentMethod;

        @NotEmpty(name = "txnLanguage", max = 2)
        @Pattern(regexp = "^PL|EN|DE|RU|FR|IT|ES|PT$")
        private String txnLanguage;

        @NotEmpty(name = "amount", max = 10)
        @Pattern(regexp = "^[0-9]{1,10}$")
        private String amount;

        @NotEmpty(name = "currency", max = 3)
        @Pattern(regexp = "^PLN$")
        private String currency;

        @NotEmpty(name = "orderCode", max = 50)
        @Pattern(regexp = "^[^\"\'&<>@#%+]*$")
        private String orderCode;

        @Length(name = "merchantLabel", max = 50)
        @Pattern(regexp = "^[^%&+]*$")
        private String merchantLabel;

        @Length(name = "customerBusinessName", max = 50)
        @Pattern(regexp = "^[^%&+]*$")
        private String customerBusinessName;

        @Length(name = "customerName", max = 20)
        @Pattern(regexp = "^[^%&+]*$")
        private String customerName;

        @Length(name = "customerSurname", max = 30)
        @Pattern(regexp = "^[^%&+]*$")
        private String customerSurname;

        @Length(name = "customerEmail", max = 254)
        @Pattern(regexp = "^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$")
        private String customerEmail;

        @NotEmpty(name = "customerCountry", max = 2)
        @Pattern(regexp = "^[a-zA-Z]{2}$")
        private String customerCountry;

        @NotEmpty(name = "expirationDate")
        @Pattern(regexp = "^\\d{4}-\\d{2}-\\d{2}( \\d{1,2}:\\d{2})?$") // yyyy-MM-dd HH:mm (where HH:mm is optional)
        private String expirationDate;

        @Length(name = "additionalEmail", max = 254)
        @Pattern(regexp = "^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$")
        private String additionalEmail;

        @Length(name = "additionalEmail", max = 500)
        private String emailDescription;

        private Boolean preauth;   //optional

        // ...

}

2.5. Zwracane kody odpowiedzi

200 OK // link zapisany
400 Bad Request // błędne dane wejściowe, szczegóły w zwróconej przez VPOSa odpowiedzi
500 Internal Server Error // odpowiednik 006 z formatki, szczegóły w zwróconej przez VPOSa odpowiedzi

2.6. Przykładowe odpowiedzi

200 OK

{
  "linkUrl": "https://vpos.polcard.com.pl/vpos/ecom/link/9BaamroHV4o",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABYklEQVR42u2YQY7DMAhF8Ypj+KYT56Y+RlZm+B9SqVN1U41kFrWsquZlQTAf44i9G/IlH5JLfDT/e3Wfp9mAodcg3a2n2y7nsxHCWIMMiZUc/gZqeKQUocs/IofVI25WG2pWjMSKLrvjL3mwk1AlyMScf/Szk+SYovO4+tKXurORwGt4SolMBFWx8yWI0VmJmpdSLkPstsHlA4k5mxUhNJgt5uPSKYhuL0FipTgrMq56Z+J+4s56aYE+oGAEVe4c3U76gNfY85OVD2rOLmA7wTl2XGxSWGPcvIqQbE/649AQfdTE3YQGbC8zcbHsLS1CQhyTvee922UIZzbFrC4IcBFyMgFbFj8ebun1bhIDOkZKxkusIiS7J+Rj3iTiMlGC9Dhs4SnDmb81CG8SmCt6KKlGJPr0FRLJiFYhjVqJu86tn/0kDo3Bbn2w8j3dwHaSVElj72n8GtGe9LOPfL9X/S/5BfLbESPTEbnhAAAAAElFTkSuQmCC"
}

400 Bad Request

{
 "fault":"Global rest service exception occurred.",
 "message":"TxnLinkRestServiceBean#registerTxnLink(arg1).paymentMethod must match \"^CARD|ETRANSFER|MASTERPASS|PSP$\"",
 "errorCode":null
}

500 Internal Server Error

{
 "fault":"Internal error occurred.",
 "message":"expirationDate must be in the future",
 "errorCode":"validationError"
}

500 Internal Server Error

{
 "fault":"Internal error occurred.",
 "message":"Unparseable date: \"2022-02-35 12:21\"",
 "errorCode":null
}

3. Register card link

3.1. Endpoint URL

Method: POST
URL: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/{merchantCode}/links/cards
URL - przykład: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/81102837/links/cards

3.2. Wymagane nagłówki

Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxx

3.3. Body

{
 "posIdentifier":"73666164",
 "amount":"1900",
 "currency":"PLN", # (1)
 "orderCode":"ORDERCODE!",
 "customerBusinessName": "customerBusinessName",
 "customerEmail":"customerEmail@customerEmail.pl",
 "expirationDate":"2019-02-21 12:21", # (2)
 "additionalEmail":"additionalEmail@additionalEmail.pl",
 "emailDescription":"emailDescription asfgfsadf",
 "preauth": "false",
 "sendEmail": "false"
}

zawsze PLN
yyyy-MM-dd HH:mm (where HH:mm is optional)

3.4. Walidacja pól

Zgodnie z adnotacjami poniżej.

public class CardLinkType {

        @NotEmpty(name = "posIdentifier", max = 20)
        @Pattern(regexp = "^[0-9]{1,20}$")
        private String posIdentifier;

        @Length(name = "amount", max = 10)
        @Pattern(regexp = "^[0-9]{1,10}$")
        private String amount;

        @Length(name = "currency", max = 3)
        @Pattern(regexp = "^PLN$")
        private String currency;

        @NotEmpty(name = "orderCode", max = 50)
        @Pattern(regexp = "^[^\"\'&<>@#%+]*$")
        private String orderCode;

        @Length(name = "customerBusinessName", max = 50)
        @Pattern(regexp = "^[^%&+]*$")
        private String customerBusinessName;

        @NotEmpty(name = "customerEmail", max = 254)
        @Pattern(regexp = "^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$")
        private String customerEmail;

        @NotEmpty(name = "expirationDate")
        @Pattern(regexp = "^\\d{4}-\\d{2}-\\d{2}( \\d{1,2}:\\d{2})?$") // yyyy-MM-dd HH:mm (where HH:mm is optional)
        private String expirationDate;

        @Length(name = "additionalEmail", max = 254)
        @Pattern(regexp = "^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$")
        private String additionalEmail;

        @Length(name = "additionalEmail", max = 500)
        private String emailDescription;

        private Boolean preauth;   //optional default false

        private Boolean sendEmail; //optional default true

        // ...

}

3.5. Zwracane kody odpowiedzi

200 OK // link zapisany
400 Bad Request // błędne dane wejściowe, szczegóły w zwróconej przez VPOSa odpowiedzi
500 Internal Server Error // odpowiednik 006 z formatki, szczegóły w zwróconej przez VPOSa odpowiedzi

3.6. Przykładowe odpowiedzi

200 OK

{
 "linkUrl":"https://vpos.polcard.com.pl/vpos/card/link/kweFB2rErVB",
 "qrCodeImage":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABWElEQVR42u2YQW7EIAxFzYpjcNNJclOOkRXU/9tM26m6qSrxF4NQFPyycGz8TWLzt2Fv8kdym4/it3fzec15wtA0SHPr5bbbeS+EMGqQ02Jlh79BnXhEimBlD7Nj6pHZH9bOOqcYiZWH8yB/3Qc7CasEOzHnS/3sJDm6l8hxt1F/6M5GAq/hKUukI6jVpwaB1MFZ34bPUlYh2IMwXCuojK4IacNcV2Bgtrshuk2CZJfoVD52s7r26HZCUXExHsYKhu+f2d5OyhLmQuXz91i6s5+kHldsRkO2Pf8yBIY0x/2XbG8m2fxTZuD+qCIEzR+VQVXObMuQbPu8Ul1QLiJk4KTZ6D40xuIYpUBi0HCt74khQtbpiS13HaOmCOGpk+oSvudVg5zRK+j+wasYQZv1JEdPS+VTIdH/EdcUGw0SX9WntXgqziwaZFUJW0eJWvleP9vI+3/V/5IPTfwWjZHtNfIAAAAASUVORK5CYII="
}

500 Internal Server Error

{
 "fault":"Internal error occurred.",
 "message":"Unparseable date: \"2022-02-35 12:21\"",
 "errorCode":null
}

400 Bad Request

{
 "fault":"Global rest service exception occurred.",
 "message":"TxnLinkRestServiceBean#registerCardLink(arg1).currency must match \"^PLN$\"",
 "errorCode":null
}

4. Deactivate transaction link

4.1. Endpoint URL

Method: POST
URL: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/{merchantCode}/links/{linkId}/deactivate
URL - przykład: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/81102837/links/5K0KQJHdgHi/deactivate

4.2. Wymagane nagłówki

Jak dla register txn link i register card link.

4.3. Body

Brak (empty)

4.4. Walidacja pól

Zgodnie z adnotacjami poniżej.

@Pattern(regexp = "^[0-9]{1,20}$") @PathParam("merchantCode") String merchantCode,
@Pattern(regexp = "^[a-zA-Z0-9_\\-]{11}$") @PathParam("linkId") String linkId

4.5. Zwracane kody odpowiedzi

200 OK // link zdezaktywowany
400 Bad Request // błędne dane wejściowe, szczegóły w zwróconej przez VPOSa odpowiedzi
500 Internal Server Error // odpowiednik 006 z formatki, szczegóły w zwróconej przez VPOSa odpowiedzi

4.6. Przykładowe odpowiedzi

Note	W przypadku `200 OK` nie jest zwracana żadna odpowiedź (puste body).

400 Bad Request

{
  "fault": "Link not found.",
  "message": "Entity: EPaymentLink not found. Business key name: merchantCode, link url, value: 81102837, 5K0KQJHdgHs",
  "errorCode": "entityNotFound"
}

5. Change link expiration date

5.1. Endpoint URL

Method: POST
URL: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/{merchantCode}/links/{linkId}/change-date
URL - przykład: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/81102837/links/pTqjFv51ov8/change-date

5.2. Wymagane nagłówki

Jak dla register txn link i register card link.

5.3. Body

{
"expirationDate":"2020-09-09" # (1)
}

yyyy-MM-dd HH:mm (where HH:mm is optional)

5.4. Walidacja pól

Zgodnie z adnotacjami poniżej.

@Pattern(regexp = "^[0-9]{1,20}$") @PathParam("merchantCode") String merchantCode,
@Pattern(regexp = "^[a-zA-Z0-9_\\-]{11}$") @PathParam("linkId") String linkId

public class LinkExpDateType {

        @NotEmpty(name = "expirationDate")
    @Pattern(regexp = "^\\d{4}-\\d{2}-\\d{2}( \\d{1,2}:\\d{2})?$") // yyyy-MM-dd HH:mm (where HH:mm is optional)
        private String expirationDate;

        // ...

}

5.5. Zwracane kody odpowiedzi

200 OK // data zmieniona
400 Bad Request // błędne dane wejściowe, szczegóły w zwróconej przez VPOSa odpowiedzi
500 Internal Server Error // odpowiednik 006 z formatki, szczegóły w zwróconej przez VPOSa odpowiedzi

5.6. Przykładowe odpowiedzi

Note	W przypadku `200 OK` nie jest zwracana zadna odpowiedź (puste body).

400 Bad Request

{
  "fault": "Global rest service exception occurred.",
  "message": "TxnLinkRestServiceBean#changeExpirationDate(arg2).expirationDate must match \"^\\d{4}-\\d{2}-\\d{2}$\"",
  "errorCode": null
}

6. Find transaction links

6.1. Endpoint URL

Method: GET
URL: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/{merchantCode}/links;posIdentifier=xxxxxxxxxxx;orderCode=yyyyyyy
URL - przykład: https://vpos.polcard.com.pl/vpos/epayment/rest/merchants/81102837/links;posIdentifier=73666164;orderCode=123

6.2. Wymagane nagłówki

Jak dla register txn link i <<registerCardLinkHeaders, register card link>.

6.3. Body

Brak (empty)

6.4. Walidacja pól

Zgodnie z adnotacjami poniżej.

@Pattern(regexp = "^[0-9]{1,20}$") @PathParam("merchantCode") String merchantCode,
@Pattern(regexp = "^[0-9]{1,20}$") @MatrixParam("posIdentifier") String posIdentifier # <1>,
@Pattern(regexp = "[^\"\'&<>@#]{1,50}") @MatrixParam("orderCode") String orderCode) # (2)

Pole nieobowiązkowe
Pole nieobowiązkowe

6.5. Zwracane kody odpowiedzi

200 OK // wszystko OK, odpowiedź w body
400 Bad Request // błędne dane wejściowe, szczegóły w zwróconej przez VPOSa odpowiedzi
500 Internal Server Error // odpowiednik 006 z formatki, szczegóły w zwróconej przez VPOSa odpowiedzi

6.6. Przykładowe odpowiedzi

Note	Kolejność rekordów w odpowiedzi Wyszukiwanie zwraca rekordy posortowane od najnowszego (liczy się data rejestracji linku w VPOSie) do najstarszego.

200 OK

{
  "records": [{
    "posIdentifier": "73666164",
    "paymentMethod": null,
    "txnLanguage": "PL",
    "amount": "10000",
    "currency": "PLN",
    "orderCode": "123",
    "merchantLabel": "123",
    "customerBusinessName":"customerBusinessName",
    "customerName": "Test",
    "customerSurname": "Test",
    "customerEmail": "customer@email.qaz",
    "customerCountry": "PL",
    "expirationDate": "2018-08-29 12:21",
    "additionalEmail": "additional@email.qaz",
    "emailDescription": null,
    "status": 10 (1)
  }, {
    "posIdentifier": "73666164",
    "paymentMethod": null,
    "txnLanguage": "PL",
    "amount": "12300",
    "currency": "PLN",
    "orderCode": "123",
    "merchantLabel": null,
    "customerBusinessName":"customerBusinessName",
    "customerName": null,
    "customerSurname": null,
    "customerEmail": null,
    "customerCountry": "PL",
    "expirationDate": "2018-08-10 12:21",
    "additionalEmail": null,
    "emailDescription": null,
    "status": 10
  }],
  "recordsCount": 2, # (2)
  "moreRecordsExist": false, # (3)
  "moreRecordsExistMsg": null # (4)
}

Status linku. Możliwe wartości poniżej.
liczba zwróconych rekordów, max. 20
true jeśli w bazie VPOSa istnieje więcej niż 20 rekordów, które spełniają kryteria
Jeśli moreRecordsExist == true to tutaj pojawi się komentarz: Response limited to the most recent 20 records. Provide more specific search criteria to narrow down returned results.

Możliwe wartości pola status linku

        // created
        CREATED(10),
        // sent automatically from system (via e-mail)
        AUTO_SENT(20),
        // link consumed, payment not finished
        PENDING(30),
        // link consumed, payment performed successfully
        PAID(40),
        // link expired
        EXPIRED(50),
        // cancelled by merchant
        CANCELLED(60);

400 Bad Request

{
  "fault": "Logged merchant code [81102837] does not match merchant code provided in REST request [81102836]",
  "message": "Logged merchant code [81102837] does not match merchant code provided in REST request [81102836]",
  "errorCode": "cardAcceptorInvalid"
}

7. Generator nieaktywny

Przy próbie wywołania Transaction link REST API dla merchanta, któremu usługa została wyłączona (lub nie została jeszcze aktywowana), system na każde zapytanie odpowiada następującym komunikatem:

403 Forbidden

{
  "fault": "Forbidden request.",
  "message": "Transaction link generator not enabled for MID 81102837",
  "errorCode": "configurationError"
}