Skip to content

Metody pro platbu Skip Pay

Jump to bottom
Daniel Marek edited this page Dec 2, 2024 · 7 revisions

Stručný přehled

ℹ️ Z mallpay se od 6.10.2022 stalo Skip Pay. Kromě názvu zůstává vše beze změny. V eAPI části zde na wiki a v kódu API je však stále použito jako mallpay (názvy operací a parametry). Metody pro platbu mallpay (resp. Skip Pay) jsou i nadále plně funkční.

Platební metoda Skip Pay používá API metody mallpay/init pro založení platby na bráně a mallpay/logistics pro předání stavu doručování zásilky na platební bránu. Zrušení platby lze provést pomocí metody mallpay/cancel, částečnou nebo úplnou vratku částky transakce lze provést pomocí metody mallpay/refund. Pro zjištění stavu platby slouží obecná API funkce payment/status.

Zpracování Skip Pay platby probíhá na platební bráně Skip Pay, tj. zákazník je z e-shopu přesměrován na Skip Pay. Parametry pro přesměrování jsou výsledkem volání mallpay/init. Pokud Skip Pay zákazníka již zná a ví, že pro konkrétní nákup není platba Skip Pay možná, bude volání mallpay/init zamítnuto, zákazník není obtěžován přesměrováním na Skip Pay bránu a obchodník může nabídnout alternativní způsoby platby.

Metoda Popis
mallpay/init Založení Odložené platby na platební bráně pro mallpay@shop.
mallpay/logistics Pomocí této operace obchodník předá údaje o doručení nebo odeslání zboží zákazníkovi, případně údaje o zrušených položkách objednávky.
mallpay/cancel Pomocí této operace může obchodník zrušit Odloženou platbu.
mallpay/refund Provedení vratky u Skip Pay platby.

⚠️ Věnujte, prosím, pozornost zejména tomu, že metoda Skip Pay (na rozdíl od ostatních metod na platební bráně) používá téměř ve všech voláních identifikaci položek nákupu.

  • Při zakládání platby (mallpay/init) je nutné identifikovat položky a zákazníka.
  • Při odesílání/doručování zboží (mallpay/logistics) je nutné identifikovat položky, kterých se odeslání, resp. doručení týká.
  • Stejně tak při vratce (mallpay/refund) je nutné na bránu odeslat seznam položek, ke kterým se finanční vratka váže.
  • Pouze funkce mallpay/cancel nevyžaduje identifikaci položek, protože tato funkce ruší celou objednávku.

Datové struktury  

V rámci volání Skip Pay metod se používají následující základní datové struktury:

Z těchto částí se pro operaci mallpay/init seskládají složitější datové struktury:

Kromě toho se v rámci operací mallpay/logistics a mallpay/refund odkazuje na položky objednávky pomocí datových struktur:

V následující části je uveden přehled výše zmíněných základních datových struktur a jejich parametrů včetně příkladu plnění:

Tučně uvedené parametry jsou pro volání povinné.

Datová struktura address (Adresa)  

Položka Typ Popis
name String Jméno, max. délka 40 znaků
country String Stát, max. délka 20 znaků
city String Město, max. délka 50 znaků
streetAddress String Ulice (část města), max. délka 100 znaků
streetNumber String Číslo popisné, max. délka 25 znaků
zip String Poštovní směrovací číslo, max. délka 10 znaků
addressType String Typ adresy; adresy se vyplňují u objednávky, povolené hodnoty:
DELIVERY (adresa pro doručení)
BILLING (fakturační adresa)

Příklad vyplnění fakturační adresy

{
  "addressType":"BILLING",
  "streetAddress":"Radlická 333",
  "city":"Praha 5",
  "zip":"15000",
  "country":"CZ"
}

Datová struktura price (Částka)  

Položka Typ Popis
amount Number Částka v setinách základní měny (např. 12590 odpovídá 125,90 Kč)
currency String Měna dle formátu ISO 4217; pro Skip Pay platební metodu povolena pouze CZK

Příklad vyplnění částky 125,90 Kč

{
  "amount":12590,
  "currency":"CZK"
}

