ddebowczyk/api

Informacje ogólne

Adresy serwerów

Produkcyjne API: https://api.fiberpay.pl/1.0 frontend produkcyjny: https://fibepay.pl

API testowe: https://apitest.fiberpay.pl/1.0 frontend testowy: https://test.fiberpay.pl

Są to zupełnie rozdzielone środowiska (łącznie z infrastrukturą). Klucze API z jednego środowiska nie będą działać w drugim.

Klucze API

Do korzystania z API konieczne jest wygenerowanie kluczy:

• jawnego (publicKey) - używanego do przesyłania w ramach żądań API
• tajnego (secretKey) - używanego do podpisywania żądań (nigdy nie powinien by przesyłany lub ujawniany)

Nagłówki

Każde żądanie do API powinno posiadać następujące nagłówki:

• Content-Type - application/json
• Accept - application/json
• X-API-Key – wygenerowany klucz jawny
• X-API-Nonce – nonce w postaci liczba naturalnej, każdy następny nonce powinien być większy od poprzedniego (przykładowo można użyć timestampa lub zaokrąglonego microtime jeśli używamy PHP)
• X-API-Method-And-Uri – informacja o wywoływanej metodzie HTTP oraz URI
  • np. POST /api/order/create/massoutbound
  • np. POST /api/order/create/massoutbound/item
• X-API-Signature – podpis z użyciem skrótu sha512 stworzonego przy użyciu ‘message’, ‘nonce’, ‘apikey’, ‘requestBody’ i ‘secretkey’

Instrukcja utworzenia X-API-Signature

Należy utworzyć połączony ciąg znaków (concatenated string) składający się z message, nonce, apikey oraz requestBody (kolejność ma znaczenie!), a następnie wygenerować skrót sha512 z utworzonego ciągu używając secretkey.

• przykładowa impelmentacja w PHP:

$implodeParams = implode( ‘’, [$message, $nonce, $apikey, $requestBody]);
hash_hmac(‘sha512’, $implodeParams, $secretkey)

$requestBody to ciało (body) żądania HTTP. Gdy go brak to powinien zostać użyty pusty string ('').

Mechanizm callbacków

FiberPay posiada mechanizm tzw. callbacków. Poktualizacji zlecenia system FiberPay może wywołać żądanie HTTP na wskazany uprzednio adres, gdzie:

• w ciele (body) żądania będzie zawarty token JWT z aktualnymi danymi zlecenia,
• w nagłówku (header) żądania będzie zawarty jawny klucz API, wskazujacy który klucz tajny został wykorzystany do utworzenia JWT

Informacje jak odkodować lub jakich bibliotek użyć do obsługi tokenu JWT są pod adresem: https://jwt.io/

Opis usług

Direct transfer

Usługa pojedynczego przekazu pieniężnego na konkretne konto bankowe. Platforma korzystająca z API może założyć zlecenie, a następnie dostać potwierdzenie, gdy dany przekaz zostanie opłacony, a także gdy FiberPay wykonana już dany przekaz na wskazane konto.

POST /orders/direct

Utworzenie zlecenia. Parametry żądania:

Parametr	Opis
amount	(wymagane) kwota przekazu, decimal z maks. 2 miejscami po przecinku (np. 100.50)
currency	(wymagane) waluta, aktualnie dostępne tylko PLN
toName	(wymagane) nazwa odbiorcy,
toIban	(wymagane) IBAN odbiorcy,
description	tytuł przelewu,
metadata	opcjonalne dane przekazywane przez FiberPay w odpowiedzi,
callbackUrl	URL na który ma być wywołany callback
callbackParams	opcjonalne parametry callbacka

Przykładowa odpowiedź serwera

{
  "data": {
      "code": "gjrbwhcx96v7",
      "status": "defined",
      "type": "direct",
      "currency": "PLN",
      "amount": "100.0000",
      "feeAmount": "0.5000",
      "toName": "Michał",
      "toIban": "PL27114020040000300201355387",
      "metadata": null,
      "createdAt": "2020-09-18 17:02:42",
      "updatedAt": "2020-09-18 17:02:42"
  },
  "invoice": {
      "amount": "100.50",
      "currency": "PLN",
      "iban": "PL123400007",
      "description": "gjrbwhcx96v7"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/direct/gjrbwhcx96v7"
  }
}

