SDK Typescript

1 Przyklad uzycia SDK (Typescript)

Work in progress! - Draft [WIP]

  • uzupełnić o &sig=

1.1 Implementator (dostawca / sklep / uslugodawca) i inicjalizacja platnosci

Przygotowanie instancji dla rejestru pay.wdft.ovh

  const ps = new PaymentStandard("https://pay.wdft.ovh");

  const providers = await ps.providers();

Przykładowy set z providers w odpowiedzi:

[
  {
    id: "bank-tst",
    name: "bank testowy",
    prettyName: "Bank Testowy S.A.",
    logo: "https://pay.wdft.ovh/assets/test-bank/logo.png",
    platforms: ["android", "ios"],
  },
]

Generowanie linku platniczego

  const paymentLink = ps.createPaymentLink({
    provider_id: "bank-tst",
    payment_id: "my-unique-payment-id",
    transfer_amount: "1.12",
    transfer_currency: "PLN",
    transfer_description: "Demo payment for article",
    receiver_name: "Gazeta Wyborna S.A.",
    receiver_address: "ul. Wyspiańska 10, 00-001 Warszawa",
    receiver_country: "PL",
    payload: "",
    receiver_iban: "PL22294000000000000000000000",
    // In this case pay.wdft.ovh is not an role as registry! it's our saas payment provider here you need to implement this endpoint
    webhook_confirm_url: "https://pay.wdft.ovh/webhook/:status",
  });

Następnie parsujemy link

  const parsed = new URL(paymentLink);

Link ten w oparciu o konfiguracje aplikacji bankowej zostanie uruchomiony przez “aplikacje bankowa”

https://pay.wdft.ovh/pay/wdft?wh=https%3A%2F%2Fpay.wdft.ovh%2Fwebhook%2F%3Astatus%3Fprovider_id%3Dsample-provider-id-from-registry%26payment_id%3Dsample-id%26payload%3D%26transfer_amount%3D1000.00%26transfer_currency%3DPLN%26transfer_description%3DDemo%2Bpayment%2Bfor%2Barticle%26receiver_name%3DWDFT%2BPSA%26receiver_address%3Dul.%2BWyspian%25CC%2581ska%2B10%252C%2B00-001%2BWarszawa%26receiver_country%3DPL%26receiver_iban%3DPL22294000000000000000000000

Możemy też z niego wygenerować kod QR dla płatności

W momencie kliknięcia zostaniemy przekierowani na aplikację. W przypadku braku aplikacji na stronę placeholder.

1.2 Bank

W momencie kiedy użytkownik przechodzi do aplikacji bankowej, bank musi:

  • odczytać parametry
  • zwalidować sumę kontrolną [WIP]
  • uzupełnić templatkę
  • potwierdzić operację (UI) - complete
  • potwierdzić operację (Backend) - confirm
1.2.1 Applikacja bankowa

Bank w momencie uruchomienia parsuej dane tj. poprzez pobranie paremtru wh:

  const webhookCallbackUrl = parsed.searchParams.get("wh")!;

Rozparsowywując link

https://pay.wdft.ovh/webhook/:status?provider_id=sample-provider-id-from-registry&payment_id=sample-id&payload=&transfer_amount=1000.00&transfer_currency=PLN&transfer_description=Demo+payment+for+article&receiver_name=WDFT+PSA&receiver_address=ul.+Wyspiańska+10,+00-001+Warszawa&receiver_country=PL&receiver_iban=PL22294000000000000000000000

Uzyskujemy parametry:

[
  [ "transfer_amount", "1000.00" ],
  [ "transfer_currency", "PLN" ],
  [ "transfer_description", "Demo payment for article" ],
  [ "receiver_name", "WDFT PSA" ],
  [ "receiver_address", "ul. Wyspiańska 10, 00-001 Warszawa" ],
  [ "receiver_country", "PL" ],
  [ "receiver_iban", "PL22294000000000000000000000" ]
]

W momencie wykonania przelewu w aplikacji bankowej, Bank generuje wygnature w oparciu o klucz “complete” (kliencki) i robi call na payment link tj.

:status zostaje zastapiony complete a nastepnie obliczona jest sygnatura zgodnie z kluczem i podczas callu dodanie x-pay-signature

await ps.complete(webhookCallbackUrl, "client-secret");

albo odrzuca, :status zostaje zastapiony “reject”

  await ps.reject(webhookCallbackUrl, "client-secret");
1.2.2 Backend bankowy

Bank w momencie dopisania transakcji do tablicy elixir już bez możliwości wycofania transakcji przez użytkownika zatwierdza ją.

:status zostaje zastapiony confirm a nastepnie obliczona jest sygnatura zgodnie z kluczem i podczas callu dodanie x-pay-signature

  await ps.confirm(webhookCallbackUrl, "backend-secret");

1.3 Impelmentator (dostawca / sklep / uslugodawca)

W momencie kiedy, sprzedawca otrzymuje webhook na /webhook/:status w body otrzymuje encoded_url oraz w naglowki x-pay-signature

Implementator robi “verify” w rejestrze w ktorym inicjalizowal “payment link”

  const data = await ps.verifySignatureAndDecode(request.url, request.headers['x-pay-signature'])

W zaleznosci od :status:

  • confirmed - przelew zlecony, nie moze zostac wycofany, mozna wysylac towar,
  • completed - ui bankowe przeszlo, przelew zlecony, mozna udostepnic tanie “tresci” online,
  • rejected - odrzucona przez usera, niezrealizowana

W przypadku braku otrzymania webhook - timeout do 5 minut, nie przetwarzac.

2025 wdft psa.