Datová struktura vat (Daňová sazba)  

Položka Typ Popis
amount Number Částka daně v setinách základní měny (např. 5000 odpovídá 50,00 Kč)
currency String Měna dle formátu ISO 4217; pro Skip Pay platební metodu povolena pouze CZK
vatRate Number Daňová sazba jako přirozené číslo (hodnota 15 odpovídá 15% sazbě)

Příklad vyplnění 15% daňové sazby 50,- Kč

{
  "amount":5000,
  "currency":"CZK",
  "vatRate":15
}

Datová struktura order item (Položka objednávky)  

Položka Typ Popis
code String Kód položky (interní pro e-shop). Slouží pro lepší identifikaci položky v případě provádění následných operací (mallpay/logistics, mallpay/refund). Platební brána ani Skip Pay tento kód nevaliduje, max. délka 50 znaků
ean String Kód EAN, max. délka 15 znaků
name String Název položky, max. délka 200 znaků
type String Typ položky. Povolené hodnoty:
PHYSICAL pro fyzické zboží, které zákazníkovi obchodník doručuje nebo si jej zákazník vyzvedává;
DISCOUNT použijte, pokud uvádíte slevu jako samostatnou položku na faktuře;
DIGITAL použijte pro digitální položky, například elektronické licence nebo média;
GIFT_CARD použijte při prodeji dárkových karet;
STORE_CREDIT použijte, pokud zákazníkovi prodáváte nebo dáváte dárkovou kartu použitelnou pouze ve vašem obchodě;
SALES_TAX použijte, pokud uvádíte daně (např. DPH) jako samostatnou položku na faktuře (v českém prostředí se typicky nepoužije);
SHIPPING_FEE použijte pro dopravné;
INSURANCE použijte, pokud uvádíte pojištění jako samostatnou položku na faktuře;
FEE použijte pro ostatní poplatky.
quantity Number Množství. Pokud je prázdné, odpovídá hodnotě 1.
variant String Varianta produktu (například barva, velikost balení, velikost paměti apod.) - pro iPhone 7 se jedná o "64 GB Space gray" (zákazníkovi se v systému Skip Pay nikde nezobrazuje), max. délka 50 znaků
description String Krátký popisek produktu, max. délka 100 znaků
producer String Výrobce, max. délka 50 znaků
categories Array Seznam kategorií, do kterých lze položku zařadit (může odpovídat kategoriím v e-shopu, zákazníkovi se v systému Skip Pay nikde nezobrazuje).
unitPrice Object Jednotková cena jednoho kusu položky, viz datová struktura price, uvedená jako cena včetně daně (DPH). Daň se vyčísluje v samostatném parametru unitVat.
unitVat Object Jednotková daň za jeden kus položky, viz datová struktura vat
totalPrice Object Celková cena položky, viz datová struktura price, uvedená jako celková cena za nakupovaný počet kusů položky včetně daně (DPH). Daň se vyčísluje v samostatném parametru totalVat.
totalVat Object Celková daň za nakupovaný počet kusů položky, viz datová struktura vat.
productUrl String URL odpovídající popisu položky v e-shopu, max. délka 250 znaků

Příklad položky objednávky

{
  "code":"X123",
  "name":"iPhone XS",
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": {
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }
}

V následující části je uveden přehled výše zmíněných složitějších datových struktur a jejich parametrů včetně příkladu plnění:

Datová struktura customer (Údaje o zákazníkovi)  

Položka Typ Popis
firstName String Křestní jméno zákazníka. Povinné v případě, že fullName je prázdné, max. délka 40 znaků.
lastName String Příjmení zákazníka. Povinné v případě, že fullName je prázdné, max. délka 40 znaků.
fullName String Celé jméno zákazníka (zadávané na rozdíl od firstName a lastName jako jedna položka) včetně akademických titulů. Povinné pouze v případě, že firstName a lastName jsou prázdné, max. délka 100 znaků.
titleBefore String Akademický titul před jménem, max. délka 20 znaků.
titleAfter String Akademický titul za jménem, max. délka 20 znaků.
email String E-mailová adresa zákazníka, max. délka 50 znaků.
phone String Telefonní číslo včetně mezinárodní předvolby (včetně úvodního znaku +), max. délka 16 znaků.
tin String IČO zákazníka, max. délka 10 znaků.
vatin String DIČ zákazníka, max. délka 12 znaků.