GET /orders/direct/{code}

Parametr	Opis
code	(wymagane) kod zlecenia

DELETE /orders/direct/{code}

Anulowanie wcześniej utworzonego zlecenia (możliwe tylko dla jeszcze nieopłaconych zleceń).

Parametr	Opis
code	(wymagane) kod zlecenia

{
  "data": {
      "code": "gjrbwhcx96v7",
      "status": "cancelled",
      "type": "direct",
      "currency": "PLN",
      "amount": "100.0000",
      "feeAmount": "0.5000",
      "toName": "Michał",
      "toIban": "PL27114020040000300201355387",
      "metadata": null,
      "createdAt": "2020-09-18 17:02:42",
      "updatedAt": "2020-09-18 17:03:34"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/direct/gjrbwhcx96v7"
  }
}

FiberSplit

Usługa gdzie FiberPay może wykonać wiele przekazów pieniężnych w zamian za jedną opłatę (np. 100 przelewów na wybrane konta bankowe). Platforma korzystająca z API może założyć zlecenie, a następnie dostać potwierdzenie, gdy dany zostanie ono płacone, a także dostać informacje dot. statusu każdego ze zleconych przekazów pieniężnych.

Aby skorzystać z usługi należy:

• założyć zlecenie (POST /orders/massoutbound)
• dodać poszczególne przekazy pieniężne (POST /orders/massoutbound/item)
• zakończyć definicję zlecenia (PUT /orders/massoutbound/{code}/define)
• opłacić utworzone zlecenie

POST /orders/split

Tworzy zlecenie

Parametr	Opis
currency	(wymagane) waluta zlecenia, aktualnie wspieramy tylko PLN
metadata	opcjonalne dane przekazywane przez FiberPay w callbacku,

Przykładowa odpowiedź

{
  "data": {
      "code": "zc6ta75gfpme",
      "status": "open",
      "type": "split",
      "currency": "PLN",
      "metadata": null,
      "createdAt": "2020-09-18 17:05:32",
      "updatedAt": "2020-09-18 17:05:32",
      "items": []
  },
  "invoice": {
      "amount": "0.00",
      "currency": "PLN",
      "iban": null,
      "description": "zc6ta75gfpme"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/split/zc6ta75gfpme"
  }
}

POST /orders/split/item

Tworzy pojedynczy przelew do wysłania w ramach całego zlecenia.

Parametr	Opis
amount	(wymagane) kwota przelewu
currency	(wymagane) waluta przelewu (aktualnie wspierane tylko PLN)
parentCode	(wymagane) kod zlecenia nadrzędnego
toName	(wymagane) nazwa odbiorcy
toIban	(wymagane) IBAN odbiorcy
description	(wymagane) tytuł przelewu
metadata	opcjonalne dane przekazywane przez FiberPay w odpowiedzi,
callbackUrl	URL na który ma być wywołany callback
callbackParams	opcjonalne parametry callbacka

Przykładowa odpowiedź

{
  "data": {
      "code": "gmats9v3",
      "description": "testowy przelew",
      "status": "open",
      "type": "split_item",
      "currency": "PLN",
      "amount": "100",
      "feeAmount": "1.50",
      "toName": "Michał",
      "toIban": "PL27114020040000300201355387",
      "parentCode": "m9cqbfhk5x4e",
      "metadata": null,
      "createdAt": "2020-09-18 17:07:53",
      "updatedAt": "2020-09-18 17:07:53"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/split/item/gmats9v3"
  }
}

PUT /orders/split/{code}/define

Kończy tworzenie orderu (zamyka definicję).

Parametr	Opis
code	(wymagane) kod zlecenia

Przykładowa odpowiedź:

{
  "data": {
      "code": "m9cqbfhk5x4e",
      "status": "defined",
      "type": "split",
      "currency": "PLN",
      "metadata": null,
      "createdAt": "2020-09-18 17:06:30",
      "updatedAt": "2020-09-18 17:08:38",
      "items": [
          {
              "data": {
                  "code": "gmats9v3",
                  "description": "testowy przelew",
                  "status": "open",
                  "type": "split_item",
                  "currency": "PLN",
                  "amount": "100.0000",
                  "feeAmount": "1.5000",
                  "toName": "Michał",
                  "toIban": "PL27114020040000300201355387",
                  "parentCode": "m9cqbfhk5x4e",
                  "metadata": null,
                  "createdAt": "2020-09-18 17:07:53",
                  "updatedAt": "2020-09-18 17:07:53"
              },
              "links": {
                  "rel": "self",
                  "href": "https://apitest.fiberpay.pl/1.0/orders/split/item/gmats9v3"
              }
          }
      ]
  },
  "invoice": {
      "amount": "101.50",
      "currency": "PLN",
      "iban": "PL123400003",
      "description": "m9cqbfhk5x4e"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/split/m9cqbfhk5x4e"
  }
}

GET /orders/split/{code}

Pobranie informacji o całym zleceniu

Parametr	Opis
code	(wymagane) kod zlecenia

GET /orders/split/item/{code}

Pobranie informacji o poszczególnym przekazie pieniężnym

Parametr	Opis
code	(wymagane) kod zlecenia

FiberCollect

POST /orders/collect

Tworzy zlecenie

Parametr	Opis
currency	(wymagane) waluta przelewu (aktualnie wspierane tylko PLN)
toName	(wymagane) nazwa odbiorcy
toIban	(wymagane) IBAN odbiorcy
metadata	opcjonalne dane przekazywane przez FiberPay w odpowiedzi,

Przykładowa odpowiedź:

{
  "data": {
      "code": "w3taegy6fzuj",
      "status": "open",
      "type": "collect",
      "currency": "PLN",
      "toName": "Michał",
      "toIban": "PL27114020040000300201355387",
      "metadata": null,
      "createdAt": "2020-09-18 17:11:46",
      "updatedAt": "2020-09-18 17:11:46"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/collect/w3taegy6fzuj"
  }
}

POST /orders/collect/item

Tworzy pojedynczy przelew do wysłania w ramach całego zlecenia.

Parametr	Opis
amount	(wymagane) kwota przelewu
currency	(wymagane) waluta przelewu (aktualnie wspierane tylko PLN)
parentCode	(wymagane) kod zlecenia nadrzędnego
description	(wymagane) tytuł przelewu
metadata	opcjonalne dane przekazywane przez FiberPay w odpowiedzi,
callbackUrl	URL na który ma być wywołany callback
callbackParams	opcjonalne parametry callbacka

Przykładowa odpowiedź:

{
  "data": {
      "code": "xwbmedu9",
      "status": "open",
      "type": "collect_item",
      "currency": "PLN",
      "amount": "100",
      "feeAmount": "0.50",
      "toName": "Michał",
      "parentCode": "p4rtzey3hnwv",
      "description": "testowy przelew",
      "metadata": null,
      "createdAt": "2020-09-18 17:13:42",
      "updatedAt": "2020-09-18 17:13:42",
      "redirect": "https://test.fiberpay.pl/order/xwbmedu9"
  },
  "invoice": {
      "amount": "100.50",
      "currency": "PLN",
      "iban": "PL123400001",
      "bban": "123400001",
      "description": "xwbmedu9"
  },
  "links": {
      "rel": "self",
      "href": "https://apitest.fiberpay.pl/1.0/orders/collect/item/xwbmedu9"
  }
}

GET /orders/collect/{code}

Pobranie informacji o całym zleceniu

Parametr	Opis
code	(wymagane) kod zlecenia

GET /orders/collect/item/{code}

Pobranie informacji o pojedynczej wpłacie

Parametr	Opis
code	(wymagane) kod zlecenia

DELETE /orders/collect/item/{code}

Parametr	Opis
code	(wymagane) kod zlecenia

Przykładowa odpowiedź:

{
    "data": {
        "code": "xwbmedu9",
        "status": "cancelled",
        "type": "collect_item",
        "currency": "PLN",
        "amount": "100.0000",
        "feeAmount": "0.5000",
        "toName": "Michał",
        "parentCode": "p4rtzey3hnwv",
        "description": "testowy przelew",
        "metadata": null,
        "createdAt": "2020-09-18 17:13:42",
        "updatedAt": "2020-09-18 17:25:46",
        "redirect": "https://test.fiberpay.pl/order/xwbmedu9"
    },
    "invoice": [],
    "links": {
        "rel": "self",
        "href": "https://apitest.fiberpay.pl/1.0/orders/collect/item/xwbmedu9"
    }
}

