Niestandardowa integracja płatności

Tematy w tym dokumencie:

• Przetwarzanie płatności przez zewnętrznych dostawców w Monetization
• Asynchroniczne przetwarzanie płatności
  • Eksportowanie faktur
    • Exporting job – plik CSV do SFTP
    • Notification - metoda webhook
  • Importowanie płatności
    • Import pliku CSV przez SFTP
    • Import przez wywołanie API
      • Uwierzytelnianie
      • Żądanie importu płatności
• Synchroniczne przetwarzanie płatności
  • Konfiguracja zewnętrznego dostawcy płatności
  • Operacje na klientach
    • Utworzenie klienta (bez karty)
    • Aktualizacja klienta
    • Odczyt klienta
    • Usunięcie klienta
  • Operacje na kartach
    • Setup (żądanie konfiguracji karty)
    • Usunięcie karty
  • Operacje transakcyjne
    • Authorization
    • Capture
    • Charge
    • Void
    • Refund
  • Obsługa błędów

Przetwarzanie płatności przez zewnętrznych dostawców w Monetization

Przetwarzanie płatności przez zewnętrznych dostawców można realizować dwiema metodami: synchroniczną i asynchroniczną. Metoda synchroniczna wymaga natychmiastowych odpowiedzi z komponentu integracji płatniczej, natomiast metoda asynchroniczna łączy eksport faktur z Monetization z późniejszym importem płatności.

Asynchroniczne przetwarzanie płatności

W przypadku asynchronicznego przetwarzania płatności eksportujesz faktury z Monetization, a same płatności są przetwarzane całkowicie poza Monetization. Gdy masz wyniki przetwarzania płatności, importujesz je przez pliki CSV albo przez API Monetization.

Eksportowanie faktur

Faktury z Monetization można eksportować, konfigurując mapper eksportu faktur i planując zadanie eksportu, które wyeksportuje pliki do lokalizacji SFTP, albo subskrybując zdarzenie utworzenia faktury przez Webhook, co wywoła żądanie faktury na podany adres URL zawsze wtedy, gdy zostanie utworzona nowa faktura.

Exporting job – plik CSV do SFTP

Aby eksportować faktury jako pliki CSV, należy skonfigurować mapper Invoice Export, który mapuje parametry faktury na kolumny pliku CSV. Interfejs użytkownika Monetization umożliwia taką konfigurację w sekcji Business configuration Export Invoice mappers.

Rysunek 1: Przykład konfiguracji mappera eksportu faktur

Eksporty faktur są planowane przez Exporting Jobs, które mogą być zadaniami jednorazowymi albo zautomatyzowanymi do uruchamiania w określonych okresach. Exporting Job zapisze wyeksportowany plik CSV w odpowiedniej lokalizacji SFTP storage/invoice/folder_name/file_name.csv.

Rysunek 2: Przykład zadania eksportu faktur

Notification - metoda webhook

Eksportowanie faktur przez webhooki pozwala otrzymywać faktury natychmiast po ich utworzeniu. Osiąga się to przez skonfigurowanie Invoice Notification Rule, która wysyła każdą utworzoną fakturę jako żądanie z treścią JSON na podany adres URL wraz ze wszystkimi wstępnie skonfigurowanymi opcjami nagłówków.

Rysunek 3: Przykład konfiguracji webhooka tworzenia faktury

Importowanie płatności

Transakcje płatnicze można importować do Monetization, konfigurując mapper importu płatności i przesyłając pliki CSV płatności do wejściowej lokalizacji SFTP albo korzystając z REST API Monetization.

Import pliku CSV przez SFTP

Aby Monetization mogło importować transakcje płatnicze przez pliki CSV, musi być skonfigurowany Payment Import Mapper. Konfigurację można wykonać w interfejsie użytkownika Monetization w sekcji Business configuration Import Payment mappers.

Payment mapper pozwala mapować kolumny CSV na parametry transakcji płatniczej oraz zdefiniować prefiks pliku, który musi występować w przesyłanych plikach.

Pliki są przesyłane na serwer SFTP do folderu edl/input, a następnie przenoszone do folderu edl/processed, edl/successful, edl/error albo edl/rejected zależnie od wyników przetwarzania.

Rysunek 4: Przykład konfiguracji mappera importu płatności

Import przez wywołanie API

Aby zaimportować transakcję płatniczą przez API Monetization, wyślij żądanie JSON ze szczegółami transakcji do REST API Monetization.

Uwierzytelnianie

API Monetization używa uwierzytelniania Bearer Token:

1. Wykonaj żądanie Authentication z nazwą użytkownika, hasłem i konkretnym kodem witryny.
2. Pobierz token z odpowiedzi.
3. Ustaw nagłówek Authorization na Bearer <token> w kolejnych żądaniach.
4. Token wygasa po 5 minutach.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}

Żądanie importu płatności

URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Synchroniczne przetwarzanie płatności

Synchroniczne przetwarzanie płatności wymaga synchronicznej komunikacji między Monetization a Twoim komponentem integracji płatniczej. Ta metoda przetwarzania umożliwia autoryzacje kart kredytowych/debetowych oraz natychmiastowe płatności.

Konfigurujesz Monetization, aby określić, dokąd mają być wysyłane żądania związane z przetwarzaniem płatności, a Monetization ma zdefiniowane odpowiedzi, których oczekuje w zamian. Ta metoda przetwarzania umożliwia przechowywanie referencji metod płatności przy klientach i obsługuje zautomatyzowane procesy pobierania płatności.

