### Install Midtrans Python Client from Repository

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Install the library by navigating to the repository folder and running pip install.

```bash
pip install .
```

--------------------------------

### Initialize Core API and Handle Notifications

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Setup the Core API client and process incoming transaction notifications.

```python
api_client = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
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
```

--------------------------------

### Install Project Locally

Source: https://github.com/midtrans/midtrans-python-client/blob/master/Maintaining.md

Installs the project locally using pipenv, allowing for development and testing within a virtual environment. Ensure pipenv is installed and you are in the project directory.

```bash
pipenv install

```

```bash
pipenv install --python /usr/bin/python3

```

```bash
pipenv shell

```

```bash
pip install -e .

```

--------------------------------

### Install Midtrans Client

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Use pip to install the official Midtrans Python library.

```bash
pip install midtransclient
```

--------------------------------

### Run Project with Docker Compose

Source: https://github.com/midtrans/midtrans-python-client/blob/master/Maintaining.md

Starts the project services using Docker Compose, typically for running tests within a containerized environment. Use 'docker-compose down' to stop and clean up containers.

```bash
docker-compose up

```

```bash
docker-compose down

```

--------------------------------

### Build and Upload Package to PyPI

Source: https://github.com/midtrans/midtrans-python-client/blob/master/Maintaining.md

Commands to build the package distribution files and upload them to the Python Package Index (PyPI) or TestPyPI. This process involves installing necessary tools like setuptools, wheel, and twine.

```bash
python -m pip install --upgrade setuptools wheel

```

```bash
python setup.py sdist bdist_wheel

```

```bash
python -m pip install --upgrade twine

```

```bash
twine upload dist/* --skip-existing

```

```bash
twine upload --repository-url https://test.pypi.org/legacy/ dist/* --skip-existing

```

--------------------------------

### GoPay Account Linking Initialization

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Initialize the Midtrans Core API client for GoPay account linking. This setup is a prerequisite for tokenization processes.

```python
import midtransclient
import datetime

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

--------------------------------

### Get Subscription Details

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Retrieve the current details of an existing subscription using its ID.

```python
details = core_api.get_subscription(subscription_id)
print(f"Next execution: {details['schedule']['next_execution_at']}")
```

--------------------------------

### Create Snap Transaction

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Prepare transaction parameters and call the create_transaction method to get a transaction token and details. The parameter dictionary must include transaction details and can optionally include credit card configurations.

```python
# Create Snap API instance
snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# Prepare parameter
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)
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/midtrans/midtrans-python-client/blob/master/Maintaining.md

Executes tests using pytest. For specific test cases, use the -k flag. Ensure pytest is installed if you encounter errors.

```bash
pytest

```

```bash
pytest -k "test_core_api_charge_fail_401"

```

```bash
pip install pytest

```

--------------------------------

### Get B2B Transaction Status

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Retrieve the status of a B2B transaction using its order ID. This is applicable for VA transactions.

```python
b2b_status = api_client.transactions.statusb2b(order_id)
```

--------------------------------

### Initialize Snap API Client

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Create an instance of the Snap class for customizable payment popups. Ensure your server and client keys are correctly set.

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

--------------------------------

### Initialize Core API Client

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Create an instance of the CoreApi class for backend integrations. Ensure your server and client keys are correctly set.

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

--------------------------------

### Create Subscription Payment

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Set up recurring subscription payments using credit card tokens. Requires initial payment token and scheduling details.

```python
import midtransclient
import datetime

core_api = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

# Create subscription (requires saved_token_id from initial card payment)
subscription_param = {
    "name": "PREMIUM-MONTHLY-" + datetime.datetime.now().strftime("%Y%m%d%H%M%S"),
    "amount": "100000",
    "currency": "IDR",
    "payment_type": "credit_card",
    "token": "SAVED_TOKEN_ID_FROM_INITIAL_PAYMENT",
    "schedule": {
        "interval": 1,
        "interval_unit": "month",  # Options: day, week, month
        "max_interval": 12,
        "start_time": "2024-01-01 00:00:00 +0700"
    },
    "metadata": {
        "description": "Premium subscription"
    },
    "customer_details": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@email.com",
        "phone": "+62812345678"
    }
}

# Create subscription
subscription = core_api.create_subscription(subscription_param)
subscription_id = subscription['id']
print(f"Subscription ID: {subscription_id}")
print(f"Status: {subscription['status']}")
```

--------------------------------