Příklad plnění customer dat (vyplnění oddělených položek pro jméno a příjmení):

{
  "firstName":"Adam",
  "lastName":"Beran",
  "email": "[email protected]",
  "phone": "+420800300300"
}

Příklad plnění customer dat (vyplnění položky fullName pro jméno a příjmení):

{
  "fullName":"Adam Beran",
  "email": "[email protected]",
  "phone": "+420800300300"
}

Datová struktura order (Údaje o objednávce)  

Položka Typ Popis
totalPrice Object Celková cena včetně DPH, tuto částku obdrží obchodník na účet, popis viz datová struktura Price.
totalVat Array Rozpad celkové ceny na jednu nebo více daňových sazeb, popis viz datová struktura vat.
addresses Array Seznam adres. Od verze 1.9 je fakturační adresa (typ BILLING) i doručovací adresa (typ DELIVERY) nepovinná. Doporučujeme vyplňovat fakturační adresu a zasílat navíc doručovací adresu (pokud je odlišná od fakturační).
deliveryType String Typ doručení. V případě hodnoty DELIVERY_CARRIER je možné doručení upřesnit v parametru carrierId nebo carrierCustom.
Povolené hodnoty:
DELIVERY_CARRIER (zaslání dopravcem na adresu specifikovanou zákazníkem)
PERSONAL_BRANCH (osobní vyzvednutí na provozovně e-shopu)
PERSONAL_PARTNER (osobní vyzvednutí na provozovně distribučního partnera e-shopu)
ONLINE (elektronické doručení - např. pro elektronické licence, dárkové karty apod.)
carrierId String Identifikace dopravce, povolené hodnoty:
CZ_POST_HAND
CZ_POST_OFFICE
CZ_POST_OTHER
PPL
DPD
GEIS
IN_TIME
TOP_TRANS
GEBRUDER_WEISS
LOCAL_COURIER
TNT
GLS
HDS_COMFORT
HDS_STANDARD
MALL_DEPOSIT.
carrierCustom String Upřesnění dopravce v případě, že jej nelze specifikovat pomocí carrierId.
items Array Položky objednávky, popis viz datová struktura order item.

Počet položek objednávky není neomezený. Platí, že celková délka struktury order serializovaná jako JSON nesmí překročit 4000 znaků.

Příklad vyplnění objednávky (jedna položka, uvedena fakturační adresa):

{
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }],
  "addresses": [{
    "addressType":"BILLING",
    "streetAddress":"Radlická 333",
    "city":"Praha 5",
    "zip":"15000",
    "country":"CZ"
  }],
  "items": [{
    "code":"X123",
    "name":"iPhone XS",
    "totalPrice": {
      "amount":1452000,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":252000,
      "currency":"CZK",
      "vatRate":21
    }
  }]
}

Příklad vyplnění objednávky (dvě položky, každá v jiné daňové sazbě, bez fakturační nebo dodací adresy):

{
  "totalPrice": {
    "amount":3047400,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":522900,
    "currency":"CZK",
    "vatRate":21
  },
  {
    "amount":4500,
    "currency":"CZK",
    "vatRate":15
  }],
  "items": [{
    "code":"A456",
    "name":"Canon EOS 80D",
    "totalPrice": {
      "amount":3012900,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":522900,
      "currency":"CZK",
      "vatRate":21
    }
  },
  {
    "code":"Y987",
    "name":"Fotografická příručka",
    "totalPrice": {
      "amount":34500,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":4500,
      "currency":"CZK",
      "vatRate":15
    }
  }]
}

V následující části je uveden přehled výše zmíněných datových struktur pro mallpay/logistics a mallpay/refund a jejich parametrů včetně příkladu plnění:

Datová struktura item reference (Reference na položku objednávky)  

