Billpayment - CSQ Docs

Introduction

The Invoice Payment API allows you to retrieve and pay pending invoices. The workflow is dynamic and adapts based on the account type and product-specific requirements. The following steps describe the process in detail.

Workflow

Step 1: Obtaining Parameters

Input

To begin, the client sends:

A product identifier to determine what fields are required for querying and completing the payment.

Response

The system dynamically generates:

Fields required for querying invoices (query).

Fields required for processing the payment (pay).

Labels and types for front-end integration (front).

Example Response:

{
    "rc": 0,
    "message": "OK",
    "front": [
        {
            "name": "card_code",
            "label": "CARD CODE",
            "type": "INPUT"
        },
        {
            "name": "installments_to_pay",
            "label": "INSTALLMENTS TO PAY",
            "type": "INPUT"
        }
    ],
    "query": [
        "card_code",
        "installments_to_pay"
    ],
    "pay": [
        "card_code",
        "installments_to_pay",
        "transaction_code"
    ]
}

Please note that the fields vary depending on the product, which is why a dynamic structure is being proposed.

The fields in query must be provided in the next step, and pay fields will be required for the payment.

Get parameters

Step 2: Service Query

Input

The client sends the fields specified in the query section from Step 1 as key-value pairs.

Example Query Body:

[
    {
        "key": "card_code",
        "value": "1234567890"
    },
    {
        "key": "installments_to_pay",
        "value": "2"
    }
]

Response

The system dynamically provides the necessary data, which may include:

Customer details (e.g., full name).

Transaction code (transaction_code).

Invoice details (e.g., pending invoices, amounts, fees).

Example Response:

{
    "rc": 0,
    "message": "OK",
    "additionalData": [
        {
            "key": "customerFullName",
            "value": "ANONYMOUS USER"
        },
        {
            "key": "transaction_code",
            "value": "ABC123XYZ"
        }
    ],
    "type": "OPEN",
    "pendingInvoices": 1,
    "amountToSendX100": 5000,
    "destinationAmountX100": 5000,
    "serviceFeeX100": 0,
    "totalAmountX100": 5000
}

Key elements in the response:

additionalData: Contains dynamic fields required for the next steps (e.g., transaction_code).

type: Indicates the payment type (e.g., “OPEN”).

"TOTAL" Payment: This product type allows only the full payment of the outstanding debt.

"DISCRETE" Payment: In this case, the system provides an invoice breakdown, enabling the payment of one or more invoices individually without the need to cover the total accumulated debt.

"OPEN" Payment: This product works similarly to a digital wallet. The customer can load an amount into their “wallet” and choose to either cover the total debt, pay a portion of it (leaving a negative balance), or add more than the amount owed, leaving a positive balance in their account.

Amount fields (amountToSendX100, totalAmountX100, etc.) in cent units.

Get Invoces

Step 3: Making the Payment

Input

The client submits:

Transaction-specific fields: These include data from pay and additionalData returned in previous steps.

Payment details:

beneficiaryPhoneNumber (OPTIONAL, ONLY when info sms must be send to the beneficiary and this option is active).

amountToSendX100 (depends on transaction type).

localDateTime (timestamp of the transaction).

Example Payment Body:

{
    "beneficiaryPhoneNumber": "123456789",
    "amountToSendX100": 5000,
    "localDateTime": "2024-12-04T17:47:00",
    "additionalData": [
        {
            "key": "contract_number",
            "value": "CONTRACT1234"
        },
        {
            "key": "transaction_code",
            "value": "ABC123XYZ"
        }
    ]
}

Response

The system processes the payment and returns the result (e.g., success status, confirmation details, or errors).

Payment

Key Considerations

Dynamic Workflow:

The required fields for each step are determined dynamically by the system based on the product identifier provided.

This ensures flexibility across different products and services.

Field Types:

The front section specifies labels and input types to guide front-end integration (e.g., text input fields).

Payment Flexibility:

Supports scenarios like total payments, partial payments, or open payments (wallet).

Each type adjusts dynamically based on the system’s response.

With this information, the system will process the payment request.

Bill Payment

Introduction#

Workflow#

Step 1: Obtaining Parameters#

Step 2: Service Query#

Step 3: Making the Payment#

Key Considerations#

Introduction

Workflow

Step 1: Obtaining Parameters

Step 2: Service Query

Step 3: Making the Payment

Key Considerations