Stakar greiðslur (e. Payments)

Stakar greiðslur er hægt að framkvæma ef viðskiptavinur hefur verið skráður með gildan greiðslumáta. Einnig þarf að vera til staðar sjálfgefinn færsluhirðir fyrir Áskels aðganginn þinn. Hafðu samband við okkur til þess að ganga úr skugga um að það sé í lagi áður en þú byrjar.

Eins og flestar aðrar aðgerðir í vefþjónustu Áskels krefst þessi aðgerð leynilega API lykilsins (e. Private API key).

Stöður á greiðslum

Stakar greiðslur geta meðal annars haft eftirfarandi stöður.

Auðkenni stöðu

Lýsing

pending

Greiðsla hefur verið stofnuð og verður skuldfærð strax

settled

Skuldfærsla tókst

failed

Skuldfærsla tókst ekki og má reyna aftur allt að 4 sinnum

retrying

Skuldfærsla verður reynd aftur eins fljótt og auðið er

refunded

Greiðslan hefur verið endurgreidd að fullu

Ferlið

Öll köll í vefþjónustur má prófa í Swagger skjölun okkar sem finna má hér

  1. Greiðsla er stofnuð á viðskiptavin með upplýsingar um gjaldmiðil og upphæð. Valkvæmt er að láta fylgja með lýsingu og tilvísun úr þínu viðskiptakerfi.

  • python
API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}"
}

data = {
    "customer_reference": "customer-12345",
    "amount": "1",
    "currency": "ISK",
    "description": "My description", # Optional description
    "reference": "customer-12345", # Optional reference
}

response = requests.post("https://askell.is/api/payments/", data=data, headers=headers)

Svarið lítur svona út:

{
    "uuid": "a19ca264-5dd4-4897-bcb8-47d84844a2bc",
    "amount": "1.0000",
    "refunded_amount": "0.00",
    "currency": "ISK",
    "description": "My description",
    "reference": "customer-12345",
    "state": "pending",
    "created_at": "2021-10-15T10:02:25.663806Z",
    "updated_at": "2021-10-15T10:02:25.663824Z",
    "transactions": [
        {
        "external_reference": null,
        "data": {},
        "state": "initial",
        "uuid": "951913b0-3b99-4c6c-a58c-3b8e7c18b488",
        "fail_code": null,
        "refund_code": null,
        "cancel_code": null,
        "amount": "1.00",
        "refunded_amount": "0.00",
        "currency": "ISK"
        }
    ]
}

  1. Það þarf að fylgjast með stöðu greiðslunnar í gegnum vefkróka (e. webhooks). Þegar greiðslan breytir um stöðu sendum við viðburðinn payment.changed. Hér má líta dæmi um færslu sem hefur farið í gegn og má teljast greidd.

Sjá nánar undir Vefkrókar