### Instantiate Midtrans Snap API Client

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Create an instance of the Midtrans Snap API client. Set `is_production` to `False` for sandbox environment. Requires server and client keys.

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

--------------------------------

### Configure Advanced Client Settings

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Shows how to initialize the Midtrans client with custom HTTP headers, override notification URLs, configure proxy settings, and re-configure client properties after initialization.

```python
import midtransclient

snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

snap.api_config.custom_headers = {
    'x-custom-header': 'custom-value',
    'x-override-notification': 'https://myapp.com/webhook',
    'x-append-notification': 'https://backup.myapp.com/webhook'
}

snap.api_config.proxies = {
    'http': 'http://proxy.company.com:8080',
    'https': 'http://proxy.company.com:8080'
}

snap.api_config.set(
    is_production=True,
    server_key='PRODUCTION_SERVER_KEY',
    client_key='PRODUCTION_CLIENT_KEY'
)

snap.api_config.is_production = True
snap.api_config.server_key = 'NEW_SERVER_KEY'
```

--------------------------------

### Create Snap Transaction

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Initialize the Snap client and generate payment tokens or redirect URLs for the payment popup.

```python
import midtransclient

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

# Prepare transaction parameters
param = {
    "transaction_details": {
        "order_id": "order-12345",
        "gross_amount": 200000
    },
    "credit_card": {
        "secure": True
    },
    "customer_details": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@email.com",
        "phone": "+62812345678"
    }
}

# Create transaction
transaction = snap.create_transaction(param)

# Get transaction token for Snap.js popup
transaction_token = transaction['token']
print(f"Token: {transaction_token}")

# Get redirect URL for Snap redirect method
redirect_url = transaction['redirect_url']
print(f"Redirect URL: {redirect_url}")

# Alternative methods to get token or URL directly
token = snap.create_transaction_token(param)
url = snap.create_transaction_redirect_url(param)
```

--------------------------------

### Initialize Snap JS for Frontend Payments

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Embeds the Snap JS library and configures the pay button to trigger the payment modal with a transaction token.

```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>
```

--------------------------------

### Process Credit Card Charge via Core API

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Demonstrates how to charge a credit card transaction using the Core API instance.

```python
# Create Core API instance
core_api = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# Prepare parameter
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
        "authentication": True
    }
}

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

--------------------------------

### Generate Snap Redirect URL

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Initializes the Snap client and creates a transaction to obtain a redirect URL for the payment page.

```python
# Create Snap API instance
snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# Prepare parameter
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)
```

--------------------------------

### Create Subscription API for Credit Card

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Use this snippet to create a subscription for credit card payments. Ensure you have obtained a 1-click saved token and include necessary customer and schedule details.

```python
# Create Subscription API instance
core_api = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# Prepare parameter
param = {
    "name": "SUBSCRIPTION-STARTER-1",
    "amount": "100000",
    "currency": "IDR",
    "payment_type": "credit_card",
    "token": "436502qFfqfAQKScMtPRPdZDOaeg7199",
    "schedule": {
      "interval": 1,
      "interval_unit": "month",
      "max_interval": 3,
      "start_time": "2021-10-01 07:25:01 +0700"
    },
    "metadata": {
      "description": "Recurring payment for STARTER 1"
    },
    "customer_details": {
      "first_name": "John A",
      "last_name": "Doe A",
      "email": "johndoe@email.com",
      "phone": "+62812345678"
    }
}
create_subscription_response = core_api.create_subscription(param)

subscription_id_response = create_subscription_response['id']
# get subscription by subscription_id
get_subscription_response = core_api.get_subscription(subscription_id_response)

# disable subscription by subscription_id
disable_subscription_response = core_api.disable_subscription(subscription_id_response)

# enable subscription by subscription_id
enable_subscription_response = core_api.enable_subscription(subscription_id_response)

# update subscription by subscription_id
update_param = {
    "name": "SUBSCRIPTION-STARTER-1-UPDATE",
    "amount": "100000",
    "currency": "IDR",
    "token": "436502qFfqfAQKScMtPRPdZDOaeg7199",
    "schedule": {
      "interval": 1
}
update_subscription_response = core_api.update_subscription(subscription_id_response, update_param)
```

--------------------------------

### Re-configure Snap API Client

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Update the configuration of an existing Snap API instance using the set method. This allows dynamic changes to production status, server key, and client key.

```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)
```

--------------------------------

### Tokenization API for Gopay Account Linking

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

This snippet demonstrates how to link a customer's Gopay account using the Tokenization API. You need to obtain a Gopay payment token first via the `get_payment_account` API call.

```python
# Create Tokenization API instance
core_api = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# Prepare parameter
param = {
  "payment_type": "gopay",
  "gopay_partner": {
    "phone_number": "81234567891",
    "country_code": "62",
    "redirect_url": "https://mywebstore.com/gopay-linking-finish" #please update with your redirect URL
  }
}