Tato datová struktura se použije pro předání reference na doručené, odeslané nebo zrušené položky objednávky v rámci volání mallpay/logistics anebo pro předání reference na vrácené položky objednávky v rámci volání mallpay/refund. Pozor! Do datové struktury reference na položku objednávky je nutné uvádět stejnou hodnotu položky code jako při zakládání objednávky v datové struktuře OrderItem ve volání mallpay/init. V případě vyplnění položky name (tato položka je v rámci volání mallpay/logistics a mallpay/refund nepovinná), musí být předávaná hodnota také shodná s původní hodnotou předávanou při založení objednávky. Pokud nebude stejná, neprojdou v systému Skip Pay validace.

Položka Typ Popis
code String Kód položky (interní pro e-shop). Slouží pro identifikaci položky objednávky, max. délka 50 znaků.
ean String Kód EAN, max. délka 15 znaků.
name String Název položky, max. délka 200 znaků.
type String Typ položky, povolené hodnoty:
PHYSICAL
DISCOUNT
SHIPPING_FEE
SALES_TAX
DIGITAL
GIFT_CARD
STORE_CREDIT
FEE
INSURANCE.
quantity Number Množství. Pokud je prázdné, odpovídá hodnotě 1.

Příklad vyplnění reference na položku objednávky:

{
  "code":"X123",
  "name":"iPhone XS"
}

Datová struktura order reference (Reference objednávky)  

Tato datová struktura se použije v rámci volání mallpay/logistics pro předání údajů o celkové ceně doručeného nebo odeslaného zboží včetně rozpadu na daňové sazby a doručených nebo odeslaných položek objednávky. Pomocí této struktury může obchodník dále předat v rámci mallpay/logistics také údaje o zrušené části objednávky.

Položka Typ Popis
totalPrice Object Celková cena včetně DPH, popis viz datová struktura price.
totalVat Array Daňová sazba, popis viz datová struktura vat.
items Array Pole objektů typu "reference na položku objednávky", kterými obchodník odkazuje na položky objednávky, popis viz datová struktura item reference.

Příklad vyplnění reference objednávky:

{
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }],
  "items": [{
    "code":"X123",
    "name":"iPhone XS"
  }]
}

Metoda mallpay/init  

POST https://api.platebnibrana.csob.cz/api/v1.9/mallpay/init

Operace založí Odloženou platbu (mallpay@shop). Do systému Skip Pay předá platební brána údaje o zákazníkovi a objednávce. Systém Skip Pay provede prvotní ověření zákazníka (tzv. pre-check), a pokud je platba pro daného zákazníka možná, je výsledkem této operace zejména URL pro přesměrování do Skip Pay.

