nox-py-sdk 0.1.0

An SDK made with Python to interact with the Checkout API and V2 API in a simple and efficient way.

Nox SDK

An SDK made with Python to interact with the Checkout API and V2 API in a simple and efficient way.

Installing

pip install nox-py-sdk

Checkout API

Setup

To use the SDK, you will need an API token generated by the Nox system.

from nox_py_sdk import CheckoutAPI

token = 'your_api_token'

checkout_api = CheckoutAPI(token)

Using Checkout API methods

Listing Checkouts

Gets a list of checkouts based on the given query parameters.

get_checkouts(query_params: Optional[Dict[str, Any]] = None) -> GetCheckoutsResponse

Usage Example:

response = checkout_api.get_checkouts({
    'page': 1,
    'created_at_start': '2024-04-08',
    'created_at_end': '2024-05-08'
})
print(response.checkouts)

Response:

{
    "checkouts": [
        {
            "id": 1,
            "image": "base64image",
            "image_type": "image/png",
            "description": "Teste",
            "price": "50.00",
            "redirect_url": "https://example.com",
            "is_enabled": true,
            "theme_color": "custom",
            "payment_method": "all",
            "colors": {
                "primary": "#F2F2F2",
                "secondary": "#FFFFFF",
                "text": "#334155",
                "button": "#3F438C",
                "textButton": "#FFFFFF"
            },
            "created_at": "2024-06-13T18:41:20.329Z",
            "url_id": "f25f51c9-0a90-41c9-9571-035813ae0000"
        }
    ],
    "current_page": 1,
    "total_pages": 1
}

Retrieving Checkout

Retrieves a checkout using its url_id identifier.

get_checkout(url_id: str) -> CheckoutDetail

Usage Example:

checkout = checkout_api.get_checkout('123')
print(checkout)

Response:

{
    "image": "base64image",
    "description": "Produto teste",
    "price": "10.00",
    "redirect_url": "https://example.com",
    "is_enabled": true,
    "payment_method": "all",
    "url_id": "0989d6cc-b02c-493b-b953-dab39dbc1111",
    "colors": {
        "primary": "#F2F2F2",
        "secondary": "#FFFFFF",
        "text": "#334155",
        "button": "#3F438C",
        "textButton": "#FFFFFF"
    },
    "code": "string",
    "txid": "string"
}

Creating Checkout

Create a new checkout with the provided data. create_checkout(data: CreateCheckoutData, file: Optional[IO] = None) -> CreateCheckoutResponse

Usage Example:

data = {
    'colors': {
        'primary': '#000000',
        'secondary': '#FFFFFF',
        'text': '#333333',
        'button': '#FF0000',
        'textButton': '#FFFFFF'
    },
    'price': 1000,
    'description': 'Produto teste',
    'redirect_url': 'https://example.com',
    'payment_method': 'credit_card',
    'is_enabled': True,
    'theme_color': '#FF00FF'
}

response = checkout_api.create_checkout(data, file)
print(response)

Response:

{
    "id": 1,
    "url_id": "87ff1499-dab3-44e6-9538-3cbb05b66666"
}

Updating Checkout

Updates data from an existing checkout.

update_checkout(id: int, data: UpdateCheckoutData, file: Optional[IO] = None) -> UpdateCheckoutResponse

Usage Example:

update_data = {
    'price': 1200,
    'change_image': False
}

response = checkout_api.update_checkout(123, update_data, new_file)
print(response.detail)

Response:

{
    "detail": "Checkout updated successfully."
}

Error Handling

In case of errors, the methods will throw an exception with a detailed message

try:
    checkout = checkout_api.get_checkout('123')
except Exception as e:
    print(e)

V2 API

Setup

To use the SDK, you will need an API token and a merchant resgistration. To achieve them, you must get in contact with Nox, so we can provide them to you.

from nox_py_sdk import V2API

token = 'your_api_token'

v2_api = V2API(token)

Using V2 API methods

Get Account.

Retrieves the account information associated with the API token. get_account() -> Account

