Plačilna integracija po meri

Ta dokument pojasnjuje, kako Monetization omogoča podporo za obdelavo plačil za ponudnike plačil tretjih oseb, ki niso podprti privzeto, ali za primere, ko se odločite za obdelavo plačilne logike zunaj Monetization prek svojih integracijskih procesov.

Kategorija:

Razvoj in integracija

Teme v tem dokumentu:

Obdelava plačil tretjih oseb v Monetization
Asinhrona obdelava plačil
- Izvoz faktur
  - Exporting job – datoteka CSV na SFTP
  - Obvestilo - metoda webhook
- Uvoz plačil
  - Uvoz datoteke CSV prek SFTP
  - Uvoz prek klica API
    - Avtentikacija
    - Zahtevek za uvoz plačila
Sinhrona obdelava plačil

Obdelava plačil tretjih oseb v Monetization

Obdelavo plačil tretjih oseb je mogoče doseči z dvema metodama: sinhrono in asinchrono. Sinhrona metoda zahteva takojšnje odzive vaše komponente za integracijo plačil, medtem ko asinhrona metoda združuje izvoz faktur iz Monetization in poznejši uvoz plačil.

Informacija:

Običajno vaš primer uporabe določa, katera metoda obdelave je optimalna.

Asinhrona obdelava plačil

Pri asinhroni obdelavi plačil izvozite fakture iz Monetization, plačila pa se v celoti obdelajo zunaj Monetization. Ko imate rezultate obdelave plačil, jih uvozite prek datotek CSV (ang. Comma-Separated Values) ali prek API (ang. Application Programming Interface) v Monetization.

Izvoz faktur

Fakture iz Monetization lahko izvozite tako, da konfigurirate mapper za izvoz faktur in načrtujete delo za izvoz (Exporting job), ki bo datoteke izvozilo na lokacijo SFTP (ang. Secure File Transfer Protocol), ali pa se naročite na obveščanje o ustvarjanju faktur prek Webhooka, ki bo ob vsaki ustvarjeni fakturi sprožil zahtevek na navedeni naslov URL (ang. Uniform Resource Locator).

Exporting job – datoteka CSV na SFTP

Za izvoz faktur v datoteke CSV je treba konfigurirati mapper za izvoz faktur (Invoice Export mapper), da se parametri fakture preslikajo v stolpce datoteke CSV. Uporabniški vmesnik Monetization omogoča takšno konfiguracijo pod Business configuration Export Invoice mappers.

Example of invoice export mapper configuration Slika 1: Primer konfiguracije mapperja za izvoz faktur

Izvozi faktur so načrtovani prek Exporting Jobs, ki so lahko enkratna opravila ali pa avtomatizirana za izvajanje v določenih obdobjih. Exporting Job bo izvoženo datoteko CSV shranil na ustrezno lokacijo SFTP storage/invoice/folder_name/file_name.csv.

Example of invoice export job Slika 2: Primer dela za izvoz faktur

Obvestilo - metoda webhook

Izvoz faktur prek webhookov vam omogoča, da fakture prejmete takoj po njihovem ustvarjanju. To dosežete s konfiguracijo pravila za obveščanje o fakturah (Invoice Notification Rule), ki bo vsako ustvarjeno fakturo poslalo kot zahtevek z vsebino JSON (ang. JavaScript Object Notation) na navedeni naslov URL, skupaj z vsemi predhodno konfiguriranimi možnostmi glave (header).

Example of invoice creation webhook configuration Slika 3: Primer konfiguracije webhooka za ustvarjanje faktur

Uvoz plačil

Plačilne transakcije lahko uvozite v Monetization tako, da konfigurirate mapper za uvoz plačil in naložite datoteke CSV s plačili na vhodno lokacijo SFTP ali pa uporabite REST (ang. Representational State Transfer) API v Monetization.

Uvoz datoteke CSV prek SFTP