Položka Typ Popis
merchantId String ID obchodníka přiřazené platební bránou.
orderNo String Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka 10 číslic.
customer Object Údaje o zákazníkovi, které budou použity pro vyřízení Odložené platby u Skip Pay. Popis parametrů viz datová struktura customer.
order Object Údaje o objednávce, které budou použity pro vyřízení Odložené platby u Skip Pay. Popis parametrů viz datová struktura order.
agreeTC Boolean Souhlas zákazníka s obchodními podmínkami Skip Pay. Povolené hodnoty: true, false. Podmínky není nutné na e-shopu zobrazovat - v takovém případě pošlete prosím false a odsouhlasení podmínek si zajistí systém Skip Pay. Pokud budete podmínky zobrazovat, není nutný souhlas ve smyslu zaškrtnutí checkboxu. Jedná se o informovaný souhlas, který stačí zobrazit.
dttm String Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
clientIp String IP adresa zákazníka (jeho prohlížeče) přistupujícího na e-shop obchodníka, formát ipv4 nebo ipv6.
returnUrl String URL adresa, na kterou bude klient přesměrován zpět do e-shopu v případě zrušení platby zákazníkem. Maximální délka 300 znaků. Při přesměrování zpět na e-shop se předává stejná sada parametrů jako v případě návratu z platební brány při platbě kartou.
returnMethod String Metoda návratu na URL adresu e-shopu. Povolené hodnoty POST, GET. Doporučená metoda je POST.
merchantData String Libovolná pomocná data, která předává obchodník na bránu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků. V případě obchodního modelu "Marketplace" musí obchodník identifikovat svého retailera pomocí IČO. Tento identifikátor je třeba plnit do hranatých závorek [] a může být umístěn libovolně v rámci položky merchantData. V případě, že se nákupu účastní vícero retailerů, hodnoty IČO se oddělují čárkou - např. [12345678,87654321].
ttlSec Number Nastavení životnosti platby, v sekundách, min. povolená hodnota 600, max. povolená hodnota 43200 (10 min - 12 hodin). Životnost platby je počítána od okamžiku provolání mallpay/init.
signature String Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "orderNo":"51966",
  "customer": {
    "firstName": "Adam",
    "lastName": "Malý",
    "email": "[email protected]",
    "phone": "+420800300300"
  },
  "order": {
    "totalPrice": {
    	"amount":1210000,
    	"currency":"CZK"
    },
    "totalVat": [{
    	"amount":210000,
    	"currency":"CZK",
    	"vatRate":21
    }],
    "addresses": [
    	{
    	"addressType":"BILLING",
    	"streetAddress":"Radlická 333",
    	"city":"Praha 5",
    	"zip":"15000",
    	"country":"CZ"
    	}
    ],
    "items": [
    	{
    	"code":"ABC123",
    	"name":"iPhone 8S",
	    "totalPrice": {
	    	"amount":1210000,
	    	"currency":"CZK"
	    },
	    "totalVat": {
	    	"amount":210000,
	    	"currency":"CZK",
	    	"vatRate":21
	    }
      }
    ]
  },
  "agreeTC":true,
  "dttm":"20220125131559",
  "clientIp":"192.0.2.2",
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "merchantData":"some-base64-encoded-merchant-data",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty  

Položka Typ Popis
payId String Jednoznačné ID platby (přidělené platební bránou v operaci mallpay/init, obsahuje 15-znakový řetězec).
dttm String Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode Number Výsledek operace, viz výčet.
resultMessage String Textový popis výsledku operace.
paymentStatus Number Stav platby, viz životní cyklus transakce.
mallpayUrl String URL pro přesměrování zákazníka na Skip Pay, vyplněno v případě, že resultCode je 0 .
signature String Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro mallpay/init -- úspěšně založená platby:

{
  "payId":"be36dc0c6229@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "mallpayUrl": "https://www.mallpay.cz/...",
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro mallpay/init - zamítnutá platba (nevalidní vstupní parametry):

{
  "payId":"be36dc0c6229@HA",
  "dttm":"20220125131601",
  "resultCode": 110,
  "resultMessage":"Missing 'customer' parameter",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Metoda mallpay/logistics  

PUT https://api.platebnibrana.csob.cz/api/v1.9/mallpay/logistics

Pomocí této operace obchodník předá údaje o doručení nebo odeslání (dle smluvního nastavení se Skip Pay) jednotlivých položek objednávky zákazníkovi. Pokud obchodník neodeslal / nedodal všechny původní položky objednávky (předané na platební bránu v operaci mallpay/init, je nutné tyto položky uvést ve zrušených položkách.

Položka Typ Popis
merchantId String ID obchodníka přiřazené platební bránou.
payId String PayID platby.
event String Způsob předání zboží, povolené hodnoty: delivered, sent.
date String Datum doručení nebo odeslání zboží, formát YYYYMMDD.
fulfilled Object Údaje o doručených/odeslaných položkách objednávky včetně celkové částky a rozpadu daňových sazeb, popis viz datová struktura order reference.
cancelled Object Údaje o zrušených položkách objednávky včetně celkové částky a rozpadu daňových sazeb, popis viz datová struktura order reference, vyplněno v případě zrušených položek objednávky u Skip Pay.
deliveryTrackingNumber String Sledovací číslo u dopravce.
dttm String Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
signature String Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "payId":"be36dc0c6229@HA",
  "event":"delivered",
  "date":"20191020",
  "fulfilled": {
    "totalPrice": { "amount":24200, "currency":"CZK" },
    "totalVat": [ { "amount":4200, "currency":"CZK", "vatRate":21 } ],
    "items":[
      { 
        "code":"AX1255c",
        "name":"Obal na iPhone XS",
        "type":"PHYSICAL",
        "quantity":1
      }
    ]
  },
  "dttm":"20220125131610",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty  

Položka Typ Popis
payId String Jednoznačné ID platby (přidělené platební bránou v operaci mallpay/init, obsahuje 15-znakový řetězec).
dttm String Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode Number Výsledek operace, viz výčet.
resultMessage String Textový popis výsledku operace.
paymentStatus Number Stav platby, viz životní cyklus transakce.
statusDetail String Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, možné hodnoty viz číselník.
signature String Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro mallpay/logistics:

{
  "payId":"be36dc0c6229@HA",
  "dttm":"20220125131612",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "signature":"base64-encoded-response-signature"
 }

Metoda mallpay/cancel  

PUT https://api.platebnibrana.csob.cz/api/v1.9/mallpay/cancel

Pomocí této operace provede obchodník zrušení Odložené platby, ve vstupních parametrech uvádí důvod zrušení. Ruší se celá objednávka, proto nejsou v tomto volání předávány reference na položky objednávky.

Položka Typ Popis
merchantId String ID obchodníka přiřazené platební bránou.
payId String PayID platby.
reason String Důvod zrušení platby obchodníkem, povolené hodnoty:
aborted pro zrušenou objednávku zákazníkem;
other_payment pro situaci, kdy se zákazník rozhodl změnit způsob platby;
undeliverable pro případ, že objednávka byla zrušena z důvodu nedoručitelnosti (např. nevyzvednutý balík);
unavailable pro případ zrušení objednávky z důvodu nedostupnosti zboží;
abandoned pro případ nedokončení objednávky zákazníkem (pouze pokud e-shop vyžaduje další kroky k dokončení objednávky po potvrzení Skip Pay platby);
changed pro případ, že zákazník změnil objednávku a ta z toho důvodu zanikla;
unprocessed pro ostatní důvody na straně e-shopu, které vedly k nemožnosti dokončit/naplnit objednávku.
dttm String Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
signature String Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "payId":"be36dc0c6229@HA",
  "reason":"aborted",
  "dttm":"20220125131620",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty  

Položka Typ Popis
payId String Jednoznačné ID platby (přidělené platební bránou v operaci mallpay/init, obsahuje 15-znakový řetězec).
dttm String Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode Number Výsledek operace, viz výčet.
resultMessage String Textový popis výsledku operace.
paymentStatus Number Stav platby, viz životní cyklus transakce.
statusDetail String Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, možné hodnoty viz číselník.
signature String Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro mallpay/cancel:

{
  "payId":"be36dc0c6229@HA",
  "dttm":"20220125131622",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 3,
  "signature":"base64-encoded-response-signature"
 }

Metoda mallpay/refund  

PUT https://api.platebnibrana.csob.cz/api/v1.9/mallpay/refund

Voláním operace je zažádáno o návrat prostředků nazpět plátci. Aplikuje se na již zaúčtované platby. Lze provést i tzv. částečnou vratku vyplněním nepovinného parametru amount. Částečnou vratku lze provádět opakovaně, přičemž platí, že částka v parametru amount musí být menší než rozdíl původní autorizované částky a sumy doposud provedených (schválených) částečných vratek.

Položka Typ Popis
merchantId String ID obchodníka přiřazené platební bránou.
payId String Jednoznačné ID platby (přidělené platební bránou v operaci mallpay/init).
dttm String Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
amount Number Požadovaná částka pro částečnou vratku v setinách základní měny; pro úplnou vratku nepovinné.
refundedItems Array Údaje o vrácených položkách objednávky, popis viz datová struktura item reference; povinné pro částečnou i úplnou vratku.
signature String Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "payId":"be36dc0c6229@HA",
  "refundedItems":[
    { 
      "code":"AX1255c",
      "name":"Obal na iPhone XS"
    }],
  "dttm":"20220125131710",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty  

Položka Typ Popis
payId String Jednoznačné ID platby (přidělené platební bránou v operaci mallpay/init, obsahuje 15-znakový řetězec).
dttm String Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode Number Výsledek operace, viz výčet.
resultMessage String Textový popis výsledku operace.
paymentStatus Number Stav platby, viz životní cyklus transakce.
statusDetail String Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, možné hodnoty viz číselník.
signature String Podpis odpovědi, kódováno v BASE64.

Zpracování u této operace je asynchronní, parametr paymentStatus v návratových hodnotách proto obsahuje aktuální stav platebního požadavku (Platba zúčtována), stav platebního požadavku je možné sledovat přes payment/status.

Příklad návratových hodnot pro mallpay/refund:

{
  "payId":"be36dc0c6229@HA",
  "dttm":"20220125131713",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "signature":"base64-encoded-response-signature"
 }

Mikrostavy platební metody Skip Pay  

Platební metoda Skip Pay podporuje mikrostavy pouze ve stavech 3, 6 a 10.

Mikrostavy Skip Pay | stav 3 "platba zrušena"

Pro platby zrušené obchodníkem (poté, co zavolal operaci mallpay/cancel) rozlišuje platební brána následující mikrostavy:

statusDetail popis
canceled.aborted#mallpay zrušeno zákazníkem
canceled.other_payment#mallpay změna způsobu platby a zánik objednávky
canceled.undeliverable#mallpay nedoručitelné
canceled.unavailable#mallpay zboží nedostupné
canceled.abandoned#mallpay objednávka opuštěna zákazníkem
canceled.changed#mallpay objednávka byla změněna a zanikla
canceled.unprocessed#mallpay jinak nezpracovaná objednávka

Mikrostavy Skip Pay | stav 6 "platba zamítnuta"

Pro zamítnuté platby rozlišuje platební brána následující mikrostavy:

statusDetail popis
declined.abandoned#mallpay opuštěno v žádosti – timeout payId
declined.rejected#mallpay obecné zamítnutí – zamítnutí žádosti ve Skip Pay
declined.shipping_timeout#mallpay obchodník nepředal logistický stav v limitu

Mikrostavy Skip Pay | stav 10 "platba vrácena"

Pro platby, u nichž došlo k vratce, rozlišuje platební brána následující mikrostavy:

statusDetail popis
refunded.full#mallpay provedena plná vratka (jedna nebo více částečných)
refunded.partial#mallpay provedena částečná vratka (jedna nebo více částečných, přičemž nebyla dosažena suma původní transakce)

💳 Platební brána

  1. Průběh platby
  2. API integrace a zabezpečení
  3. Návod na přechod do produkčního prostředí
  4. Testovací karty
  5. API Sunset

💰 Platby

  1. Ověření karetních plateb
  2. Platba na bráně
  3. OneClick platba
  4. Platba na míru
  5. Apple Pay
  6. Google Pay
  7. Zaúčtování platby kartou na menší částku
  8. Platební tlačítko ČSOB
  9. Platba Skip Pay

🔬 eAPI 1.9

  1. Volání rozhraní eAPI
  2. Podpis požadavku a ověření podpisu odpovědi
  3. Přehled eAPI metod
  4. Základní metody
  5. Metody pro OneClick platbu
  6. Metody pro Apple Pay
  7. Metody pro Google Pay
  8. Metody pro platební tlačítko
  9. Metody pro platbu Skip Pay
  10. Dodatečná data o nákupu

📐 Návody a podklady

  1. Loga a prezentace platebních metod
  2. Logo obchodníka
  3. Barevné schéma

📟 API rozšíření

  1. Koncept API rozšíření
  2. Detailní datum a čas zpracování a vypořádání transakce
  3. Data o kartě pro OneClick platbu
  4. Data o kartě pro platbu na bráně
  5. Tokenizace
  6. Ověřovací kód na výpis

🔧 Časté dotazy (FAQ)

  1. Funkční a komerční dotazy
  2. Technické dotazy

📡 Archiv starších verzí eAPI

  1. eAPI 1.8
  2. eAPI 1.7
  3. eAPI 1.6
  4. eAPI 1.5
  5. eAPI 1.0
Clone this wiki locally