Forward transfer

Usługa dwóch powiązanych przekazów pieniężnych, pozwalająca na przyjęcie przekazu pieniężnego, a następnie opłacenie innego przekazu ze środków pierwszego.

• Source - osoba opłacająca przekaz
• Target - odbiorca przekazu
• Broker - pośrednik (poza FiberPayem)

POST /orders/forward

Utworzenie zlecenia. Parametry żądania:

Parametr	Opis
sourceAmount	(wymagane) całościowa kwota przekazu, decimal z maks. 2 miejscami po przecinku (np. 100.50)
targetAmount	(wymagane) kwota przekazu, która trafi do odbiorcy, decimal z maks. 2 miejscami po przecinku (np. 100.50)
currency	(wymagane) waluta, aktualnie dostępne tylko PLN
targetName	(wymagane) nazwa odbiorcy,
targetIban	(wymagane) IBAN odbiorcy,
brokerName	(wymagane) nazwa pośrednika,
brokerIban	(wymagane) IBAN pośrednika,
description	tytuł przelewu,
targetDescription	(wymagane) Opis dla odbiorcy,
metadata	opcjonalne dane przekazywane przez FiberPay w callbacku,
callbackUrl	URL na który ma być wywołany callback
callbackParams	opcjonalne parametry callbacka

Przykładowa odpowiedź serwera:

{
    "data": {
        "code": "xbwucsgfn5pa",
        "status": "defined",
        "type": "forward",
        "currency": "PLN",
        "targetAmount": "100.0000",
        "targetName": "Target",
        "targetIban": "PL12340000TARGET",
        "targetDescription": "targetDescription",
        "brokerAmount": "48.7500",
        "brokerName": "Broker",
        "brokerIban": "PL12340000BROKER",
        "feeAmount": "1.2500",
        "createdAt": "2020-09-16 18:43:37",
        "updatedAt": "2020-09-16 18:43:37"
    },
    "invoice": {
        "amount": "150.00",
        "currency": "PLN",
        "iban": "PL123400005",
        "description": "n9t6k4zw"
    },
    "links": {
        "rel": "self",
        "href": "https://apitest.fiberpay.pl/1.0/orders/forward/xbwucsgfn5pa"
    }
}

GET /orders/forward/{code}

Parametr	Opis
code	(wymagane) kod zlecenia

GET /settlements

GET /settlements/{code}

Środowisko testowe

Dostępne są tutaj dodatkowe metody ułatwiające sprawdzanie działalności systemu oraz automatyzacja testów.

Automatyzacja testów

• Sprawdzenie nowych przelewów w systemie - co minutę
• Uruchomienie przetwarzania zleceń po otrzymaniu dla nich wpłaty - co minutę
• Wysyłanie callbacków - co minutę
• Przetwarzanie zleceń typu Collect - co godzinę
• Przetworzenie przelewów wychodzących - co minutę

Dodatkowe ścieżki

POST /bankTransactions

Symulacja przychodzącego przelewu bankowego.

Parametr	Opis
amount	(wymagane) kwota przelewu
currency	(wymagane) waluta przelewu (aktualnie wspierane tylko PLN)
fromName	(wymagane) nazwa nadawcy
fromIban	(wymagane) IBAN nadawcy
description	(wymagane) tytuł przelewu (kod zlecenia)

Przykładowa odpowiedź serwera:

{
    "data": {
        "contractorName": "TEST",
        "contractorIban": "PL12340000TEST",
        "amount": 100.5,
        "currency": "PLN",
        "description": "kn8sf7amj6xy",
        "bankReferenceCode": "kn8sf7amj6xy",
        "operationCode": "kn8sf7amj6xy",
        "accountIban": "PL123400007",
        "bookedAt": "2020-09-18 13:30:28",
        "createdAt": "2020-09-18 13:30:28",
        "updatedAt": "2020-09-18 13:30:28"
    }
}