Payment methods
The merchandised checkout choices over each registered provider.
The merchandised checkout choices over each registered provider. See Payment methods.
List payment methods
/api/v1/kahunacart/payment-methods
Every merchandised payment method this store offers, with its fee, its scoping conditions and the gateway it runs over. A method is not a provider: a provider is a credentialed integration written in code, and a method is a row a merchant types — "Visa", "Klarna" and "Bank transfer" can be three methods over one or two providers. The answer also carries the registered providers, and a provider_registered flag per method so a method whose gateway plugin is switched off can be told apart from one the merchant has disabled.
Create a payment method
/api/v1/kahunacart/payment-methods
Add a checkout choice over an existing gateway. The fee is a fixed amount plus a percentage, both optional, and it lands on the order as its own adjustment taxed at fee_tax_class — which is how a cash-on-delivery surcharge works and why there is no separate surcharge concept. Scope it with conditions to make it appear only for the orders it suits.
Parameters
| Name | Type | Description |
|---|---|---|
| provider required | string | The gateway slug that takes the money, e.g. offline or stripe |
| code required | string | This method's own handle within that gateway, e.g. bank_transfer |
| label_key optional | string | What the customer reads; a translation key or the words themselves |
| description_key optional | string | The sentence under the label; a translation key or the words themselves |
| logo optional | string | Path or URL to the mark shown beside the label |
| instructions optional | string | Markdown shown once this method is chosen — where a bank transfer's account details go. Placeholders {order_number}, {order_total}, {currency}, {customer_email} and {config.<key>} are substituted; it is not Twig and nothing in it is executed. |
| enabled optional | boolean |
Default:
true |
| position optional | integer | Where it sits in the checkout list |
| fee_fixed_minor optional | integer | The fixed half of the surcharge, in minor units of the store currency |
| currencies optional | array of string | The currencies this method is offered in, only on a store that sells in more than one; an empty list, which is the default, is every currency. A method limited to EUR is shown as unavailable on an order in any other currency. The list narrows what the gateway already allows and never widens it |
| currency_amounts optional | object | The fixed fee in the store's other currencies, {"EUR": {"fee_fixed": "2.50"}}, as decimal strings in that currency's own decimal places. A method with no fixed fee in the order's currency charges only its percentage there. An empty string removes one |
| fee_percent optional | string | The percentage half, as a decimal string ("1.5"); never a float |
| fee_tax_class optional | string | Which tax class the fee is taxed under; empty means the store default |
| zero_total_only optional | boolean | Only offer it when there is nothing to pay. No longer needed for free orders: since 1.4.6 an order with nothing to pay completes paid without asking any provider, whichever method is chosen. A method already set this way keeps working. |
| config optional | object | The method's own settings — account number, sort code, payee name — readable from the instructions as {config.<key>} |
| conditions optional | object | When this method is offered at all, as a nested document — {"container": "all", "children": [{"attribute": "cart_subtotal", "operator": "gte", "value": 50000}]}. Containers are all, any or none and they nest. Attributes come from list_rule_attributes and an unknown one is refused. A method that fails its conditions is shown as unavailable with a reason rather than silently dropped. A condition on an amount of money (type money) is in one currency: leave `currency` out for the store currency, or name a currency the store sells in, as in {"attribute": "cart_subtotal", "operator": "gte", "value": 4500, "currency": "EUR"}. It is false on an order in any other currency, so cover two currencies with one condition each inside an `any` container. |
Update a payment method
/api/v1/kahunacart/payment-methods/{id}
Change a method's merchandising, its fee, or its conditions. Sending conditions replaces the whole set, a container with no children removes the scoping, and omitting it leaves the set standing.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Payment method id |
| provider optional | string | |
| code optional | string | |
| label_key optional | string | |
| description_key optional | string | |
| logo optional | string | |
| instructions optional | string | |
| enabled optional | boolean | |
| position optional | integer | |
| fee_fixed_minor optional | integer | At least 0. |
| currencies optional | array of string | The currencies it is offered in; see create_payment_method |
| currency_amounts optional | object | The fixed fee in the other currencies; see create_payment_method |
| fee_percent optional | string | A decimal string ("1.5"); never a float |
| fee_tax_class optional | string | |
| zero_total_only optional | boolean | |
| config optional | object | |
| conditions optional | object |
Delete a payment method
/api/v1/kahunacart/payment-methods/{id}
Remove a checkout choice and the conditions that scoped it. Orders paid by it are untouched and keep saying how they were paid: an order records provider/code, not this row's id.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Payment method id |
Reorder payment methods
/api/v1/kahunacart/payment-methods/reorder
Put the checkout list in the order given. Send every id, in the order you want them; ids the store does not have are ignored rather than refused.
Parameters
| Name | Type | Description |
|---|---|---|
| ids required | array of integer | Every payment method id, in the order they should appear |
Sending conditions on a PATCH replaces the whole set. An attribute the store does not publish is refused by name on the save, never at checkout.