# link payment account
link_payment_account_response = core_api.link_payment_account(param)

# get payment account
get_payment_account_response = core_api.get_payment_account(active_account_id)

# unlink account
unlink_payment_account_response = core_api.unlink_payment_account(active_account_id)
```

--------------------------------

### Enable Subscription

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Resume recurring charges for a disabled subscription. Requires the subscription ID.

```python
core_api.enable_subscription(subscription_id)
```

--------------------------------

### Link and Charge GoPay Account

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Demonstrates linking a GoPay account, retrieving its details, and then using it to charge a transaction. Requires customer authorization for linking.

```python
link_param = {
    "payment_type": "gopay",
    "gopay_partner": {
        "phone_number": "81234567891",
        "country_code": "62",
        "redirect_url": "https://mystore.com/gopay-callback"
    }
}

link_response = core_api.link_payment_account(link_param)
account_id = link_response['account_id']
print(f"Account ID: {account_id}")
print(f"Status: {link_response['account_status']}")  # PENDING initially

activation_url = link_response['actions'][0]['url']
print(f"Activation URL: {activation_url}")

account = core_api.get_payment_account(account_id)
if account['account_status'] == 'ENABLED':
    payment_token = account['metadata']['payment_options'][0]['token']

    charge_param = {
        "payment_type": "gopay",
        "gopay": {
            "account_id": account_id,
            "payment_option_token": payment_token,
            "callback_url": "https://mystore.com/payment-callback"
        },
        "transaction_details": {
            "gross_amount": 50000,
            "order_id": "GOPAY-" + datetime.datetime.now().strftime("%Y%m%d%H%M%S")
        }
    }
    charge_response = core_api.charge(charge_param)
    print(f"Transaction: {charge_response['transaction_id']}")

