Python SDK – BoxPay

Overview

The BoxPay provides a Python Server SDK for interacting with the BoxPay Checkout APIs. It simplifies the process of integrating BoxPay payments into your application, allowing you to:

Create checkout sessions to initiate payment flows
Verify the status of payment transactions
Handle errors gracefully to provide a robust user experience

Pre-requisites

Before you start using the BoxPay Checkout SDK, you’ll need the following:

Python: The SDK is written in Python, so you’ll need a Python environment set up (version 3.7 or later is recommended). You can download Python from the official website (https://www.python.org/).
BoxPay Merchant Account: You will need an active BoxPay merchant account to obtain an API key and Merchant ID. You can sign up for an account on the BoxPay website.
API Key and Merchant ID: Obtain your API credentials from within your BoxPay merchant dashboard.

Installation

You can install the BoxPay Checkout SDK using pip

pip install boxpay-checkout-sdk

Initialisation

Obtain your BoxPay API key and Merchant ID from your BoxPay merchant dashboard.
Instantiate a BoxpayClient object, supplying your API key and Merchant ID

from boxpay_checkout_sdk.boxpay_client import BoxpayClient

api_key = "your_boxpay_api_key"
merchant_id = "your_merchant_id"

client = BoxpayClient(api_key, env)
checkout_client = CheckoutClient(client)

Creating a checkout session

Construct a CheckoutSessionRequest object, populating it with the necessary checkout information (see “Data Models” section below for details).
Call the create_checkout_session method of your CheckoutClient instance:

checkout_session_request = CheckoutSessionRequest(
    context=context_data,
    paymentType="S" or "A",
    shopper=shopper_data,
    order=order_data,
    frontendReturnUrl="your website url",
    frontendBackUrl="your website url",
    statusNotifyUrl="your website url",
    money=money_data,
    descriptor=descriptor_data,
    billingAddress=billing_address_data,
    metadata={},
    shopperAuthentication=shopper_authentication_data
)
checkout_session_response = checkout_client.create_checkout_session(checkout_session_request)
if checkout_session_response.url:
    # Redirect the user to the checkout URL
    print(f"Checkout URL: {checkout_session_response.url}")
else:
        print("Checkout session failed to initiate. Please try again or contact support.")

    # Example of accessing additional error info (if available)
    if checkout_session_response.status_code == 400:  # Example - Invalid request
        error_details = checkout_session_response.fieldErrorItems

Verifying a payment

Obtain the payment token from your checkout process.
Construct a TransactionInquiryDetails object with the token.
Call the verify_payment method of your CheckoutClient:

token = "payment_token_obtained_from_checkout"
inquiry_details = TransactionInquiryDetails(token=token)
inquiry_response = client.verify_payment(token, inquiry_details)

Error Types

The SDK defines custom exception classes for different error types:

APIError: General API errors
AuthenticationError: Authentication failures
InvalidParameterError: Incorrect data provided
ResourceNotFoundError: Resource (e.g., transaction) not found
TimeoutError: Timeout when communicating with the API
PaymentDeclinedError: Payment declined by the issuer

Implement error handling logic using try…except blocks to address these exceptions appropriately.

Checkout Integration