Da bi Monetization lahko uvozil plačilne transakcije prek datotek CSV, mora biti konfiguriran mapper za uvoz plačil (Payment Import Mapper). Konfiguracija je mogoča prek uporabniškega vmesnika Monetization pod Business configuration Import Payment mappers.

Payment mapper omogoča preslikavo stolpcev CSV v parametre plačilnih transakcij in definicijo predpone datoteke, ki mora biti prisotna v naloženih datotekah.

Datoteke se naložijo na strežnik SFTP v mapo edl/input in bodo premaknjene v mape edl/processed, edl/successful, edl/error ali edl/rejected, odvisno od rezultatov obdelave.

Example of payment import mapper configuration Slika 4: Primer konfiguracije mapperja za uvoz plačil

Uvoz prek klica API

Za uvoz plačilne transakcije prek API-ja v Monetization pošljite zahtevek JSON s podrobnostmi o transakciji na REST API v Monetization.

Opomba:

Uporabnik se mora najprej avtenticirati za komunikacijo z API-jem v Monetization.

Avtentikacija

API v Monetization uporablja avtentikacijo z žetonom Bearer :

Izvedite zahtevek za avtentikacijo z uporabniškim imenom, geslom in specifično kodo spletnega mesta (site code).
Pridobite žeton (token) iz odgovora.
V naslednjih zahtevkih nastavite glavo Authorization na Bearer <žeton>.
Žeton poteče po 5 minutah.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

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

Zahtevek za uvoz plačila

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"
}

Sinhrona obdelava plačil

Sinhrona obdelava plačil zahteva sinhrono komunikacijo med Monetization in vašo komponento za integracijo plačil. Ta metoda obdelave omogoča avtorizacije kreditnih/debetnih kartic in takojšnja plačila.

V Monetization konfigurirate, kam naj se pošiljajo zahtevki, povezani z obdelavo plačil, Monetization pa ima vnaprej določene odgovore, ki jih pričakuje v zameno. Ta metoda obdelave omogoča shranjevanje referenc plačilnih sredstev pri strankah in podpira avtomatizirane procese zbiranja plačil.

Za Monetization je postopek integracije praktično enak kot privzeta integracija z obstoječim ponudnikom (Stripe, Braintree itd.). Komunikacija pa poteka prek komponente, ki ste jo razvili vi in ki deluje kot prehod (gateway) do vašega lokalnega ponudnika plačil.

Ključne operacije za podporo sinhrone obdelave plačil:

Setup Intent
Authorize
Capture
Charge

Nastavitev ponudnika plačil tretjih oseb

Za nastavitev integracije s ponudnikom plačil tretjih oseb konfigurirajte profil plačilnega prehoda tretjih oseb (third-party payment gateway profile) in navedite naslov URL, kamor naj Monetization pošilja zahtevke.

To lahko storite prek uporabniškega vmesnika pod System configuration Payment gateways ali z ustvarjanjem profila plačilnega prehoda prek REST API-ja v 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"
    }
}

Operacije s strankami

Operacije s strankami veljajo le v primerih, ko ponudnik plačil tretjih oseb podpira upravljanje strank. Če ponudnik plačil ne podpira upravljanja strank, se lahko ID-ji strank nadomestijo s katero koli vrednostjo (npr. časovni žig Unix ob zahtevku).

Ustvari stranko (brez kartice)

Ustvari stranko kot objekt v storitvi ponudnika plačil.

Zahtevek, ki ga pošlje 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 "
        }
    }
}

Pričakovan odgovor:

Status HTTP (ang. Hypertext Transfer Protocol): 201 Created

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

Posodobi stranko

Posodobi objekt stranke v storitvi ponudnika plačil.

Zahtevek, ki ga pošlje 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 "
        }
    }
}

Pričakovan odgovor:

Status HTTP: 204 No Content

Brez vsebine odgovora

Preberi podatke o stranki

Prebere objekt stranke iz storitve ponudnika plačil.

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

Pričakovan odgovor:

Status HTTP: 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"
            }
        ]
    }
}

Izbriši stranko

Izbriše objekt stranke iz storitve ponudnika plačil.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 204 No Content

Brez vsebine odgovora

Operacije s karticami

Operacije s karticami se nanašajo na nastavljanje ali odstranjevanje kreditnih in debetnih kartic.

Nastavitev (zahtevek za nastavitev kartice)

Sproži postopek, v katerem lahko stranka navede podatke o kreditni kartici, ki se tokenizirajo in shranijo v Monetization. Ob zahtevku za dodajanje nove kreditne kartice bo Monetization poslal zahtevek za nastavitev vaši integracijski komponenti.

Vaša integracijska komponenta mora obdelati vso logiko, povezano s storitvami ponudnika plačil, in v odgovor vrniti URL za preusmeritev v Monetization. Stranka bo nato preusmerjena na navedeni URL, kjer bo obrazec, ki ga gosti vaš ponudnik plačil, zbral in tokeniziral podatke o strankini kartici.

Credit card setup Slika 5: Nastavitev kreditne kartice

Zahtevek, ki ga pošlje 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"
        }
    }
}

Pričakovan odgovor:

Status HTTP: 201 Created

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

Izbriši kartico

Pošlje zahtevek vaši integracijski komponenti za obdelavo logike odstranjevanja reference kreditne kartice prek storitev ponudnika plačil, nato pa po uspehu odstrani referenco iz Monetization.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 204 No Content

Brez vsebine odgovora

Transakcijske operacije

Transakcijske operacije se nanašajo na transakcijska dejanja, izvedena na shranjenih žetonih plačilnih sredstev (kreditna/debetna kartica). Ta dejanja vključujejo:

Avtorizacija
Zajem
Obremenitev
Preklic
Vračilo

Avtorizacija

Avtorizacija se uporablja za avtorizacijo (zaklepanje) sredstev na strankinem plačilnem sredstvu. Avtorizacije se lahko pozneje zajamejo (Capture) ali prekličejo (Void). Spodnji zahtevek se pošlje vaši integracijski komponenti, ki mora obdelati logiko storitve ponudnika plačil in vrniti odgovor.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 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"
}

Zajem

Zajem (Capture) se nanaša na zbiranje avtoriziranih sredstev iz predhodnega zahtevka za avtorizacijo. Znesek za zbiranje je lahko enak ali nižji od avtoriziranega zneska.

Vsa neizterjana avtorizirana sredstva bo storitev ponudnika plačil sprostila nazaj stranki. Spodnji zahtevek se pošlje vaši integracijski komponenti, ki mora obdelati logiko storitve ponudnika plačil in vrniti odgovor.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 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"
}

Obremenitev

Obremenitev (Charge) avtorizira in zajame sredstva kot enotno takojšnjo transakcijo. Spodnji zahtevek se pošlje vaši integracijski komponenti, ki mora obdelati logiko storitve ponudnika plačil in vrniti odgovor.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 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"
}

Preklic

Operacija preklica (Void) prekliče transakcijo avtorizacije in sprosti avtorizirana sredstva. Spodnji zahtevek se pošlje vaši integracijski komponenti, ki mora obdelati logiko storitve ponudnika plačil in vrniti odgovor.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 202 Accepted

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

Vračilo

Vračilo (Refund) vrne sredstva stranki in se nanaša na predhodno transakcijo obremenitve (Charge) ali zajema (Capture). Spodnji zahtevek se pošlje vaši integracijski komponenti, ki mora obdelati logiko storitve ponudnika plačil in vrniti odgovor.

Zahtevek, ki ga pošlje Monetization:

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

Pričakovan odgovor:

Status HTTP: 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"
}

Odpravljanje napak

V primeru, da operacija na vaši integracijski komponenti ni uspešna, vrnite kateri koli status zunaj območja 200-300 in sporočilo o napaki v telesu odgovora.

Prejšnja

Naprave