Utworzenie linku do płatności
W celu utworzenia linku, należy wysłać zapytanie na adres:
POST /pay/v1/payments
curl --location --request POST 'https://pay.billtech.pl/pay/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0Cg==' \
--data-raw '{
"payments": [
{
"userId": "user-1234",
"amount": 123.45,
"nrb": "28616102383202382844889825",
"title": "FV 123/2020",
"paymentDue": "2020-07-23",
"name": "Jan",
"surname": "Kowalski",
"email": "[email protected]",
"operationId": 13912
}
]
}'
| atrybut | opis |
|---|---|
| payments: array | Lista płatności, dla których ma być wygenerowany link |
| userId: string | Identyfikator klienta w systemie dostawcy (max 100 znaków) |
| amount: number | Należna kwota |
| nrb: string | Numer konta bankowego do przelewu w formacie BBAN |
| title: string | Tytuł opłaty (max 105 znaków), dopuszczalne znaki: A-Za-z0-9#&_-,./ oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne) |
| paymentDue: string | Termin płatności (format yyyy-mm-dd) |
| name: string | Imię płatnika (opcjonalne, max 100 znaków) Dopuszczalne znaki: A-Za-z0-9-,. oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne) |
| surname: string | Nazwisko (opcjonalne, max 100 znaków) Dopuszczalne znaki: A-Za-z0-9-,. oraz znak spacji(0x20) i znaki z zakresu UNICODE 00C0 - 02C0 (m.in. polskie znaki diakrytyczne) |
| email: string | Adres e-mail płatnika (opcjonalny) |
| operationId: string | Identyfikator płatności w systemie dostawcy (opcjonalny, max 100 znaków). W przypadku podania tego parametru tworzone/aktualizowane linki muszą być unikalne ze względu na parę: userId, operationId. |
{
"links": [
{
"token": "e64a219df20884e4db40b7f99ac2cef9c08650f22e74ca6d09f49ad24734ae75c388b7052500033b693ae29edb2ed9d8ccfa85e66023c9e023eac4f353e2be05",
"link": "https://pay.billtech.pl/single-payment/e64a219df20884e4db40b7f99ac2cef9c08650f22e74ca6d09f49ad24734ae75c388b7052500033b693ae29edb2ed9d8ccfa85e66023c9e023eac4f353e2be05",
"shortLink": "https://zapl.ac/SscsYRx7qy"
}
]
}
| atrybut | opis |
|---|---|
| links: array | Lista linków w kolejności odpowiadającej zapytaniu |
| token: string | Token służący identyfikacji danego linku do płatności |
| link: string | Pełny link do płatności |
| shortLink: string | Skrócony link do płatności |
Możliwe jest wygenerowanie wielu linków (maksymalnie 100) w pojedynczym zapytaniu. Kolejność wygenerowanych linków odpowiada kolejności płatności w zapytaniu.
Przed dystrybucją linków do użytkowników należy dodać do nich dane osobowe klientów w postaci parametrów, np.:
https://pay.billtech.pl/single-payment/e64a219df20884e4...
?name=Jan&surname=Kowalski&[email protected]
Sugerujemy, by system Dostawcy zapisał utworzony link w relacji z konkretną fakturą. W ten sposób link tworzony jest raz dla danej faktury, a następnie można dołączyć go do wiadomości e-mail czy sms, a także wyświetlić w panelu online użytkownika. System powinien zapisać również token, który jest potrzebny do anulowania linku do płatności.
Utworzenie linku do płatności powoduje pojawienie się opłaty przypisanej do danego użytkownika w ekosystemie. Użytkownik widzi tę opłatę w swojej ulubionej aplikacji, nawet jeśli nie wejdzie w wygenerowany link. Z tego powodu najlepszym momentem utworzenia linku jest moment powstania należności (np. wystawienie faktury).
Płatność za saldo
Jeśli w danym momencie użytkownik ma kilka aktywnych linków (nieopłaconych faktur), to po wejściu na dowolny z tych linków będzie on widział informację o łącznym saldzie. Będzie mógł wtedy zdecydować czy chce zapłacić za pojedynczą fakturę czy spłacić całe saldo.
Istnieje możliwość skierowanie użytkownika bezpośrednio na spłatę salda poprzez dodanie parametru type=balance
do dowolnego aktywnego linku, np.:
https://pay.billtech.pl/single-payment/e64a219df20884e4...
?name=Jan&surname=Kowalski&[email protected]
&type=balance
Przykładowym przypadkiem użycia takiego linku jest ekran blokady usług lub wiadomość e-mail przypominająca o zadłużeniu.
Połączenie konta w ekosystemie
Połączenie konta w ekosystemie oznacza połączenie konta użytkownika w Systemie Dostawcy z ulubioną aplikacją użytkownika
w ekosystemie BillTech. Pierwszym sposobem, w jaki użytkownik może połączyć konto, jest wejście w link do płatności, a następnie
wybranie opcji rejestracji. Po zarejestrowaniu w aplikacji, konto użytkownika w Systemie Dostawcy będzie automatycznie połączone.
Od tej pory kolejne opłaty dodane do ekosystemu poprzez utworzenie linku do płatności będą automatycznie pojawiać się na koncie użytkownika w aplikacji.
Połączenie konta z pominięciem podsumowania płatności
Istnieje możliwość skierowania użytkownika bezpośrednio na rejestrację w aplikacji, bez pokazywania ekranu płatności.
W tym celu, do dowolnego aktywnego linku należy dodać parametrów type=connect oraz connectApp=<id aplikacji> np.:
https://pay.billtech.pl/single-payment/e64a219df20884e4...
?name=Jan&surname=Kowalski&[email protected]
&type=connect&connectApp=MU
Skrócony link
Pole shortLink w odpowiedzi zawiera skrócony link do płatności, który może być użyty np. w wiadomości SMS, gdzie występuje ograniczenie liczby znaków.
Skrócone linki są zwracane tylko gdy w zapytaniu podane są dane osobowe tj. name oraz surname.
W przypadku skróconego linku funkcjonują inne zasady dołączania parametrów, np. type. Aby dodać parametry do linku jednocześnie zachowując
jego niewielką długość, należy skorzystać z serwisu https://zapl.ac/encode:
POST https://zapl.ac/encode
curl --location --request POST 'https://zapl.ac/encode?type=connect&connectApp=MU' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://zapl.ac/SscsYRx7qy"
}'
{
"url": "https://zapl.ac/SscsYRx7qy/24"
}
W powyższym przykładnie parametry: ?type=connect&connectApp=MU dodane do url zapytania zostały zakodowane do skróconego linku w postaci
trzech znaków: /24.