Integracja z Twoim serwisem

Dokumentacja dla merchantów

Utwórz zamówienie

Użyj metody public/exchanger/order/create

Nazwa Opis Typ
routeId id kierunku ObjectID
partner link partnera STRING
amount kwota w FLOAT
fromValues[0][key] nazwa klucza ObjectID
fromValues[0][value] wartość dla tego pola STRING
toValues[0][key] nazwa klucza STRING
toValues[0][value] wartość dla tego pola STRING
routeValues[0][key] nazwa klucza ObjectID
routeValues[0][value] wartość dla tego pola STRING
lang język klienta (ru, en) STRING
agreement zgoda BOOLEAN
hideOutData zabezpiecz dane wyjściowe BOOLEAN
clientCallbackUrl callback po zakończeniu zamówienia: klient zobaczy przycisk powrotu na stronę i zostanie przekierowany na ten URL ?status=success lub ?status=error STRING
ipnUrl url natychmiastowego powiadomienia o płatności (zostanie wywołane, gdy zamówienie zmieni status) STRING
ipnSecret ciąg do utworzenia bezpiecznego hasha w ipn url STRING

Dokumentację systemu autoryzacji znajdziesz w panelu osobistym. Więcej o pracy z metodami i dodatkowymi danymi znajdziesz na

IPN (Powiadomienie o zmianie statusu zamówienia płatności)

Aby otrzymywać powiadomienie o zmianie statusu zamówienia podczas jego tworzenia, należy przekazać dodatkowe parametry:

  • clientCallbackUrl - callback po zakończeniu zamówienia: klient zobaczy przycisk powrotu na stronę i zostanie przekierowany na ten URL
  • hideOutData - ukryj dane odbiorcy
  • ipnUrl - Link HTTP/HTTPS do powiadomienia Twojego serwera.
  • ipnSecret - Losowy ciąg do utworzenia podpisu żądania (dla zachowania integralności żądania)
  1. Żądanie zostanie wysłane metodą POST
  2. IPN zostanie wysłane jednokrotnie
  3. Dostarczenie IPN nie jest gwarantowane (jeśli serwer nie odpowiedział na żądanie, nie zostanie ono wysłane ponownie)

Przykład IPN

  • POST
  • ['Content-Type'] = 'application/x-www-form-urlencoded'


  • orderUID :Number() - zamówienie uid
  • orderId :String(ObjectId) -zamówienie id
  • newStatus :String() - zamówienie bieżący status
  • inAmount :String(number) - order in sum
  • outAmount :String(number) - order out sum
  • xml_from :String() - zamówienie uid
  • xml_to :String() - zamówienie uid
  • timestamp :Number() - unix-czas powiadomienia ipn
  • toValues :Array([{key,name,value}]) - dane zamówienia

Lista statusów

  • new - nowe zamówienie
  • waitPayment - oczekiwanie na płatność użytkownika
  • errorPayment - błąd płatności użytkownika (merchant wysłał błąd)
  • inProgress - w trakcie (oczekuje na administratora lub płatność zamówienia)
  • inProgressPayout - w kolejce do wypłaty (płatność przyjęta pomyślnie) (jeśli w walucie skonfigurowano autowypłatę, zostanie zainicjowana)
  • errorPayout - błąd wypłaty (podczas wypłaty wystąpił błąd)
  • hold - zamrożone (problemy z zamówieniem)
  • done - zamówienie zrealizowane pomyślnie
  • returned - zamówienie zostało opłacone, ale nie wszystkie warunki wymiany zostały spełnione i środki zwrócono nadawcy
  • deleted - zamówienie usunięte (anulowane)

Weryfikacja sumy kontrolnej żądania (IPN)

sha256(orderId:newStatus:inAmount:outAmount:xml_from:xml_to:timestamp:ipnSecret)

        
const stringForHash = orderId+":"+newStatus+":"+inAmount+":"+outAmount+":"+xml_from+":"+xml_to+":"+timestamp+":"+ipnSecret;
// example string for hash 5d8e6002b80b7b4cd75a6424:inProgress:2:317.42:ETH:WMZ:1571328406072:SECRET123

const hash = crypto.createHash('sha256').update(stringForHash).digest('hex')
// example hash af3acf947e6f0e0f2c267e300b8582e504dba12d1f2d058652b7414163c09f48

Kontrola płatności

  1. Jeśli chcesz kontrolować status zamówień, twórz je z autoryzacją — wtedy wszystkie zamówienia będą widoczne w panelu osobistym;
  2. Możesz zapisać UID zamówienia i secret oraz ręcznie przejść do zamówienia, podając te dane w pasku adresu

Płatność

  1. Możesz użyć /payment/ do wyświetlenia strony płatności

    // schema
    https://hellchange.top/user-lang/payment/order-uid/order-secret
    // example result
    https://hellchange.top/en/payment/1409/dGqwF2M2eBPaSN1G5ljMS1cb
  2. Możesz też po prostu podać link do wymiany w takiej postaci, w jakiej widzą go wszyscy klienci, według tego samego schematu co w pierwszym wariancie, tylko /payment/ należy zastąpić przez /order/
  3. W metodzie są parametry, które pozwalają wyświetlić dane płatności lub formularz płatności na Twojej stronie — możesz z nich korzystać. WAŻNE: jeśli metoda z ręczną płatnością, po płatności należy zaktualizować status zamówienia z waitPayment na inProgress.

Informacje