Usage Example:

account = v2_api.get_account()
print(account)

Response:

{
    "name": "John Doe",
    "balance": 1500.50
}

Create Payment Method

Creates a new payment using the specified method and details. create_payment(data: CreatePaymentData) -> CreatePaymentResponse

Usage Example:

payment_response = v2_api.create_payment({
    'method': 'PIX',
    'code': '123456',
    'amount': 1000
})
print(payment_response)

Response:

{
    "method": "PIX",
    "code": "123456",
    "amount": 1000,
    "qrcode": "https://api.example.com/qrcode",
    "qrcodebase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "copypaste": "1234567890",
    "txid": "abc123",
    "Status": "WAITING_PAYMENT"
}

Create Cash-out Payment

Creates a new cash-out payment. create_payment_cash_out(data: CreatePaymentData) -> Payment

Usage Example:

payment_response = v2_api.create_payment({
    'method': 'PIX',
    'code': '123456',
    'amount': 1000,
    'type': 'PIX_KEY',
    'pixkey': 'your-pix-key',
})
print(payment_response)

Response:

{
    "Method": "PIXOUT",
    "Status": "SENT",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
}

Retrieve Payment's Info

Fetches the details of a specific payment by its code or tx_id. get_payment(identifier: str) -> Payment

Usage Example:

payment = v2_api.get_payment('payment-identifier')
print(payment)

Response:

{
    "Method": "PIX",
    "Status": "PAID",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
    "end2end": "e2e123",
    "receipt": "https://api.example.com/receipt"
}

Resend Webhook

Resends the webhook for a specific transaction. resend_webhook(txid: str) -> None

Usage Example:

v2_api.resend_webhook('txid')

Send Transactions Report

Generates and sends a transaction report based on the specified filters to merchant email associated with the token in csv format. send_transactions_report(filters: TransactionsRequestFilters) -> None

Usage Example:

v2_api.send_transactions_report({
    'begin_date': '2024-01-01',
    'end_date': '2024-01-31',
    'method': 'PIX',
    'status': 'PAID'
})

Create Credit Card Payment

Creates a new payment using a credit card. create_credit_card_payment(data: CreateCreditCardPaymentData) -> CreditCardPaymentResponse

Usage Example:

credit_card_payment_response = v2_api.create_credit_card_payment({
    'amount': 1000,
    'email': '[e-mail]',
    'code': '123456',
    'name': 'User Name',
    'cpf_cnpj': '12345678900',
    'expired_url': 'https://example.com/expired',
    'return_url': 'https://example.com/return',
    'max_installments_value': 200,
    'soft_descriptor_light': 'COMPANY NAME'
})
print(credit_card_payment_response)

Response:

{
    "id": "cc123",
    "due_date": "2024-12-31",
    "currency": "BRL",
    "email": "[e-mail]",
    "status": "pending",
    "total_cents": 1000,
    "order_id": "order123",
    "secure_id": "secure123",
    "secure_url": "https://api.example.com/secure",
    "total": "10.00",
    "created_at_iso": "2024-09-01T12:34:56Z"
}

Retrieve Credit Card Payment

Retrieves details of a specific credit card payment by its identifier. get_credit_card_payment(identifier: str) -> CreditCardPayment

Usage Example:

payment = v2_api.get_credit_card_payment('credit-card-identifier')
print(payment)

Response:

{
    "id": 123,
    "status": "PAID",
    "code": "cc123",
    "txid": "tx123",
    "amount": 1000,
    "created_at": "2024-09-01T12:34:56Z",
    "paid_at": "2024-09-01T13:00:00Z",
    "canceled_at": null,
    "customer_name": "John Doe",
    "customer_email": "[e-mail]",
    "customer_document": "123.456.789-00",
    "merchant_id": 456,
    "id_from_bank": "bank123"
}

Error Handling

In case of errors, the methods will throw an exception with a detailed message

try:
    checkout = v2_api.get_credit_card_payment('identifier')
except Exception as e:
    print(e)