DocsValtuutukset, veloitukset ja mitätöinnit
Hallitse maksun valtuutus-, veloitus- ja mitätöintikulkuja
Jotkut maksutavat tukevat kaksivaiheista kulkua: ensin valtuuta (varaa varat), sitten veloita (peri varat) tai mitätöi (vapauta varaus).
Veloitustilat
Aseta capture_mode tilaukseen hallitaksesi, milloin varat veloitetaan:
| Tila | Toiminta |
|---|---|
manual | Veloitat eksplisiittisesti, kun olet valmis (esim. lähetyksen jälkeen). Jos et veloita ennen tilauksen vanhenemista, valtuutus menetetään eikä sitä voi enää veloittaa. |
delayed | Varat veloitetaan automaattisesti expiration_period-ajan kuluessa. |
{
"currency": "EUR",
"amount": 5000,
"capture_mode": "manual",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}manual-veloitustilassa sinun täytyy veloittaa ennen tilauksen vanhenemisajan päättymistä. Vanhenemisen jälkeen valtuutus vapautetaan eikä varoja voi enää veloittaa. Aseta sopiva expiration_period toimitusaikataulullesi.
Voit asettaa capture_mode-tilan tilaustasolla ilman transactions-kentän määrittämistä. Isännöity maksusivu näyttää tällöin vain maksutavat, jotka tukevat määritettyä veloitustilaa.
Veloitettavissa olevien summien tarkistaminen
Ennen veloitusta voit tarkistaa, kuinka paljon on käytettävissä veloitettavaksi pyytämällä amount_details-tiedot:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"Vastaus sisältää amount_details-objektin:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Tilausrivit
Käytettäessä veloituksia ja mitätöintejä tilausrivin mukaan, käytä seuraavia tyyppejä:
| Tyyppi | Kuvaus |
|---|---|
physical | Fyysinen tuote |
discount | Alennussumma |
shipping_fee | Toimituskustannus |
sales_tax | Myyntivero |
digital | Digitaalinen tuote |
gift_card | Lahjakortti |
store_credit | Myymäläkrediitti |
surcharge | Lisämaksu |
Maksujen veloittaminen
Veloitus tilausrivin mukaan
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Veloitus summan mukaan
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Maksujen mitätöinti
Mitätöinti vapauttaa valtuutetut varat takaisin asiakkaalle.
Mitätöinti tilausrivin mukaan
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Mitätöinti summan mukaan
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Kyselyparametrit
Lisää kyselyparametreja sisällyttääksesi lisätietoja vastaukseen:
| Parametri | Kuvaus |
|---|---|
?fields[]=order_line_details | Sisällytä tilausrivien erittely |
?fields[]=amount_details | Sisällytä summien erittely |
Optimistinen lukitus
Veloitus- ja mitätöintipäätepisteet tukevat ETag-pohjaista optimistista lukitusta if-match-otsakkeen kautta. Tämä estää kilpailutilanteita, kun useat järjestelmät yrittävät veloittaa saman tapahtuman.
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
-u {api_key}: \
-H "Content-Type: application/json" \
-H "if-match: \"etag-value\"" \
-d '{"description": "Capture", "amount": 2500}'Jos ETag ei täsmää (tilausta on muokattu sen jälkeen kun hait sen viimeksi), saat 412 Precondition Failed -vastauksen.
Cost+ tukee yhtä veloitusta valtuutusta kohden, ja mitätöintejä voidaan käsitellä vain ennen veloitusta. Suunnittele veloitusstrategiasi sen mukaisesti.
Liittyvät päätepisteet
- Veloitus summan mukaan — veloita tietty summa valtuutetusta tilauksesta
- Veloitus tilausrivin mukaan — veloita tietyt tilausrivit
- Mitätöinti summan mukaan — mitätöi tietty summa valtuutetusta tilauksesta
- Mitätöinti tilausrivin mukaan — mitätöi tietyt tilausrivit