{
    "event": "payment.changed",
    "sender": "admin",
    "data": {
        "uuid": "a19ca264-5dd4-4897-bcb8-47d84844a2bc",
        "amount": "1.0000",
        "refunded_amount": "0.00",
        "currency": "ISK",
        "description": "My description",
        "reference": "customer-12345",
        "state": "settled",
        "created_at": "2021-10-15T10:02:25.663806Z",
        "updated_at": "2021-10-15T10:02:25.663824Z",
        "transactions": [
            {
                "external_reference": "2286047",
                "data": {
                "id": "2286047",
                "receipt": {
                        "BuidAdOgilda": false,
                        "Bunkanumer": "B0003049",
                        "Dagsetning": "14.10.2021",
                        "F22_1til4": "1005",
                        "Faersluhirdir": "VALITOR, sími: 525 2000",
                        "Faerslunumer": "2286047",
                        "FaerslunumerUpphafleguFaerslu": null,
                        "Heimildarnumer": "277031",
                        "Hugbunadarnumer": "11101040000",
                        "Kortnumer": "****-****-****-2779",
                        "LinaC1": "060",
                        "LinaC2": "1509",
                        "LinaC3": "FÆRSLUNR: 128715286045",
                        "LinaC4": "HEIMILD:277031",
                        "LinaD1": "12",
                        "LinaD2": null,
                        "PinSkilabod": null,
                        "PosiID": "0225",
                        "Soluadilinumer": "S0053128",
                        "StadsetningNumer": "0001",
                        "TegundAdgerd": "SALA",
                        "TegundKorts": "Mastercard",
                        "TegundKortsKodi": "500",
                        "TerminalID": "11100126",
                        "Timi": "15:36",
                        "Upphaed": "1",
                        "UtstodNumer": "0001",
                        "VerslunHeimilisfang": null,
                        "VerslunNafn": "Fyrirtækjagreiðslur TEST",
                        "VerslunStadur": "Reykjavík",
                        "Vidskiptaskilabod": "VIÐSKIPTI ISK: 1"
                    },
                    "status": "settled"
                },
                "state": "settled",
                "uuid": "3c03b82a-951a-4331-b651-550de9da9004",
                "fail_code": null,
                "refund_code": null,
                "cancel_code": null,
                "amount": "1.00",
                "refunded_amount": "0.00",
                "currency": "ISK"
            },
        ]
    }
}

  1. Sú staða getur komið upp að færsla fari ekki í gegn af einhverjum ástæðum og fái því stöðuna failed. Í þeim tilfellum má reyna að skuldfæra sömu greiðslu aftur með retry vefþjónustunni. Það er hægt að reyna aftur allt að fjórum sinnum.

  • python
API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}"
}

uuid = "a19ca264-5dd4-4897-bcb8-47d84844a2bc"

response = requests.post(f"https://askell.is/api/payments/{uuid}/retry/", data={}, headers=headers)

Endurgreiðsla greiðslu

Stöku greiðslu sem hefur verið skuldfærð má endurgreiða að fullu eða að hluta með eftirfarandi slóð:

POST /api/payments/{uuid}/refund/

Beiðnin krefst leynilegs API lykils eða eldri token-auðkenningar. Beiðni með opnum API lykli er svarað með 403.

Meginmálið er valfrjálst. Með amount er sú upphæð endurgreidd, en án þess er allt endurgreitt sem eftir er að endurgreiða:

{
  "amount": "2500"
}

amount er í gjaldmiðli greiðslunnar og má vera tala eða strengur. Í gjaldmiðlum án aukastafa, eins og krónum, er það heil tala, en í öðrum gjaldmiðlum má það hafa í mesta lagi tvo aukastafi. Það þarf að vera hærra en núll og má ekki vera hærra en það sem eftir er að endurgreiða.

Aðeins er hægt að endurgreiða greiðslu í stöðunni settled. Greiðslu má endurgreiða í mörgum hlutum, upp að upphæð hennar. Greiðsla sem hefur verið endurgreidd að hluta er áfram í stöðunni settled, eins og færsla hennar, og refunded_amount á greiðslunni og færslunni sýnir hve mikið hefur verið endurgreitt. Hvort tveggja fer í stöðuna refunded þegar öll upphæðin hefur verið endurgreidd.

Hlutaendurgreiðslur fara eftir færsluhirði. Teya, Verifone og Straumur taka við þeim, en Valitor Pay aðeins frá og með deginum eftir skuldfærsluna, og aðeins að fullu fyrir skuldfærslur frá því fyrir 2022. Teya RPG endurgreiðir aðeins alla upphæðina. Færsluhirðir sem endurgreiðir aðeins alla upphæðina getur ekki endurgreitt afgang greiðslu sem hefur þegar verið endurgreidd að hluta.

  • python
API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}"
}

uuid = "a19ca264-5dd4-4897-bcb8-47d84844a2bc"

response = requests.post(
    f"https://askell.is/api/payments/{uuid}/refund/",
    json={"amount": "2500"},
    headers=headers,
)

