3. How to create a Payment backend — django SHOP 0.1.1.dev0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django SHOP 0.1.1.dev0 documentation »

# 3. How to create a Payment backend

Payment backends must be listed in settings.SHOP_PAYMENT_BACKENDS

## 3.1. Shop interface

While we could solve this by defining a superclass for all payment backends, the better approach to plugins is to implement inversion-of-control, and let the backends hold a reference to the shop instead.

The reference interface for payment backends is located at

class `shop.payment.api.` `ShopPaymentAPI`

Currently, the shop interface defines the following methods:

### 3.1.1. Common with shipping

`ShopPaymentAPI.` `get_order`(request)

  Returns the order currently being processed.

  Parameters: | request – a Django request object
  Return type: | an `Order` instance

`ShopPaymentAPI.` `add_extra_info`(order, text)

  Adds an extra info field to the order (whatever)

  Parameters: | order – an `Order` instance text – a string containing the extra order information

`ShopPaymentAPI.` `is_order_payed`(order)

  Whether the passed order is fully paid or not

  Parameters: | order – an `Order` instance
  Return type: | `bool`

`ShopPaymentAPI.` `is_order_complete`(order)

  Whether the passed order is in a “finished” state

  Parameters: | order – an `Order` instance
  Return type: | `bool`

`ShopPaymentAPI.` `get_order_total`(order)

  Returns the order’s grand total.

  Parameters: | order – an `Order` instance
  Return type: | `Decimal`

`ShopPaymentAPI.` `get_order_subtotal`(order)

  Returns the order’s sum of item prices (without taxes or S&H)

  Parameters: | order – an `Order` instance
  Return type: | `Decimal`

`ShopPaymentAPI.` `get_order_short_name`(order)

  A short human-readable description of the order

  Parameters: | order – an `Order` instance
  Return type: | a string with the short name of the order

`ShopPaymentAPI.` `get_order_unique_id`(order)

  The order’s unique identifier for this shop system

  Parameters: | order – an `Order` instance
  Return type: | the primary key of the `Order` (in the default implementation)

`ShopPaymentAPI.` `get_order_for_id`(id)

  Returns an `Order` object given a unique identifier (this is the reverse of `get_order_unique_id()`)

  Parameters: | id – identifier for the order
  Return type: | the `Order` object identified by `id`

### 3.1.2. Specific to payment

`ShopPaymentAPI.` `confirm_payment`(order, amount, transaction_id, save=True)

  This should be called when the confirmation from the payment processor was called and that the payment was confirmed for a given amount. The processor’s transaction identifier should be passed too, along with an instruction to save the object or not. For instance, if you expect many small confirmations you might want to save all of them at the end in one go (?). Finally the payment method keeps track of what backend was used for this specific payment.

  Parameters: | order – an `Order` instance amount – the paid amount transaction_id – the backend-specific transaction identifier save – a `bool` that indicates if the changes should be committed to the database.

## 3.2. Backend interface

The payment backend should define the following interface for the shop to be able do to anything sensible with it:

### 3.2.1. Attributes

`PaymentBackend.` `backend_name`

  The name of the backend (to be displayed to users)

`PaymentBackend.` `url_namespace`

  “slug” to prepend to this backend’s URLs (acting as a namespace)

### 3.2.2. Methods

`PaymentBackend.` `__init__`(shop)

  must accept a “shop” argument (to let the shop system inject a reference to it)

  Parameters: | shop – an instance of the shop

`PaymentBackend.` `get_urls`()

  should return a list of URLs (similar to urlpatterns), to be added to the URL resolver when urls are loaded. These will be namespaced with the url_namespace attribute by the shop system, so it shouldn’t be done manually.

### 3.2.3. Security

In order to make your payment backend compatible with the `SHOP_FORCE_LOGIN` setting please make sure to add the `@shop_login_required` decorator to any views that your backend provides. See How to secure your views for more information.

### Navigation

- index
- modules |
- next |
- previous |
- django SHOP 0.1.1.dev0 documentation »