Metadata-Version: 2.1
Name: midtransclient
Version: 1.0.2
Summary: Official Midtrans Payment API Client
Home-page: https://github.com/midtrans/midtrans-client-python
Author: Rizda Prasetya
Author-email: rizda.prasetya@midtrans.com
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=2.7
Description-Content-Type: text/markdown
Requires-Dist: requests (>=2.3.0)

Midtrans Client - Python
===============

[![Build Status](https://travis-ci.org/rizdaprasetya/midtrans-python-client.svg?branch=master)](https://travis-ci.org/rizdaprasetya/midtrans-python-client)

Midtrans ❤️ Python! 🐍

This is the Official Python API client/library for Midtrans Payment API. Visit [https://midtrans.com](https://midtrans.com). More information about the product and see documentation at [http://docs.midtrans.com](http://docs.midtrans) for more technical details.

## 1. Installation

### 1.a Using Pip

```
pip install midtransclient
```

### 1.b Manual Installation

If you are not using Pip, you can clone or [download](https://github.com/midtrans/midtrans-client-python/archive/master.zip) this repository.
Then import from `midtransclient` folder.

Or run Pip install from the repo folder.
```
pip install .
```

## 2. Usage

### 2.1 Choose Product/Method

We have [2 different products](https://docs.midtrans.com/en/welcome/index.html) of payment that you can use:
- [Snap](#22A-snap) - Customizable payment popup will appear on **your web/app** (no redirection). [doc ref](https://snap-docs.midtrans.com/)
- [Snap Redirect](#22B-snap-redirect) - Customer need to be redirected to payment url **hosted by midtrans**. [doc ref](https://snap-docs.midtrans.com/)
- [Core API (VT-Direct)](#22C-core-api-vt-direct) - Basic backend implementation, you can customize the frontend embedded on **your web/app** as you like (no redirection). [doc ref](https://api-docs.midtrans.com/)

Choose one that you think best for your unique needs.

### 2.2 Client Initialization and Configuration

Get your client key and server key from [Midtrans Dashboard](https://dashboard.midtrans.com)

Create API client object

```python
# Core API
core_api = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
```


```python
# Snap API
snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
```

You can also re-set config using `Snap.api_config.set( ... )`
example:

```python

# initialize object, empty config
snap = midtransclient.Snap()

# re-set full config
snap.api_config.set(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

# re-set server_key only
snap.api_config.set(server_key='YOUR_SERVER_KEY')

# re-set is_production only
snap.api_config.set(is_production=True)
```

You can also set config directly from attribute
```python
# initialize object, empty config
snap = midtransclient.Snap()

# set config
snap.api_config.is_production=False
snap.api_config.server_key='YOUR_SERVER_KEY'
snap.api_config.client='YOUR_CLIENT_KEY'
```


### 2.2.A Snap
You can see Snap example [here](examples/snap).

Available methods for `Snap` class
```python
# return Snap API /transaction response as Dictionary
def create_transactions(parameter):

# return Snap API /transaction token as String
def create_transactions_token(parameter):

# return Snap API /transaction redirect_url as String
def create_transactions_redirect_url(parameter):
```
`parameter` is Dictionary or String of JSON of [SNAP Parameter](https://snap-docs.midtrans.com/#json-objects)


#### Get Snap Token

```python
param = {
    "transaction_details": {
        "order_id": "test-transaction-123",
        "gross_amount": 200000
    }, "credit_card":{
        "secure" : True
    }
}

transaction = snap.create_transaction(param)

transaction_token = transaction['token']
# alternative way to create transaction_token:
# transaction_token = snap.create_transaction_token(param)
```


#### Initialize Snap JS when customer click pay button

Replace `PUT_TRANSACTION_TOKEN_HERE` with `transaction_token` acquired above
```html
<html>
  <body>
    <button id="pay-button">Pay!</button>
    <pre><div id="result-json">JSON result will appear here after payment:<br></div></pre> 

<!-- TODO: Remove ".sandbox" from script src URL for production environment. Also input your client key in "data-client-key" -->
    <script src="https://app.sandbox.midtrans.com/snap/snap.js" data-client-key="<Set your ClientKey here>"></script>
    <script type="text/javascript">
      document.getElementById('pay-button').onclick = function(){
        // SnapToken acquired from previous step
        snap.pay('PUT_TRANSACTION_TOKEN_HERE', {
          // Optional
          onSuccess: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          },
          // Optional
          onPending: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          },
          // Optional
          onError: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          }
        });
      };
    </script>
  </body>
</html>
```

#### Implement Notification Handler
[Refer to this section](#23-handle-http-notification)

### 2.2.B Snap Redirect

Also available as examples [here](examples/snap).

#### Get Redirection URL of a Payment Page

```python
param = {
    "transaction_details": {
        "order_id": "test-transaction-123",
        "gross_amount": 200000
    }, "credit_card":{
        "secure" : True
    }
}

transaction = snap.create_transaction(param)

transaction_redirect_url = transaction['redirect_url']
# alternative way to create redirect_url:
# transaction_redirect_url = snap.create_redirect_url(param)
```
#### Implement Notification Handler
[Refer to this section](#23-handle-http-notification)

### 2.2.C Core API (VT-Direct)

You can see some Core API examples [here](examples/core_api).

Available methods for `CoreApi` class
```python
def charge(self,parameters=dict()):
    """
    Trigger `/charge` API call to Core API
    :param parameters: dictionary of Core API JSON body as parameter, will be converted to JSON
    (more params detail refer to: https://api-docs.midtrans.com)

    :return: Dictionary from JSON decoded response
    """

def capture(self,parameters=dict()):
    """
    Trigger `/capture` API call to Core API
    Capture is only used for pre-authorize transaction only
    :param parameters: dictionary of Core API JSON body as parameter, will be converted to JSON
    (more params detail refer to: https://api-docs.midtrans.com)

    :return: Dictionary from JSON decoded response
    """

def card_register(self,parameters=dict()):
    """
    Trigger `/card/register` API call to Core API
    :param parameters: dictionary of Core API JSON body as parameter, will be converted to JSON
    (more params detail refer to: https://api-docs.midtrans.com)

    :return: Dictionary from JSON decoded response
    """

def card_token(self,parameters=dict()):
    """
    Trigger `/token` API call to Core API
    :param parameters: dictionary of Core API JSON body as parameter, will be converted to JSON
    (more params detail refer to: https://api-docs.midtrans.com)

    :return: Dictionary from JSON decoded response
    """

def card_point_inquiry(self,token_id):
    """
    Trigger `/point_inquiry/<token-id>` API call to Core API
    :param parameters: dictionary of Core API JSON body as parameter, will be converted to JSON
    (more params detail refer to: https://api-docs.midtrans.com)

    :return: Dictionary from JSON decoded response
    """
```
`parameter` is Dictionary or String of JSON of [SNAP Parameter](https://api-docs.midtrans.com/#json-objects)

#### Credit Card Get Token

Get token should be handled on  Frontend please refer to [API docs](https://api-docs.midtrans.com)

#### Credit Card Charge

```python
param = {
    "payment_type": "credit_card",
    "transaction_details": {
        "gross_amount": 12145,
        "order_id": "test-transaction-54321",
    },
    "credit_card":{
        "token_id": 'CREDIT_CARD_TOKEN' # change with your card token
    }
}

# charge transaction
charge_response = snap.charge(param)
print('charge_response:')
print(charge_response)
```


### 2.3 Handle HTTP Notification

Create separated web endpoint (notification url) to receive HTTP POST notification callback/webhook. 
HTTP notification will be sent whenever transaction status is changed.
Example also available [here](examples/transaction_actions/notification_example.py)

```python
status_response = api_client.transactions.notification(mock_notification)

order_id = status_response['order_id']
transaction_status = status_response['transaction_status']
fraud_status = status_response['fraud_status']

print('Transaction notification received. Order ID: {0}. Transaction status: {1}. Fraud status: {3}'.format(order_id,
    transaction_status,
    fraud_status))

# Sample transaction_status handling logic

if transaction_status == 'capture':
  if fraud_status == 'challenge':
    # TODO set transaction status on your databaase to 'challenge'
  else if fraud_status == 'accept':
    # TODO set transaction status on your databaase to 'success'
else if transaction_status == 'cancel' or 
  transaction_status == 'deny' or 
  transaction_status == 'expire':
  # TODO set transaction status on your databaase to 'failure'
else if transaction_status == 'pending':
  # TODO set transaction status on your databaase to 'pending' / waiting payment
```

### 2.4 Transaction Action
Also available as examples [here](examples/transaction_actions)
#### Get Status
```python
# get status of transaction that already recorded on midtrans (already `charge`-ed) 
status_response = api_client.transactions.status('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Get Status B2B
```python
# get transaction status of VA b2b transaction
statusb2b_response = api_client.transactions.statusb2b('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Approve Transaction
```python
# approve a credit card transaction with `challenge` fraud status
approve_response = api_client.transactions.approve('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Deny Transaction
```python
# deny a credit card transaction with `challenge` fraud status
deny_response = api_client.transactions.deny('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Cancel Transaction
```python
# cancel a credit card transaction or pending transaction
cancel_response = api_client.transactions.cancel('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Expire Transaction
```python
# expire a pending transaction
expire_response = api_client.transactions.expire('YOUR_ORDER_ID OR TRANSACTION_ID')
```
#### Refund Transaction
```python
# refund a transaction (not all payment channel allow refund via API)
param = {
    "amount": 5000,
    "reason": "Item out of stock"
}
refund_response = api_client.transactions.refund('YOUR_ORDER_ID OR TRANSACTION_ID',param)
```

## 3. Examples
Examples are available on [/examples](/examples) folder.
There are:
- [Core Api examples](/examples/core_api)
- [Snap examples](/examples/snap_api)
- [Flask App examples](/examples/flask_app) that implement Snap & Core Api

#### Get help

* [Midtrans Docs](https://docs.midtrans.com)
* [Midtrans Dashboard ](https://dashboard.midtrans.com/)
* [SNAP documentation](http://snap-docs.midtrans.com)
* [Core API documentation](http://api-docs.midtrans.com)
* Can't find answer you looking for? email to [support@midtrans.com](mailto:support@midtrans.com)