Svarið er greiðslan. Hér hefur 2500 kr. af 7490 kr. greiðslu verið endurgreitt og hún er því áfram í stöðunni settled (stytt):

{
    "uuid": "a19ca264-5dd4-4897-bcb8-47d84844a2bc",
    "amount": "7490.0000",
    "refunded_amount": "2500.00",
    "currency": "ISK",
    "state": "settled",
    "transactions": [
        {
            "uuid": "3c03b82a-951a-4331-b651-550de9da9004",
            "state": "settled",
            "amount": "7490.00",
            "refunded_amount": "2500.00",
            "currency": "ISK"
        }
    ]
}

HTTP

Lýsing

Næsta skref

200

Endurgreiðslan tókst. Svarið er greiðslan, með refunded_amount á greiðslunni og færslum hennar. payment.changed atburður er sendur.

Engin frekari aðgerð er nauðsynleg.

202

Færsluhirðir tók við endurgreiðslunni en hefur ekki lokið henni, eða svar hans sagði ekki hvernig henni lauk (ekkert svar eða villa á netþjóni). Upphæð hennar er haldið eftir og verður ekki endurgreidd aftur á meðan. Svarið er greiðslan, sem er enn í stöðunni settled.

Ekki meðhöndla svarið sem villu og ekki senda beiðnina strax aftur. Sé beiðnin send aftur án amount meðan endurgreiðslur í bið halda eftir öllu sem eftir er að endurgreiða er færsluhirðir spurður aftur um þær undir sömu lyklum ef hann þekkir endurtekinn lykil (Teya, Verifone). Aðrir færsluhirðar eru ekki spurðir aftur, þar sem þeir gætu endurgreitt tvisvar, og beiðninni er svarað með 400 og refund_pending.

400

Endurgreiðslunni var hafnað eða færsluhirðir lauk henni ekki. Svarið er {"error": ..., "code": ...}, þar sem error er á ensku. code er einn af kóðunum hér að neðan.

Bregðast við code frekar en texta villunnar. Greiðslan er óbreytt.

403

Beiðnin var send með opnum API lykli.

Nota leynilegan API lykil.

code

Lýsing

transaction_not_refundable

Greiðslan er ekki í stöðunni settled, til dæmis vegna þess að hún hefur þegar verið endurgreidd að fullu, eða hún á enga uppgerða færslu.

refunds_not_supported

Færsluhirðir greiðslunnar styður ekki endurgreiðslur, eða ekki fyrir þessa færslu.

partial_refund_not_supported

Færsluhirðir endurgreiðir aðeins alla upphæðina, eða ekki enn hluta hennar (Valitor Pay frá og með deginum eftir skuldfærsluna).

invalid_refund_amount

amount er ekki tala, ekki hærra en núll eða með fleiri aukastafi en gjaldmiðillinn leyfir.

refund_amount_exceeds_refundable

amount er hærra en það sem eftir er að endurgreiða. Villuboðin segja hve mikið það er.

refund_failed

Færsluhirðir framkvæmdi ekki endurgreiðsluna. Villuboðin segja hvers vegna ef færsluhirðir gaf ástæðu.

refund_pending

Endurgreiðslur í bið halda eftir öllu sem eftir er og ekki er hægt að spyrja færsluhirðinn aftur um þær án þess að eiga á hættu að endurgreiða tvisvar. Athugaðu endurgreiðsluna hjá færsluhirðinum.

billing_run_charge

uuid er færsla sem V2 innheimtulota skuldfærði, ekki stök greiðsla. Svarið ber billing_run_id innheimtulotunnar, sem er endurgreidd með POST /api/v2/billing-runs/{id}/refund/. Sjá Endurgreiðsla innheimtulotu.

Endurgreiða má skuldfærslur eldri áskrifta á sama hátt, sjá Endurgreiðsla skuldfærslu áskriftar.