»
Getting Started Templates
Getting Started Templates
Overview
The Payment Module in the Exsited SDK provides a robust set of tools to handle payment-related operations within your application. It allows developers to streamline payment processing, apply payments to invoices, and retrieve detailed payment histories for auditing or reconciliation purposes. Designed for versatility, this module supports a wide range of payment processors and ensures accurate financial tracking.
Common Import Requirements
The following imports are required when working with any payment-related functions in both Python and PHP.
Python
PHP
from exsited.exsited.exsited_sdk import ExsitedSDK
from exsited.common.ab_exception import ABException
from exsited.common.sdk_conf import SDKConfig
from config import CommonDatause Api\Component\ApiConfig;
use Api\AppService\Payment\PaymentData;
use Api\ApiHelper\Config\ConfigManager;Function: createBasicPayment
Purpose
The createBasicPayment() function creates a payment for a specified invoice by submitting payment details, including the payment processor, amount, and reference. It also includes additional details such as the payment date and associated notes. The function validates the creation of the payment and returns the payment details upon success.
Parameters
| Parameter | Type | Description |
|---|---|---|
| invoice_id | String | The unique identifier for the invoice associated with the payment. |
| date | String (Date) | The date when the payment was made (format: YYYY-MM-DD). |
| note | String | A note or description related to the payment. |
| processor | String | The processor or method of payment (e.g., "Cash", "Credit"). |
| amount | String (Decimal) | The amount of money applied in the payment (e.g., "20.00"). |
| reference | String | A reference or identifier for the payment transaction. |
Use Case
This function is used to process payments and apply them to invoices. It is useful when creating payments for outstanding invoices in the system, ensuring the correct amount is applied and reconciling the payment with the invoice.
Python
PHP
def test_payment_create_basic():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = False
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
payment_applied = PaymentAppliedDTO(processor="PROCESSOR", amount="AMOUNT", reference="REFERENCE")
payment_data = PaymentDataDTO(date="PAYMENT_DATE", paymentApplied=[payment_applied], note="PAYMENT_NOTE")
request_data = PaymentCreateDTO(payment=payment_data)
response = exsited_sdk.payment.create(invoice_id="INVOICE_ID", request_data=request_data)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function testCreateSinglePayment()
{
$invoiceId = "INVOICE_ID";
$params = [
"payment" => [
"date" => "PAYMENT_DATE",
"note" => "PAYMENT_NOTE",
"payment_applied" => [
[
"processor" => "PROCESSOR",
"amount" => "AMOUNT",
"reference" => "REFERENCE"
]
]
]
];
try {
$response = $this->paymentService->createSinglePayment($invoiceId, $params);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The response contains the details of the created payment, including the payment status, ID, applied amount, payment processor, reference, and invoice details. It also includes reconciliation status, total applied, and timestamps for creation and updates. The response can be used to verify the successful application of the payment to the specified invoice.
Python
PHP
ItemResponseDTO(
item=ItemDataDTO(
status='STATUS',
id='ITEM_ID',
name='ITEM_NAME',
displayName='DISPLAY_NAME',
description='DESCRIPTION',
type='TYPE',
baseUom='BASE_UOM',
parentItemId=None,
origin='ORIGIN',
createdBy='CREATED_BY',
createdOn='CREATED_ON',
lastUpdatedBy='LAST_UPDATED_BY',
lastUpdatedOn='LAST_UPDATED_ON',
uuid='UUID',
version='VERSION',
imageUri='IMAGE_URI',
group=None,
manager=None,
customForm=CustomFormDTO(
name='CUSTOM_FORM_NAME',
uuid='CUSTOM_FORM_UUID'
),
customAttributes=[],
customObjects=[],
codes=[
CodesDTO(name='CODE_NAME_1', value='CODE_VALUE_1'),
CodesDTO(name='CODE_NAME_2', value='CODE_VALUE_2')
],
uoms=[],
currencies=[
CurrenciesDTO(
name='CURRENCY_NAME_1',
usedForSale='USED_FOR_SALE',
defaultForSale='DEFAULT_FOR_SALE',
usedForPurchase='USED_FOR_PURCHASE',
defaultForPurchase='DEFAULT_FOR_PURCHASE'
),
CurrenciesDTO(
name='CURRENCY_NAME_2',
usedForSale='USED_FOR_SALE',
defaultForSale='DEFAULT_FOR_SALE',
usedForPurchase='USED_FOR_PURCHASE',
defaultForPurchase='DEFAULT_FOR_PURCHASE'
)
],
sale=SaleDTO(
enabled='SALE_ENABLED',
invoiceNote='INVOICE_NOTE',
accountingCode=AccountingCodeDTO(salesRevenue=None),
defaultSalePrice='DEFAULT_SALE_PRICE',
shippingProfile='SHIPPING_PROFILE',
taxExemptWhenSold='TAX_EXEMPT_WHEN_SOLD',
pricingMethod='PRICING_METHOD',
taxConfiguration=SaleTaxConfigurationDTO(
salePriceEnteredIsInclusiveOfTax='TAX_INCLUDED',
salePriceIsBasedOn=None,
taxCode=None
),
pricingProfile=None,
pricingSchedules=None,
pricingLevels=[],
charge=SaleChargeDTO(
type='CHARGE_TYPE',
pricePeriod=None,
properties=[
SaleChargePropertiesDTO(name='PROPERTY_NAME_1', value='PROPERTY_VALUE_1'),
SaleChargePropertiesDTO(name='PROPERTY_NAME_2', value='PROPERTY_VALUE_2')
]
),
paymentProperties=[
SaleChargePropertiesDTO(name='PROPERTY_NAME_1', value='PROPERTY_VALUE_1'),
SaleChargePropertiesDTO(name='PROPERTY_NAME_2', value='PROPERTY_VALUE_2')
],
discountProfile={},
pricing=PricingDTO(
type='PRICING_TYPE',
version='VERSION',
latestUsedPricingVersion='LATEST_PRICING_VERSION',
pricingModule=[]
),
width=None,
height=None,
length=None,
weight=None,
useOnSalePrice=None,
salePriceVariant=None,
salePrice=None,
startDate=None,
endDate=None
),
purchase=PurchaseDTO(
enabled='PURCHASE_ENABLED',
enableSupplierManagement='SUPPLIER_MANAGEMENT_ENABLED',
accountingCode=AccountingCodeDTO(salesRevenue=None),
purchaseOrderNote='PURCHASE_NOTE',
defaultPurchasePrice='DEFAULT_PURCHASE_PRICE',
taxExemptWhenPurchase='TAX_EXEMPT_WHEN_PURCHASED',
taxConfiguration=PurchaseTaxConfigurationDTO(
purchasePriceEnteredIsInclusiveOfTax='TAX_INCLUDED'
),
pricingProfile=None,
purchaseProperties=[
PurchasePropertiesDTO(name='PROPERTY_NAME_1', value='PROPERTY_VALUE_1'),
PurchasePropertiesDTO(name='PROPERTY_NAME_2', value='PROPERTY_VALUE_2')
],
pricing=PricingDTO(
type='PRICING_TYPE',
version='VERSION',
latestUsedPricingVersion='LATEST_PRICING_VERSION',
pricingModule=[]
),
suppliers=None
),
inventories=InventoriesDTO(
isEnabled='INVENTORY_ENABLED',
preorderPeriod=None,
warehouseIsEnabled='WAREHOUSE_ENABLED',
warehouses=[
InventoryWarehouseDTO(
name='WAREHOUSE_NAME',
uuid='WAREHOUSE_UUID',
link='WAREHOUSE_LINK',
quantityOnHand='QUANTITY_ON_HAND',
quantityOnHandValue='QUANTITY_ON_HAND_VALUE',
quantityPromised='QUANTITY_PROMISED',
quantityOnOrder='QUANTITY_ON_ORDER',
quantityOnReturn='QUANTITY_ON_RETURN',
quantityOnPurchaseReturn='QUANTITY_ON_PURCHASE_RETURN',
quantityAvailable='QUANTITY_AVAILABLE',
quantityAvailableValue='QUANTITY_AVAILABLE_VALUE',
uom='UOM'
)
],
inventoryProperties=InventoryPropertiesDTO(
quantityAvailableForSaleDetermination=['DETERMINATION_METHOD'],
quantityAvailableForSale='QUANTITY_AVAILABLE_FOR_SALE',
enableLowStockNotification='ENABLE_LOW_STOCK_NOTIFICATION',
lowStockThresholdIsBasedOn='LOW_STOCK_THRESHOLD',
enableReordering='ENABLE_REORDERING',
reorderingThresholdIsBasedOn='REORDERING_THRESHOLD'
)
),
kpis=KpisDTO(
totalRevenue='TOTAL_REVENUE',
totalCollected='TOTAL_COLLECTED',
totalOutstanding='TOTAL_OUTSTANDING',
totalOverdue='TOTAL_OVERDUE'
)
)
){
"item": {
"status": "STATUS",
"id": "ITEM_ID",
"name": "ITEM_NAME",
"display_name": "DISPLAY_NAME",
"description": "DESCRIPTION",
"type": "ITEM_TYPE",
"base_uom": "BASE_UOM",
"origin": "ORIGIN",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "UUID",
"version": "VERSION",
"image_uri": "IMAGE_URI",
"custom_form": {
"name": "CUSTOM_FORM_NAME",
"uuid": "CUSTOM_FORM_UUID"
},
"custom_attributes": [],
"custom_objects": [],
"codes": [
{
"name": "CODE_NAME_1",
"value": "CODE_VALUE_1"
},
{
"name": "CODE_NAME_2",
"value": "CODE_VALUE_2"
}
],
"uoms": [],
"currencies": [
{
"name": "CURRENCY_NAME",
"isUsedForSale": "IS_USED_FOR_SALE",
"isDefaultForSale": "IS_DEFAULT_FOR_SALE",
"isUsedForPurchase": "IS_USED_FOR_PURCHASE",
"isDefaultForPurchase": "IS_DEFAULT_FOR_PURCHASE"
}
],
"sale": {
"isEnabled": "SALE_ENABLED",
"invoice_note": "INVOICE_NOTE",
"accounting_code": [],
"default_sale_price": "DEFAULT_SALE_PRICE",
"shipping_profile": "SHIPPING_PROFILE",
"isTaxExemptWhenSold": "IS_TAX_EXEMPT_WHEN_SOLD",
"pricing_method": "PRICING_METHOD",
"tax_configuration": {
"sale_price_entered_is_inclusive_of_tax": "SALE_PRICE_INCLUSIVE_TAX"
},
"pricing_levels": [],
"charge": {
"type": "CHARGE_TYPE",
"properties": [
{
"name": "PROPERTY_NAME_1",
"value": "PROPERTY_VALUE_1"
},
{
"name": "PROPERTY_NAME_2",
"value": "PROPERTY_VALUE_2"
}
]
},
"payment_properties": [
{
"name": "PROPERTY_NAME_1",
"value": "PROPERTY_VALUE_1"
},
{
"name": "PROPERTY_NAME_2",
"value": "PROPERTY_VALUE_2"
},
{
"name": "PROPERTY_NAME_3",
"value": "PROPERTY_VALUE_3"
},
{
"name": "PROPERTY_NAME_4",
"value": "PROPERTY_VALUE_4"
}
],
"discount_profile": [],
"pricing": {
"type": "PRICING_TYPE",
"version": "VERSION",
"latest_used_pricing_version": "LATEST_USED_PRICING_VERSION",
"pricing_module": []
},
"use_on_sale_price": "USE_ON_SALE_PRICE",
"sale_price_variant": "SALE_PRICE_VARIANT",
"sale_price": "SALE_PRICE",
"start_date": "START_DATE",
"end_date": "END_DATE"
},
"purchase": {
"isEnabled": "PURCHASE_ENABLED",
"supplier_management_isEnabled": "SUPPLIER_MANAGEMENT_ENABLED",
"purchase_properties": [
{
"name": "PROPERTY_NAME_1",
"value": "PROPERTY_VALUE_1"
},
{
"name": "PROPERTY_NAME_2",
"value": "PROPERTY_VALUE_2"
}
]
},
"inventories": {
"isEnabled": "INVENTORIES_ENABLED",
"warehouse_isEnabled": "WAREHOUSE_ENABLED",
"warehouses": [
{
"name": "WAREHOUSE_NAME",
"uuid": "WAREHOUSE_UUID",
"link": "WAREHOUSE_LINK",
"quantity_on_hand": "QUANTITY_ON_HAND",
"quantity_promised": "QUANTITY_PROMISED",
"quantity_on_order": "QUANTITY_ON_ORDER",
"quantity_on_return": "QUANTITY_ON_RETURN",
"quantity_on_purchase_return": "QUANTITY_ON_PURCHASE_RETURN",
"quantity_available": "QUANTITY_AVAILABLE",
"uom": "UOM"
}
],
"inventory_properties": {
"quantity_available_for_sale_determination": [
"DETERMINATION_METHOD"
],
"quantity_available_for_sale": "QUANTITY_AVAILABLE_FOR_SALE",
"enable_low_stock_notification": "LOW_STOCK_NOTIFICATION_ENABLED",
"low_stock_threshold_is_based_on": "LOW_STOCK_THRESHOLD",
"enable_reordering": "ENABLE_REORDERING",
"reordering_threshold_is_based_on": "REORDERING_THRESHOLD"
}
}
}
}Function: readInvoicePaymentDetails
Purpose
The readInvoicePaymentDetails() function retrieves detailed payment information for a specified invoice. This function is useful for reviewing payment transactions, reconciling records, and ensuring the correct application of payments to the invoice.
Parameters
| Parameter | Type | Description |
|---|---|---|
id
|
String | The unique identifier of the invoice for which payment details are being retrieved. |
Use Case
This function is used when detailed payment information is required for auditing, customer queries, or verifying payment records against a specific invoice. For example, it can be applied in financial systems to review applied payments and their statuses.
Python
PHP
def read_invoice_payment_details():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
try:
response = exsited_sdk.payment.invoice_details(id='INVOICE_ID')
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)public function readInvoicePaymentDetails()
{
$invoiceId = 'INVOICE_ID';
try {
$response = $this->paymentService->readInvoicePaymentDetails($invoiceId);
echo '<pre>' . json_encode($response, JSON_PRETTY_PRINT) . '</pre>';
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage();
}
}Response
The function returns detailed information about the payments associated with the specified invoice. This includes the unique payment ID, the amount applied to the invoice, the payment processor used (e.g., card or direct debit), a reference for the transaction, and the current status of the payment, such as successful, pending, or failed.
Python
PHP
PaymentInvoiceResponseDTO(
invoice=PaymentListDTO(
payments=[
PaymentDataDTO(
id='PAYMENT_ID_1',
date='PAYMENT_DATE_1',
status='PAYMENT_STATUS_1',
reconcileStatus='RECONCILE_STATUS_1',
totalApplied='TOTAL_APPLIED_1',
paymentApplied=[
PaymentAppliedDTO(
processor='PROCESSOR_1',
amount=AMOUNT_1,
reference='REFERENCE_1',
method='METHOD_1'
)
],
note='NOTE_1',
creditApplied=[],
invoices=[
InvoiceDTO(
applied='APPLIED_AMOUNT_1',
code='INVOICE_CODE_1',
dueDate='DUE_DATE_1',
issueDate='ISSUE_DATE_1',
outstanding='OUTSTANDING_AMOUNT_1',
total='TOTAL_AMOUNT_1'
)
],
createdBy='CREATED_BY_1',
createdOn='CREATED_ON_1',
lastUpdatedBy='LAST_UPDATED_BY_1',
lastUpdatedOn='LAST_UPDATED_ON_1',
uuid='UUID_1',
version='VERSION_1',
customAttributes=[],
customObjects=[],
giftCertificateApplied=[]
),
PaymentDataDTO(
id='PAYMENT_ID_2',
date='PAYMENT_DATE_2',
status='PAYMENT_STATUS_2',
reconcileStatus='RECONCILE_STATUS_2',
totalApplied='TOTAL_APPLIED_2',
paymentApplied=[
PaymentAppliedDTO(
processor='PROCESSOR_2',
amount=AMOUNT_2,
reference='REFERENCE_2',
method='METHOD_2'
)
],
note='NOTE_2',
creditApplied=[],
invoices=[
InvoiceDTO(
applied='APPLIED_AMOUNT_2',
code='INVOICE_CODE_2',
dueDate='DUE_DATE_2',
issueDate='ISSUE_DATE_2',
outstanding='OUTSTANDING_AMOUNT_2',
total='TOTAL_AMOUNT_2'
)
],
createdBy='CREATED_BY_2',
createdOn='CREATED_ON_2',
lastUpdatedBy='LAST_UPDATED_BY_2',
lastUpdatedOn='LAST_UPDATED_ON_2',
uuid='UUID_2',
version='VERSION_2',
customAttributes=[],
customObjects=[],
giftCertificateApplied=[]
),
PaymentDataDTO(
id='PAYMENT_ID_3',
date='PAYMENT_DATE_3',
status='PAYMENT_STATUS_3',
reconcileStatus='RECONCILE_STATUS_3',
totalApplied='TOTAL_APPLIED_3',
paymentApplied=[
PaymentAppliedDTO(
processor='PROCESSOR_3',
amount=AMOUNT_3,
reference='REFERENCE_3',
method='METHOD_3'
)
],
note='NOTE_3',
creditApplied=[],
invoices=[
InvoiceDTO(
applied='APPLIED_AMOUNT_3',
code='INVOICE_CODE_3',
dueDate='DUE_DATE_3',
issueDate='ISSUE_DATE_3',
outstanding='OUTSTANDING_AMOUNT_3',
total='TOTAL_AMOUNT_3'
)
],
createdBy='CREATED_BY_3',
createdOn='CREATED_ON_3',
lastUpdatedBy='LAST_UPDATED_BY_3',
lastUpdatedOn='LAST_UPDATED_ON_3',
uuid='UUID_3',
version='VERSION_3',
customAttributes=[],
customObjects=[],
giftCertificateApplied=[]
)
],
pagination=PaginationDTO(
records='TOTAL_RECORDS',
limit='LIMIT',
offset='OFFSET',
previousPage='PREVIOUS_PAGE',
nextPage='NEXT_PAGE'
)
)
){
"invoice": {
"payments": [
{
"status": "PAYMENT_STATUS_1",
"id": "PAYMENT_ID_1",
"date": "PAYMENT_DATE_1",
"reconcile_status": "RECONCILE_STATUS_1",
"total_applied": "TOTAL_APPLIED_1",
"payment_applied": [
{
"amount": "AMOUNT_1",
"method": "METHOD_1",
"processor": "PROCESSOR_1",
"reference": "REFERENCE_1"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT_1",
"code": "INVOICE_CODE_1",
"due_date": "DUE_DATE_1",
"issue_date": "ISSUE_DATE_1",
"outstanding": "OUTSTANDING_AMOUNT_1",
"total": "TOTAL_AMOUNT_1"
}
],
"created_by": "CREATED_BY_1",
"created_on": "CREATED_ON_1",
"last_updated_by": "LAST_UPDATED_BY_1",
"last_updated_on": "LAST_UPDATED_ON_1",
"uuid": "UUID_1",
"version": "VERSION_1",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "PAYMENT_STATUS_2",
"id": "PAYMENT_ID_2",
"date": "PAYMENT_DATE_2",
"reconcile_status": "RECONCILE_STATUS_2",
"total_applied": "TOTAL_APPLIED_2",
"payment_applied": [
{
"amount": "AMOUNT_2",
"method": "METHOD_2",
"processor": "PROCESSOR_2",
"reference": "REFERENCE_2"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT_2",
"code": "INVOICE_CODE_2",
"due_date": "DUE_DATE_2",
"issue_date": "ISSUE_DATE_2",
"outstanding": "OUTSTANDING_AMOUNT_2",
"total": "TOTAL_AMOUNT_2"
}
],
"created_by": "CREATED_BY_2",
"created_on": "CREATED_ON_2",
"last_updated_by": "LAST_UPDATED_BY_2",
"last_updated_on": "LAST_UPDATED_ON_2",
"uuid": "UUID_2",
"version": "VERSION_2",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "PAYMENT_STATUS_3",
"id": "PAYMENT_ID_3",
"date": "PAYMENT_DATE_3",
"reconcile_status": "RECONCILE_STATUS_3",
"total_applied": "TOTAL_APPLIED_3",
"payment_applied": [
{
"amount": "AMOUNT_3",
"method": "METHOD_3",
"processor": "PROCESSOR_3",
"reference": "REFERENCE_3"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT_3",
"code": "INVOICE_CODE_3",
"due_date": "DUE_DATE_3",
"issue_date": "ISSUE_DATE_3",
"outstanding": "OUTSTANDING_AMOUNT_3",
"total": "TOTAL_AMOUNT_3"
}
],
"created_by": "CREATED_BY_3",
"created_on": "CREATED_ON_3",
"last_updated_by": "LAST_UPDATED_BY_3",
"last_updated_on": "LAST_UPDATED_ON_3",
"uuid": "UUID_3",
"version": "VERSION_3",
"custom_attributes": [],
"custom_objects": []
}
],
"pagination": {
"records": "TOTAL_RECORDS",
"limit": "LIMIT",
"offset": "OFFSET",
"previous_page": "PREVIOUS_PAGE",
"next_page": "NEXT_PAGE"
}
}
}Configuration
Before using any of these functions, ensure that your API credentials are properly configured.
- Python: The request token is retrieved from CommonData.get_request_token_dto().
- PHP: Configuration is managed via ConfigManager and $this->paymentManager.
Language-Specific Features
|
Feature |
Python Implementation |
PHP Implementation |
|---|---|---|
|
SDK Initialization |
ExsitedSDK().init_sdk() |
$this->paymentManager |
|
Exception Handling |
ABException handles errors and raw response |
try-catch block for exceptions |
|
Response Format |
Prints response using print() |
Outputs response using json_encode() |
|
Configuration |
Managed through SDKConfig |
Managed via ConfigManager |
|
Authentication Method |
OAuth token via CommonData.get_request_token_dto() |
API credentials via $this->paymentManager |
|
Error Logging |
Captures errors with ABException and prints raw response |
Captures exceptions and prints error message |
|
Data Parsing |
JSON response parsed natively in Python |
JSON encoded and displayed using PHP |
|
Error Output |
print(ab.get_errors()) and ab.raw_response |
echo 'Error: ' . $e->getMessage() |
