Payment Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the PaymentBuilder, your primary tool for creating the JSON payload needed to create AR Payment records with the PaymentsService.

1. Importing the PaymentBuilder

To get started, import the PaymentBuilder from the models directory.

from easy_acumatica.models.payment_builder import PaymentBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure: {"value": ...}. The PaymentBuilder handles this formatting for you automatically, so you can focus on the data itself.

The builder provides a fluent, chainable interface for setting the fields of a payment record, including simple fields and complex lists like documents to apply.

3. Building a Payment Payload

You can set top-level fields using either the generic .set() method or one of the many convenient shortcut methods.

Shortcut Methods for Top-Level Fields

For common fields, you can use one of the built-in shortcut methods for a cleaner syntax.

• .application_date(date) - In "YYYY-MM-DD" format
• .branch(branch_id)
• .cash_account(account)
• .currency_id(currency)
• .customer_id(id)
• .description(text)
• .external_ref(ref)
• .hold(True | False)
• .location_id(location)
• .payment_amount(amount)
• .payment_method(method) - e.g., "CHECK", "VISA"
• .payment_ref(ref) - e.g., a check number or external transaction ID
• .type(type) - e.g., "Payment", "Prepayment"

Credit Card Specific Fields:

• .card_account_nbr(nbr)
• .is_cc_payment(True | False)
• .is_new_card(True | False)
• .processing_center_id(pcid)
• .save_card(True | False)

Example: Building a simple payment

payment_payload = (  
    PaymentBuilder()  
    .type("Payment")  
    .customer_id("CUST01")  
    .payment_amount(150.75)  
    .payment_method("CHECK")  
    .payment_ref("CHK-1055")  
    .cash_account("10200")  
    .hold(False)  
)

4. Adding Details to a Payment

The PaymentBuilder includes special methods for building the nested lists required for applying payments or including external transaction data.

add_document_to_apply(doc_type, reference_nbr, doc_line_nbr=None)

Adds a document like an invoice or credit memo to the DocumentsToApply list.

payment_payload.add_document_to_apply(  
    doc_type="INV",   
    reference_nbr="INV00451",   
    doc_line_nbr=1  
)

add_order_to_apply(order_type, order_nbr)

Adds a sales order to the OrdersToApply list.

payment_payload.add_order_to_apply(order_type="SO", order_nbr="SO00789")

add_credit_card_transaction(tran_nbr, tran_type, auth_nbr, needs_validation=True)

Adds externally processed credit card transaction data to the CreditCardTransactionInfo list.

payment_payload.add_credit_card_transaction(  
    tran_nbr="ext_tran_id_12345",  
    tran_type="Authorize and Capture",  
    auth_nbr="auth_code_abc789"  
)

5. Generating the Final JSON Body

Once you have set all the required fields, call the .to_body() method to generate the final dictionary. This dictionary is formatted correctly and is ready to be sent as the JSON body in your API request.

# Get the final dictionary  
json_body = payment_payload.to_body()

# The json_body will look something like this:  
# {  
#     "Type": {"value": "Payment"},  
#     "CustomerID": {"value": "CUST01"},  
#     ...  
#     "DocumentsToApply": [  
#         {"DocType": {"value": "INV"}, "ReferenceNbr": {"value": "INV00451"}, ...}  
#     ]  
# }

6. Complete Example with PaymentsService

Here is a complete example of how to use the PaymentBuilder to create a new payment that is applied to an invoice.

from easy_acumatica.models.payment_builder import PaymentBuilder

# 1. Build the payment payload  
payment_to_create = (  
    PaymentBuilder()  
    .type("Payment")  
    .customer_id("TOPCUSTOMER")  
    .payment_method("WIRE")  
    .cash_account("10200")  
    .description("Payment for INV0099")  
    .add_document_to_apply(doc_type="INV", reference_nbr="INV0099")  
)

# 2. Use the payload with the PaymentsService to create the record  
try:  
    new_payment = client.payments.create_payment(  
        "24.200.001",  
        builder=payment_to_create  
    )  
    print(f"Successfully created payment: {new_payment['ReferenceNbr']['value']}")  
except Exception as e:  
    print(f"Failed to create payment: {e}")