Dla Monetization proces integracji jest praktycznie taki sam jak standardowa integracja z istniejącym dostawcą, takim jak Stripe czy Braintree. Komunikacja odbywa się jednak przez opracowany przez Ciebie komponent, który działa jako bramka do lokalnego dostawcy płatności.

Podstawowe operacje wymagane do obsługi synchronicznego przetwarzania płatności:

• Setup Intent
• Authorize
• Capture
• Charge

Konfiguracja zewnętrznego dostawcy płatności

Aby skonfigurować integrację z zewnętrznym dostawcą płatności, skonfiguruj profil zewnętrznej bramki płatności i podaj adres URL, na który Monetization powinno wysyłać żądania.

Można to zrobić w UI w sekcji System configuration Payment gateways albo przez utworzenie Payment Gateway Profile za pomocą REST API Monetization.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

Operacje na klientach

Operacje na klientach mają zastosowanie tylko wtedy, gdy zewnętrzny dostawca płatności obsługuje zarządzanie klientami. Jeśli dostawca płatności nie obsługuje zarządzania klientami, wtedy ids klienta można zastąpić dowolną wartością, np. znacznikiem czasu Unix żądania.

Utworzenie klienta (bez karty)

Tworzy klienta jako obiekt w usłudze dostawcy płatności.

Żądanie wysyłane przez Monetization:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Aktualizacja klienta

Aktualizuje obiekt klienta w usłudze dostawcy płatności.

Żądanie wysyłane przez Monetization:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 204 No Content

No Response Body

Odczyt klienta

Odczytuje obiekt klienta z usługi dostawcy płatności.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Oczekiwana odpowiedź:

HTPP Status: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Usunięcie klienta

Usuwa obiekt klienta z usługi dostawcy płatności.

Żądanie wysyłane przez Monetization:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Oczekiwana odpowiedź:

HTTP Status: 204 No Content

No Response Body

Operacje na kartach

Operacje na kartach dotyczą konfiguracji albo usuwania kart kredytowych i debetowych.

Setup (żądanie konfiguracji karty)

Uruchamia proces, w którym klient może podać dane karty kredytowej, które są tokenizowane i przechowywane w Monetization. Po otrzymaniu żądania dodania nowej karty kredytowej Monetization wyśle żądanie setup do Twojego komponentu integracyjnego.

Twój komponent integracyjny musi obsłużyć całą logikę związaną z usługami dostawcy płatności i zwrócić do Monetization adres URL przekierowania jako odpowiedź. Klient zostanie następnie przekierowany na podany adres URL, gdzie formularz hostowany przez dostawcę płatności zbierze i stokenizuje dane karty klienta.

Rysunek 5: Konfiguracja karty kredytowej

Żądanie wysyłane przez Monetization:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Usunięcie karty

Wysyła żądanie do Twojego komponentu integracyjnego, aby obsłużyć logikę usunięcia referencji karty kredytowej przez usługi dostawcy płatności, a następnie po powodzeniu usuwa referencję z Monetization.

Żądanie wysyłane przez Monetization:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 204 No Content

No Response Body

Operacje transakcyjne

Operacje transakcyjne dotyczą działań transakcyjnych wykonywanych na zapisanych tokenach metod płatności (kart kredytowych/debetowych). Obejmują one:

• Authorization
• Capture
• Charge
• Void
• Refund

Authorization

Authorization służy do autoryzacji (blokady) środków na metodzie płatności klienta. Autoryzacje można później wykonać jako Captured albo Voided. Poniższe żądanie jest wysyłane do Twojego komponentu integracyjnego, który powinien obsłużyć logikę usługi dostawcy płatności i zwrócić odpowiedź.

Żądanie wysyłane przez Monetization:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Capture

Capture oznacza pobranie autoryzowanych środków z wcześniejszego żądania Authorization. Kwota do pobrania może być równa autoryzowanej kwocie albo od niej niższa.

Wszelkie niepobrane autoryzowane środki zostaną zwolnione z powrotem klientowi przez usługę dostawcy płatności. Poniższe żądanie jest wysyłane do Twojego komponentu integracyjnego, który powinien obsłużyć logikę usługi dostawcy płatności i zwrócić odpowiedź.

Żądanie wysyłane przez Monetization:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Oczekiwana odpowiedź:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Charge

Charge autoryzuje i pobiera środki jako jedną natychmiastową transakcję. Poniższe żądanie jest wysyłane do Twojego komponentu integracyjnego, który powinien obsłużyć logikę usługi dostawcy płatności i zwrócić odpowiedź.

Żądanie wysyłane przez Monetization:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Oczekiwana odpowiedź:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Void

Operacja Void unieważnia transakcję Authorization, zwalniając autoryzowane środki. Poniższe żądanie jest wysyłane do Twojego komponentu integracyjnego, który powinien obsłużyć logikę usługi dostawcy płatności i zwrócić odpowiedź.

Żądanie wysyłane przez Monetization:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Oczekiwana odpowiedź:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Refund

Refund zwraca środki klientowi i odnosi się do wcześniejszej transakcji Charge albo Capture. Poniższe żądanie jest wysyłane do Twojego komponentu integracyjnego, który powinien obsłużyć logikę usługi dostawcy płatności i zwrócić odpowiedź.

Żądanie wysyłane przez Monetization:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Oczekiwana odpowiedź:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Obsługa błędów

Jeśli operacja w Twoim komponencie integracyjnym nie powiedzie się, zwróć dowolny status spoza zakresu 200-300 oraz komunikat błędu w treści odpowiedzi.