Business - Payment Methods
==========================
.. Last update: 04/04/2022

The user can specify several payment methods, and store pre-authorization binary blobs on the
server.

The base url for the APIs in this page is at::

  /api/business-mobile/

A JSON file with OpenAPI data about all business-related mobile APIs can be downloaded :download:`here </openapi/srv-business-base/api-src-WebMobile.json>`.

List actual methods
-------------------

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/list

If there is an error the response will be negative without any further indications.

If positive, ``Data`` will be::

  [
    {
      ID: 7,                                           // Int
      CreatedDate: "2001-01-01T01:01:01Z",             // DateTime
      Name: "Personal PayPal Account",                 // String
      Type: 3,                                         // Int (enum)
      LastValidTransaction: "2001-01-01T01:01:01Z",    // DateTime (nullable)
      LastErrorDescription: "",	                       // String
      IsPreferred: true,                               // Boolean
      CardHolderName: "Credit card holder",            // String (nullable)
      CardNumber: "Credit card number",                // String (nullable)
      CardBrand: "Credit card circuit",                // String (nullable)
      CardExpiryYear: "Credit card expiry year",       // String (nullable)
      CardExpiryMonth: "Credit card expiry month"      // String (nullable)
    },
    ...
  ]

``Type`` can be one of the :ref:`enum-paymentmethodtype` enumeration.

Add new method
--------------

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/new

With a request body like this::

  {
    Name: "Personal PayPal Account",                   // String
    Type: 3                                            // Int
  }

Where ``Type`` can be one of the :ref:`enum-paymentmethodtype` enumeration.

Furthermore, the API accepts the parameters needed for the payment gateway to retrieve the
recurrent payment authorization data and the credit card data. 
The request body for this varies depending on the payment method's type, that can be one of the values defined in
the :ref:`enum-paymentmethodtype` enumeration.

For WorldPay the body is the following::

  {
    Session: "session token",              // String
    CardHolderName "Credit card holder"    // String
  }

Possible errors are:

``err_InvalidElement``
  One of the required request body properties is missing or not set


Add new method with authorization data
--------------------------------------
Creates a new payment method, adding authorization and credit card data

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/add-authorization-data

The API creates a new payment method for the platform's default gateway, as defined in the :ref:`environment variable<configuration-business>` ``DEFAULT_PAYMENT_METHOD``,
whose value can be one of the :ref:`enum-paymentmethodtype` enumeration.

The request body format varies depending on the variable's value.
For WorldPay the body is the following::

  {
    Session: "session token",              // String
    CardHolderName "Credit card holder"    // String
  }

The API will respond with a generic error if the user already has a payment method defined, or if some error occurs in the process,
or with the following error code:

``err_InvalidElement``
  One of the required request body properties is missing or not set
  
Add authorization data to a method
----------------------------------
Adds card authorization data to an existing payment method

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/{paymentMethodId}/add-authorization-data
     
The request body varies depending on the payment method's type, that can be one of the values defined in
the :ref:`enum-paymentmethodtype` enumeration.

For WorldPay the body is the following::

  {
    Session: "session token",              // String
    CardHolderName "Credit card holder"    // String
  }
  
Possible errors are:

``err_InvalidElement``
  One of the required request body properties is missing or not set

Update data
-----------

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/edit/{id}

With a request body like this::

  {
    Name: "Personal PayPal Account",                   // String
    Type: 3                                            // Int
  }

Where ``Type`` can be one of the :ref:`enum-paymentmethodtype` enumeration.
The result can be a plain positive response or a negative response with no additional data.

Delete one
----------

.. openapi:: /openapi/srv-business-base/api-src-WebMobile.json
   :paths:
     /v1/payment-methods/{id}

The result can be a plain positive response or a negative response with no additional data.