unlink_response = core_api.unlink_payment_account(account_id)
```

--------------------------------

### Frontend Tokenization and 3DS Authentication

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/core_api_credit_card_frontend_sample.html

JavaScript implementation for capturing card tokens and handling 3DS authentication flows.

```javascript
document.querySelector("#token-form").onsubmit = function(e){ var card = { "card\_number": document.querySelector("#card-number").value, "card\_exp\_month": document.querySelector("#card-expiry-month").value, "card\_exp\_year": document.querySelector("#card-expiry-year").value, "card\_cvv": document.querySelector("#card-cvv").value, }; MidtransNew3ds.getCardToken( card, { onSuccess: function(response){ // Success to get card token\_id, implement as you wish here: document.querySelector("#token\_id\_result").value = response.token\_id; document.querySelector("#token\_id").value = response.token\_id; }, onFailure: function(response){ // Fail to get card token\_id alert(`Fail to get card token\_id: ${JSON.stringify(response)}`); console.log(`Fail to get card token\_id: ${JSON.stringify(response)}`); } } ); return e.preventDefault() && 0; // prevent form submit } document.querySelector("#authentication-form").onsubmit = function(e){ var redirect\_url = document.querySelector("#redirect\_url").value; // Utilize MidtransNew3Ds.authenticate function to perform 3DS authentication, // and handle the success/failure result MidtransNew3ds.authenticate( redirect\_url, { performAuthentication: function(redirect\_url){ // open iframe to display 3ds authentication redirect\_url to customer popupModal.openPopup(redirect\_url); }, onSuccess: function(response){ // 3ds authentication success, implement payment success scenario popupModal.closePopup(); document.querySelector("#result").innerText = JSON.stringify(response,null,2); }, onFailure: function(response){ // 3ds authentication failure, implement payment failure scenario popupModal.closePopup(); document.querySelector("#result").innerText = JSON.stringify(response,null,2); }, onPending: function(response){ // transaction is pending, transaction result will be notified later via POST notification popupModal.closePopup(); document.querySelector("#result").innerText = JSON.stringify(response,null,2) } } ); return e.preventDefault() && 0; // prevent form submit } /** * Alternatively instead of opening 3ds authentication redirect\_url using iframe, * you can also redirect customer using: ``` MidtransNew3ds.redirect(redirect\_url, { callbackUrl : 'https://mywebsite.com/finish\_3ds' }); ``` * */ /** * helper functions to open Iframe popup, you may replace this with your own method to open iframe * PicoModal library is used: * <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/picomodal/3.0.0/picoModal.js"><\/script> */ var popupModal = (function(){ var modal = null; return { openPopup(url){ modal = picoModal({ content:'<iframe frameborder="0" style="height:90vh; width:100%;" src="'+url+'"></iframe>', width: "75%", closeButton: false, overlayClose: false, escCloses: false }).show(); }, closePopup(){ try{ modal.close(); } catch(e) {} } } }()); document.querySelector("#token-implementation-lib").innerHTML = '&lt;!-- Include Midtrans JS library --&gt; \n'+ document.querySelector("#midtrans-script") .outerHTML .replace(/</g, "&lt;") .replace(/>/g, "&gt;") .replace(/\\/g, ""); document.querySelector("#token-implementation").innerHTML = document.querySelector("#js-card-token") .innerHTML .replace(/</g, "&lt;") .replace(/>/g, "&gt;") .replace(/\\/g, ""); document.querySelector("#authentication-implementation").innerHTML = document.querySelector("#js-authentication") .innerHTML .replace(/</g, "&lt;") .replace(/>/g, "&gt;") .replace(/\\/g, ""); document.querySelector("#charge-form").onsubmit = function(e){ popupModal.openPopup('data:text/html,requesting...'); fetch("/charge\_core\_api\_ajax", { method : "POST", body: JSON.stringify({ "token\_id" : document.querySelector("#token\_id").value, "authenticate\_3ds" :
```

--------------------------------

### Perform Transaction Actions

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Execute various status checks and administrative actions on existing transactions.

```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')
```

```python
# get transaction status of VA b2b transaction
statusb2b_response = api_client.transactions.statusb2b('YOUR_ORDER_ID OR TRANSACTION_ID')
```

```python
# approve a credit card transaction with `challenge` fraud status
approve_response = api_client.transactions.approve('YOUR_ORDER_ID OR TRANSACTION_ID')
```

```python
# deny a credit card transaction with `challenge` fraud status
deny_response = api_client.transactions.deny('YOUR_ORDER_ID OR TRANSACTION_ID')
```

```python
# cancel a credit card transaction or pending transaction
cancel_response = api_client.transactions.cancel('YOUR_ORDER_ID OR TRANSACTION_ID')
```

```python
# expire a pending transaction
expire_response = api_client.transactions.expire('YOUR_ORDER_ID OR TRANSACTION_ID')
```

```python
# refund a transaction (not all payment channel allow refund via API)
param = {
    "refund_key": "order1-ref1",
    "amount": 5000,
    "reason": "Item out of stock"
}
refund_response = api_client.transactions.refund('YOUR_ORDER_ID OR TRANSACTION_ID',param)
```

```python
# refund a transaction (not all payment channel allow refund via API) with Direct Refund
param = {
    "refund_key": "order1-ref1",
    "amount": 5000,
    "reason": "Item out of stock"
}
refund_response = api_client.transactions.refundDirect('YOUR_ORDER_ID OR TRANSACTION_ID',param)
```

--------------------------------

### Handle Tokenization Callback and Charge Request

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_core_api_checkout.html

Processes the tokenization result and sends an AJAX request to the backend to initiate the charge.

```javascript
var getCardTokenCallback = { onSuccess: function(response){ // success to get card token // [2] Send AJAX to let backend charge the card using the card token_id // Check backend implementation on `web.py` file, section `[2]` fetch("/charge_core_api_ajax", { method : "POST", body: JSON.stringify({ "token_id" : response.token_id, "authenticate_3ds" : document.querySelector('.authenticate_3ds').checked }), headers: {'Content-Type': 'application/json'}, }) .then(function(response) { return response.json(); }) .then(function(responseObj) { console.log("Charge response:",responseObj); if (responseObj.status_code == "201"){ // [3.1] Transaction need 3DS authentication MidtransNew3ds.authenticate(responseObj.redirect_url, callback3dsAuthentication); } else { // Transaction do not need 3DS Authentication, transaction is complete with result transactionComplete(responseObj); } }) }, onFailure: function(response){ // fail to get card token transactionComplete(response); } }
```

--------------------------------

### Configure Custom HTTP Headers

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Set custom headers for API requests, including notification URL overrides.

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

# set custom HTTP header for every request from this instance
snap.api_config.custom_headers = {
    'my-custom-header':'my value',
    'x-override-notification':'https://example.org',
}
```

```python
# create instance of api client
snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)
# set custom HTTP header that will be used by Midtrans API to override notification url:
snap.api_config.custom_headers = {
    'x-override-notification':'https://example.org',
}
```

```python
snap.api_config.custom_headers = {
    'x-append-notification':'https://example.org',
}
```

--------------------------------

### Set Snap API Configuration via Attributes

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Modify the configuration of a Snap API client by directly setting attributes on the api_config object. This is an alternative to using the set method.

```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'
```

--------------------------------

### Configure Proxies for Midtrans API Client

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Configure HTTP and HTTPS proxies for the Midtrans API client. This is useful when operating in a network environment that requires a proxy. The underlying HTTP client is Requests.

```python
snap.api_config.proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
}
```

--------------------------------

### Popup Modal Helper

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_core_api_checkout.html

Utility functions for managing the 3D Secure iframe popup using the picoModal library.

```javascript
let popupModal = (function(){ let modal = null; return { openPopup(url){ modal = picoModal({ content:'<iframe frameborder="0" style="height:90vh; width:100%;" src="'+url+'"></iframe>', width: "75%", closeButton: false, overlayClose: false, escCloses: false }).show(); }, closePopup(){ try{ modal.close(); } catch(e) {} } } }());
```

--------------------------------

### Charge Credit Card via Core API

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Process credit card payments with 3DS authentication enabled. Requires a token generated from the frontend.

```python
import midtransclient

core_api = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

# Credit card token obtained from frontend (Midtrans.js)
param = {
    "payment_type": "credit_card",
    "transaction_details": {
        "gross_amount": 150000,
        "order_id": "order-cc-001"
    },
    "credit_card": {
        "token_id": "CREDIT_CARD_TOKEN_FROM_FRONTEND",
        "authentication": True  # Enable 3DS
    },
    "customer_details": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@email.com",
        "phone": "+62812345678"
    }
}

charge_response = core_api.charge(param)
print(f"Status: {charge_response['transaction_status']}")

# If 3DS authentication required, redirect user to:
if 'redirect_url' in charge_response:
    print(f"3DS Auth URL: {charge_response['redirect_url']}")
```

--------------------------------

### Charge Credit Card via Core API

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/core_api_credit_card_frontend_sample.html

Use this cURL request to process a credit card charge on your backend server after obtaining a token.

```bash
curl -X POST \
  https://api.sandbox.midtrans.com/v2/charge \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic < From your server_key >' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "order102-2-1562650595",
    "gross_amount": 100000
  },
  "credit_card": {
    "token_id": "< Token ID from Get Token Step >",
    "authentication": true
  }
}'
```

--------------------------------

### Handle 3D Secure Authentication

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_core_api_checkout.html

Manages the 3D Secure authentication flow by opening a popup modal and handling the authentication result.

```javascript
var callback3dsAuthentication = { performAuthentication: function(redirect_url){ // [3.2] 3ds authentication redirect_url received, open iframe to display to customer popupModal.openPopup(redirect_url); }, // [3.3] When 3DS authentication result received, which contains transaction result // it will trigger one of function below, according to status: success/failure/pending onSuccess: function(response){ transactionComplete(response); }, onFailure: function(response){ transactionComplete(response); }, onPending: function(response){ transactionComplete(response); } }
```

--------------------------------

### POST /v2/charge

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Triggers a charge request to the Core API for direct payment processing.

```APIDOC
## POST /v2/charge

### Description
Processes a payment charge directly via the Core API.

### Method
POST

### Request Body
- **payment_type** (string) - Required - The payment method (e.g., credit_card).
- **transaction_details** (object) - Required - Contains order_id and gross_amount.
- **credit_card** (object) - Optional - Contains token_id and authentication settings.
```

--------------------------------

### Handle Midtrans API Errors

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Demonstrates how to catch and handle specific Midtrans API errors, including message, HTTP status, and detailed API response. Also includes a general exception catch.

```python
import midtransclient
from midtransclient import MidtransAPIError

snap = midtransclient.Snap(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

param = {
    "transaction_details": {
        "order_id": "order-12345",
        "gross_amount": 200000
    }
}

try:
    transaction = snap.create_transaction(param)
    print(f"Token: {transaction['token']}")
except MidtransAPIError as e:
    print(f"Error Message: {e.message}")
    print(f"HTTP Status: {e.http_status_code}")
    print(f"API Response: {e.api_response_dict}")
    print(f"Raw Response: {e.raw_http_client_data}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Subscription API

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Manage recurring subscription payments for credit cards.

```APIDOC
## POST /subscriptions

### Description
Create a new recurring subscription.

## GET /subscriptions/{subscription_id}

### Description
Retrieve details of a specific subscription.

## PATCH /subscriptions/{subscription_id}

### Description
Update an existing subscription.

## POST /subscriptions/{subscription_id}/disable

### Description
Pause recurring charges for a subscription.

## POST /subscriptions/{subscription_id}/enable

### Description
Resume recurring charges for a subscription.
```

--------------------------------

### Transaction Status and Actions

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Endpoints for retrieving transaction status and performing administrative actions on existing transactions.

```APIDOC
## GET /transactions/{order_id}/status

### Description
Retrieve the status of a transaction that has already been recorded on Midtrans.

### Method
GET

### Endpoint
/transactions/{order_id}/status

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique order ID or transaction ID.

## POST /transactions/{order_id}/approve

### Description
Approve a credit card transaction that has a 'challenge' fraud status.

### Method
POST

### Endpoint
/transactions/{order_id}/approve

## POST /transactions/{order_id}/deny

### Description
Deny a credit card transaction that has a 'challenge' fraud status.

### Method
POST

### Endpoint
/transactions/{order_id}/deny

## POST /transactions/{order_id}/cancel

### Description
Cancel a credit card transaction or a pending transaction.

### Method
POST

### Endpoint
/transactions/{order_id}/cancel

## POST /transactions/{order_id}/expire

### Description
Expire a pending transaction.

### Method
POST

### Endpoint
/transactions/{order_id}/expire

## POST /transactions/{order_id}/refund

### Description
Refund a transaction. Note that not all payment channels allow refunds via API.

### Method
POST

### Endpoint
/transactions/{order_id}/refund

### Request Body
- **refund_key** (string) - Required - Unique key for the refund.
- **amount** (integer) - Required - Amount to be refunded.
- **reason** (string) - Required - Reason for the refund.
```

--------------------------------

### Handle Checkout Submission and Tokenization

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_core_api_checkout.html

Captures card details from the UI and requests a card token from Midtrans using the MidtransNew3ds library.

```javascript
document.querySelector(".submit-button").onclick = function (event) { console.log("SUBMIT button clicked"); // prepare cardData var cardData = { "card_number": document.querySelector(".card-number").value, "card_exp_month": document.querySelector(".card-expiry-month").value, "card_exp_year": document.querySelector(".card-expiry-year").value, "card_cvv": document.querySelector(".card-cvv").value, }; // [1] Use card data to get card token on the callback MidtransNew3ds.getCardToken(cardData, getCardTokenCallback); event.preventDefault(); return false; };
```

--------------------------------

### Core API Class Methods

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Defines the available methods for the CoreApi class to interact with various payment endpoints.

```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
    """

```

--------------------------------

### Refund Transaction

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Initiate a refund for a transaction. Requires the order ID and a dictionary containing refund details like amount and reason.

```python
refund_param = {
    "refund_key": "order-12345-ref1",
    "amount": 25000,
    "reason": "Customer request"
}
refund_response = api_client.transactions.refund(order_id, refund_param)
```

--------------------------------

### POST /snap/v1/transactions

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Creates a transaction via Snap API to obtain a redirect URL for the payment page.

```APIDOC
## POST /snap/v1/transactions

### Description
Creates a transaction and returns a redirect URL for the payment page.

### Method
POST

### Request Body
- **transaction_details** (object) - Required - Contains order_id and gross_amount.
- **credit_card** (object) - Optional - Configuration for credit card payments.

### Response
#### Success Response (200)
- **redirect_url** (string) - The URL to redirect the user for payment.
```

--------------------------------

### Charge Bank Transfer via Core API

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Process direct bank transfer payments using the Core API. Requires specifying the bank code in the parameters.

```python
import midtransclient

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

# Prepare bank transfer payment parameters
param = {
    "payment_type": "bank_transfer",
    "transaction_details": {
        "gross_amount": 50000,
        "order_id": "order-bt-001"
    },
    "bank_transfer": {
        "bank": "bni"  # Options: bni, bca, bri, permata
    },
    "customer_details": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@email.com"
    }
}

# Charge transaction
charge_response = core_api.charge(param)
print(f"Transaction ID: {charge_response['transaction_id']}")
print(f"Status: {charge_response['transaction_status']}")
print(f"VA Numbers: {charge_response['va_numbers']}")

# Sample response:
# {
#     'transaction_id': '6ee793df-9b1d-4343-8eda-cc9663b4222f',
#     'order_id': 'order-bt-001',
#     'payment_type': 'bank_transfer',
#     'transaction_status': 'pending',
#     'fraud_status': 'accept',
#     'va_numbers': [{'bank': 'bni', 'va_number': '9888012345678901'}]
# }
```

--------------------------------

### Handle API Exceptions

Source: https://github.com/midtrans/midtrans-python-client/blob/master/README.md

Catch and inspect MidtransAPIError objects when API calls fail.

```python
err = None
try:
    transaction = snap.create_transaction(param)
except Exception as e:
    err = e
err.message
err.api_response_dict
err.http_status_code
err.raw_http_client_data
```

--------------------------------

### Disable Subscription

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Pause recurring charges for a subscription. This action requires the subscription ID.

```python
core_api.disable_subscription(subscription_id)
```

--------------------------------

### Approve Challenged Transaction

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Approve a transaction that has been flagged for challenge. Requires the order ID.

```python
approve_response = api_client.transactions.approve(order_id)
```

--------------------------------

### POST /transactions/notification

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Handle webhook notifications from Midtrans to update transaction status.

```APIDOC
## POST /transactions/notification

### Description
Verify and process incoming webhook notifications from Midtrans to synchronize transaction status.

### Request Body
- **transaction_id** (string) - Required - Unique transaction ID
- **order_id** (string) - Required - Merchant order ID
- **transaction_status** (string) - Required - Status of the transaction
- **fraud_status** (string) - Optional - Fraud status
- **payment_type** (string) - Required - Payment method used
- **gross_amount** (string) - Required - Total amount
```

--------------------------------

### Direct Refund Transaction

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Perform a direct refund for a transaction, supported by specific payment channels. Requires the order ID and refund parameters.

```python
direct_refund = api_client.transactions.refundDirect(order_id, refund_param)
```

--------------------------------

### Deny Challenged Transaction

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Deny a transaction that has been flagged for challenge. Requires the order ID.

```python
deny_response = api_client.transactions.deny(order_id)
```

--------------------------------

### Complete Transaction and Verify Status

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_core_api_checkout.html

Finalizes the transaction UI and triggers a backend verification call to update the database status.

```javascript
function transactionComplete(responseObj){ // Close 3DS popup, then display the result (for example) console.log("transactionComplete with status: ",responseObj); popupModal.closePopup(); document.querySelector("#result").innerText = JSON.stringify(responseObj, null, 2); document.querySelector("#result").scrollIntoView(); if (responseObj.transaction_id){ // [4] Inform the result to backend update DB status and verify to Midtrans // Check backend implementation on `web.py` file, section `[4]` fetch('/check_transaction_status', { method : "POST", body: JSON.stringify({ "transaction_id" : responseObj.transaction_id }), headers: {'Content-Type': 'application/json'}, }) .then(function(statusResponse) { return statusResponse.json(); } ) .then(function(statusResponseObj) { // Transaction status received after being verified console.log("Check transaction response:",statusResponseObj); // transactionComplete(statusResponseObj); document.querySelector("#status-result").innerText = JSON.stringify(statusResponseObj, null, 2); }) } }
```

--------------------------------

### Handle 3DS Authentication Response

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/core_api_credit_card_frontend_sample.html

This JavaScript snippet handles the response from a 3D Secure authentication. It updates input fields with the redirect URL or displays the status code and result in a modal. Use this when processing payments that require 3D Secure verification.

```javascript
document.querySelector('#authenticate_3ds').checked }), headers: {'Content-Type': 'application/json'}, })
.then(function(response) { return response.json(); })
.then(function(responseObj){ if(responseObj.redirect_url){ document.querySelector("#redirect_url").value = responseObj.redirect_url; document.querySelector("#redirect_url_result").value = responseObj.redirect_url; } else if (responseObj.status_code){ document.querySelector("#result").innerText = JSON.stringify(responseObj,null,2); popupModal.closePopup(); document.querySelector("#result").scrollIntoView(); } })
.catch(function(err){ alert(`Fail to get charge response: ${JSON.stringify(err)}`); console.log(`Fail to get charge response: ${JSON.stringify(err)}`) })
.finally(function(){ popupModal.closePopup(); })
return e.preventDefault() && 0; // prevent form submit
```

--------------------------------

### Transaction Management API

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Endpoints for managing the lifecycle of a transaction including status checks, approvals, cancellations, and refunds.

```APIDOC
## GET /transactions/{order_id}/status

### Description
Get the status of a B2B transaction.

### Method
GET

### Endpoint
/transactions/{order_id}/status

## POST /transactions/{order_id}/approve

### Description
Approve a challenged transaction.

### Method
POST

## POST /transactions/{order_id}/deny

### Description
Deny a challenged transaction.

### Method
POST

## POST /transactions/{order_id}/cancel

### Description
Cancel a pending or authorized transaction.

### Method
POST

## POST /transactions/{order_id}/expire

### Description
Expire a pending transaction.

### Method
POST

## POST /transactions/{order_id}/refund

### Description
Refund a transaction.

### Request Body
- **refund_key** (string) - Required - Unique key for the refund
- **amount** (integer) - Required - Refund amount
- **reason** (string) - Required - Reason for the refund
```

--------------------------------

### Handle Midtrans Webhook Notifications

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Process incoming webhook notifications from Midtrans to update transaction statuses. This involves verifying the notification and handling different transaction states.

```python
import midtransclient

api_client = midtransclient.CoreApi(
    is_production=False,
    server_key='YOUR_SERVER_KEY',
    client_key='YOUR_CLIENT_KEY'
)

# Notification JSON received from Midtrans webhook
notification_json = {
    'transaction_id': '6ee793df-9b1d-4343-8eda-cc9663b4222f',
    'order_id': 'order-12345',
    'transaction_status': 'capture',
    'fraud_status': 'accept',
    'payment_type': 'credit_card',
    'gross_amount': '150000.00'
}

# Verify and get transaction status (auto-verifies notification authenticity)
status_response = api_client.transactions.notification(notification_json)

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

# Handle transaction status
if transaction_status == 'capture':
    if fraud_status == 'accept':
        # Payment successful - update database to 'success'
        print(f"Payment successful for order {order_id}")
    elif fraud_status == 'challenge':
        # Payment challenged - update database to 'challenge'
        print(f"Payment challenged for order {order_id}")
elif transaction_status == 'settlement':
    # Payment settled - update database to 'success'
    print(f"Payment settled for order {order_id}")
elif transaction_status in ['cancel', 'deny', 'expire']:
    # Payment failed - update database to 'failure'
    print(f"Payment failed for order {order_id}")
elif transaction_status == 'pending':
    # Awaiting payment - update database to 'pending'
    print(f"Payment pending for order {order_id}")
```

--------------------------------

### JavaScript Snap Checkout Integration

Source: https://github.com/midtrans/midtrans-python-client/blob/master/examples/flask_app/templates/simple_checkout.html

Use this JavaScript code to open the Midtrans Snap payment popup. Ensure you have the Snap token and a checkout button element. The callbacks handle different payment outcomes.

```javascript
var token = document.querySelectorAll('#snap_token')[0].value;
var checkoutBtn = document.querySelectorAll('.checkout')[0];
checkoutBtn.onclick = function(){
    console.log('opening snap popup:');
    // Open Snap popup with defined callbacks.
    snap.pay(token, {
        onSuccess: function(result) {
            console.log("SUCCESS", result);
            alert("Payment accepted \r\n"+JSON.stringify(result));
        },
        onPending: function(result) {
            console.log("Payment pending", result);
            alert("Payment pending \r\n"+JSON.stringify(result));
        },
        onError: function() {
            console.log("Payment error");
        }
    });
    // For more advanced use, refer to: https://snap-docs.midtrans.com/#snap-js
}
```

--------------------------------

### Update Subscription

Source: https://context7.com/midtrans/midtrans-python-client/llms.txt

Modify an existing subscription's parameters such as name, amount, or schedule. Requires the subscription ID and updated parameters.

```python
update_param = {
    "name": "PREMIUM-MONTHLY-UPDATED",
    "amount": "150000",
    "currency": "IDR",
    "token": "SAVED_TOKEN_ID",
    "schedule": {
        "interval": 1
    }
}
core_api.update_subscription(subscription_id, update_param)
```