refundCgInvoice

Overview

The refundCgInvoice command processes refunds for invoices generated through the EZcount system. This command creates a credit note that cancels or partially refunds the original invoice while maintaining proper tax compliance and audit trails.

Use cases

Use refundCgInvoice when you need to:

Process full refunds for customer returns or cancellations
Handle partial refunds for damaged or incomplete orders
Generate credit notes for tax compliance purposes
Maintain proper documentation for financial reconciliation
Reverse invoice charges while preserving audit trails

Request structure

For general API request structure and authentication, see API Request & Response General Structure.

The refundCgInvoice command uses the following endpoint:

POST https://your-hyp-environment-url/xpo/Relay

HTTP request format

The request must be sent as a POST request with application/x-www-form-urlencoded content type, containing three required body parameters:

Parameter

Type

Description

user

string

Your merchant username for API authentication

password

string

Your merchant password for API authentication

int_in

string

XML payload containing the command and parameters (see structure below)

XML request structure

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>refundCgInvoice</command>
        <refundCgInvoice>
            <invoiceAtranId>119443246</invoiceAtranId>
            <invoice>
                <createInvoice>1</createInvoice>
            </invoice>
        </refundCgInvoice>
    </request>
</ashrait>

Required parameters

invoiceAtranId - string

The unique invoice transaction ID returned from the original addCgInvoice call. This is the identifier for the invoice to be refunded.

Example: 119443246

createInvoice - string

Indicates whether to create a credit note for the refund. Set to `1` to generate the credit document.

Valid Values: 1 (create credit note)

Response structure

Success response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>refundCgInvoice</command>
        <dateTime>2025-08-13 12:22</dateTime>
        <requestId />
        <tranId>119445298</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo />
        <version>2000</version>
        <language>Eng</language>
        <refundCgInvoice>
            <invoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceResponseCode>100</invoiceResponseCode>
                <invoiceResponseName>Proper Invoice Request</invoiceResponseName>
                <invoiceDocNumber>23961</invoiceDocNumber>
                <invoiceDocUrl>https://demo.ezcount.co.il/front/documents/get/4acae6f9-e907-472c-8254-792ec0c15a2c/copy_en</invoiceDocUrl>
                <invoiceAtranId>119445264</invoiceAtranId>
                <invoiceCreationDate>1755076924</invoiceCreationDate>
                <mailTo>[email protected]</mailTo>
                <invoiceCreationCode>000</invoiceCreationCode>
            </invoice>
        </refundCgInvoice>
    </response>
</ashrait>

Key Response Fields:

result: 000 indicates successful API call
invoiceCreationCode: 000 indicates successful credit note creation
invoiceResponseCode: 100 indicates proper invoice request
invoiceDocNumber: The generated credit note number
invoiceDocUrl: Direct link to view/download the credit note

Error responses

Example 1: No invoice found for source transaction

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>refundCgInvoice</command>
        <dateTime>2025-08-13 12:19</dateTime>
        <requestId />
        <tranId>119445219</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo />
        <version>2000</version>
        <language>Eng</language>
        <refundCgInvoice>
            <invoice>
                <invoiceCreationMethod />
                <invoiceResponseCode />
                <invoiceResponseName>No invoice was produced source transaction</invoiceResponseName>
                <invoiceDocNumber />
                <invoiceDocUrl />
                <invoiceAtranId>119443246</invoiceAtranId>
                <invoiceCreationDate>1755076765</invoiceCreationDate>
                <mailTo />
                <invoiceCreationCode>673</invoiceCreationCode>
            </invoice>
        </refundCgInvoice>
    </response>
</ashrait>

Example 2: Transaction type mismatch

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>refundCgInvoice</command>
        <dateTime>2025-08-13 12:21</dateTime>
        <requestId />
        <tranId>119445266</tranId>
        <result>675</result>
        <message>Deal type does not match invoice type</message>
        <userMessage>Deal type does not match invoice type</userMessage>
        <additionalInfo>RefundCgInvoice command was sent when the transaction type is a debit transaction</additionalInfo>
        <version>2000</version>
        <language>Eng</language>
        <refundCgInvoice>
            <invoice>
                <createInvoice>1</createInvoice>
            </invoice>
        </refundCgInvoice>
    </response>
</ashrait>

Code examples

#!/bin/bash

# Full refund of an invoice
curl -X POST https://your-hyp-environment-url/xpo/Relay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "user=your_username" \
  --data-urlencode "password=your_password" \
  --data-urlencode "int_in=<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>refundCgInvoice</command>
        <refundCgInvoice>
            <invoiceAtranId>119443246</invoiceAtranId>
            <invoice>
                <createInvoice>1</createInvoice>
            </invoice>
        </refundCgInvoice>
    </request>
</ashrait>"

import requests
import xml.etree.ElementTree as ET

def refund_invoice(username, password, invoice_atran_id):
    """
    Process a refund for an EZcount invoice
    """
    # Build XML request
    ashrait = ET.Element("ashrait")
    request = ET.SubElement(ashrait, "request")
    
    ET.SubElement(request, "version").text = "2000"
    ET.SubElement(request, "language").text = "ENG"
    ET.SubElement(request, "command").text = "refundCgInvoice"
    
    refund_cg_invoice = ET.SubElement(request, "refundCgInvoice")
    ET.SubElement(refund_cg_invoice, "invoiceAtranId").text = invoice_atran_id
    
    invoice = ET.SubElement(refund_cg_invoice, "invoice")
    ET.SubElement(invoice, "createInvoice").text = "1"
    
    xml_string = ET.tostring(ashrait, encoding='unicode')
    
    # Send request with user/password as separate parameters
    response = requests.post(
        "https://your-hyp-environment-url/xpo/Relay",
        data={
            "user": username,
            "password": password,
            "int_in": xml_string
        },
        headers={
            "Content-Type": "application/x-www-form-urlencoded"
        }
    )
    
    if response.status_code == 200:
        # Parse response
        root = ET.fromstring(response.text)
        result = root.find(".//result").text
        
        if result == "000":
            credit_note_url = root.find(".//creditNoteUrl").text
            credit_note_number = root.find(".//creditNoteNumber").text
            refund_amount = root.find(".//refundAmount").text
            print(f"Refund processed: {refund_amount}")
            print(f"Credit note: {credit_note_number}")
            print(f"Download URL: {credit_note_url}")
            return {
                "success": True,
                "credit_note_url": credit_note_url,
                "credit_note_number": credit_note_number,
                "refund_amount": refund_amount
            }
        else:
            message = root.find(".//message").text
            print(f"Error: {message}")
            return {"success": False, "error": message}
    else:
        return {"success": False, "error": f"HTTP {response.status_code}"}

# Example usage
result = refund_invoice(
    username="your_username",
    password="your_password",
    invoice_atran_id="119443246"
)

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.*;

public class InvoiceRefund {
    
    public static class RefundResult {
        public boolean success;
        public String creditNoteUrl;
        public String creditNoteNumber;
        public String refundAmount;
        public String error;
        
        public RefundResult(boolean success, String creditNoteUrl, String creditNoteNumber, 
                          String refundAmount, String error) {
            this.success = success;
            this.creditNoteUrl = creditNoteUrl;
            this.creditNoteNumber = creditNoteNumber;
            this.refundAmount = refundAmount;
            this.error = error;
        }
    }
    
    public static RefundResult refundInvoice(String username, String password, String invoiceAtranId) {
        try {
            // Build XML request
            StringBuilder xml = new StringBuilder();
            xml.append("<ashrait>");
            xml.append("<request>");
            xml.append("<version>2000</version>");
            xml.append("<language>ENG</language>");
            xml.append("<command>refundCgInvoice</command>");
            xml.append("<refundCgInvoice>");
            xml.append("<invoiceAtranId>").append(invoiceAtranId).append("</invoiceAtranId>");
            xml.append("<invoice>");
            xml.append("<createInvoice>1</createInvoice>");
            xml.append("</invoice>");
            xml.append("</refundCgInvoice>");
            xml.append("</request>");
            xml.append("</ashrait>");
            
            // Send HTTP request with user/password as separate parameters
            URL url = new URL("https://your-hyp-environment-url/xpo/Relay");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            conn.setDoOutput(true);
            
            String postData = "user=" + URLEncoder.encode(username, "UTF-8") +
                            "&password=" + URLEncoder.encode(password, "UTF-8") +
                            "&int_in=" + URLEncoder.encode(xml.toString(), "UTF-8");
            
            try (OutputStream os = conn.getOutputStream()) {
                os.write(postData.getBytes("UTF-8"));
            }
            
            // Parse response
            if (conn.getResponseCode() == 200) {
                DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                DocumentBuilder builder = factory.newDocumentBuilder();
                Document doc = builder.parse(conn.getInputStream());
                
                String result = doc.getElementsByTagName("result").item(0).getTextContent();
                
                if ("000".equals(result)) {
                    String creditNoteUrl = doc.getElementsByTagName("creditNoteUrl").item(0).getTextContent();
                    String creditNoteNumber = doc.getElementsByTagName("creditNoteNumber").item(0).getTextContent();
                    String refundAmount = doc.getElementsByTagName("refundAmount").item(0).getTextContent();
                    System.out.println("Refund processed: " + refundAmount);
                    System.out.println("Credit note: " + creditNoteNumber);
                    System.out.println("Download URL: " + creditNoteUrl);
                    return new RefundResult(true, creditNoteUrl, creditNoteNumber, refundAmount, null);
                } else {
                    String message = doc.getElementsByTagName("message").item(0).getTextContent();
                    System.out.println("Error: " + message);
                    return new RefundResult(false, null, null, null, message);
                }
            } else {
                return new RefundResult(false, null, null, null, "HTTP " + conn.getResponseCode());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
            return new RefundResult(false, null, null, null, e.getMessage());
        }
    }
    
    public static void main(String[] args) {
        RefundResult result = refundInvoice(
            "your_username",
            "your_password",
            "119443246"
        );
        
        if (result.success) {
            System.out.println("Success! Credit note URL: " + result.creditNoteUrl);
        } else {
            System.out.println("Failed: " + result.error);
        }
    }
}

const https = require('https');
const querystring = require('querystring');
const { DOMParser } = require('xmldom');

function refundInvoice(username, password, invoiceAtranId) {
    return new Promise((resolve, reject) => {
        // Build XML request
        let xml = `<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>refundCgInvoice</command>
        <refundCgInvoice>
            <invoiceAtranId>${invoiceAtranId}</invoiceAtranId>
            <invoice>
                <createInvoice>1</createInvoice>
            </invoice>
        </refundCgInvoice>
    </request>
</ashrait>`;

        // Prepare POST data with user/password as separate parameters
        const postData = querystring.stringify({
            user: username,
            password: password,
            int_in: xml
        });

        // HTTP request options
        const options = {
            hostname: 'cguat2.creditguard.co.il',
            path: '/xpo/Relay',
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

        // Send request
        const req = https.request(options, (res) => {
            let responseData = '';

            res.on('data', (chunk) => {
                responseData += chunk;
            });

            res.on('end', () => {
                try {
                    // Parse XML response
                    const parser = new DOMParser();
                    const doc = parser.parseFromString(responseData, 'text/xml');
                    
                    const result = doc.getElementsByTagName('result')[0]?.textContent;
                    
                    if (result === '000') {
                        const creditNoteUrl = doc.getElementsByTagName('creditNoteUrl')[0]?.textContent;
                        const creditNoteNumber = doc.getElementsByTagName('creditNoteNumber')[0]?.textContent;
                        const refundAmount = doc.getElementsByTagName('refundAmount')[0]?.textContent;
                        console.log(`Refund processed: ${refundAmount}`);
                        console.log(`Credit note: ${creditNoteNumber}`);
                        console.log(`Download URL: ${creditNoteUrl}`);
                        resolve({
                            success: true,
                            creditNoteUrl: creditNoteUrl,
                            creditNoteNumber: creditNoteNumber,
                            refundAmount: refundAmount
                        });
                    } else {
                        const message = doc.getElementsByTagName('message')[0]?.textContent;
                        console.log(`Error: ${message}`);
                        resolve({
                            success: false,
                            error: message
                        });
                    }
                } catch (error) {
                    reject(error);
                }
            });
        });

        req.on('error', (error) => {
            reject(error);
        });

        // Send POST data
        req.write(postData);
        req.end();
    });
}

// Example usage
(async () => {
    try {
        const result = await refundInvoice(
            'your_username',
            'your_password',
            '119443246'
        );
        
        if (result.success) {
            console.log('Success! Credit note URL:', result.creditNoteUrl);
        } else {
            console.log('Failed:', result.error);
        }
    } catch (error) {
        console.error('Error:', error.message);
    }
})();

Error codes

All invoice-related error codes are returned in the invoiceResponseCode and invoiceResponseName tags.

CG Gateway invoice error codes

Code

Description

Solution

668

Cannot Create Invoice

Check invoice parameters and retry

669

Currency not supported for invoice creation

Verify currency is supported for invoicing

670

Invoice Validation Failed

Check that invoice values are valid

671

Invoice not found

Verify the invoice identifier is correct

Invoice vendor response codes

Code

Description

Solution

100

Success

Invoice operation completed successfully

101

UsernameInvalid

Check username for invoice system

102

CompanyCodeAlreadyExists

Company code already exists in system

103

CompanyCodeDoesNotExist

Verify company code exists

104

CompanyCodeInvalidFormat

Company code must be numeric

105

DocumentInvalidSubject

Subject line is invalid

106

DocumentDoesNotExist

Document number was not found

107

SendEmailAborted

E-mailing document failed

108

EmailInvalid

Check email format

109

CultureInvalid

Invalid culture setting

110

KeyInvalid

Invalid key provided

111

AccountExpired

Account has expired

112

DocumentInvalidItemNumber

Multiple items in wrong format

113

DocumentInvalidQuantity

Quantity must be numeric

114

DocumentInvalidPrice

Price must be numeric

116

DocumentDoesNotExistForSpecifiedCompany

Document doesn't exist for company

117

CurrencyConversionServiceNotAvailable

Currency service unavailable

118

InvalidItemCode

Unacceptable item code

119

CurrencyInWrongFormat

Currency must be integer

120

DocumentMissingItem

Quantity, price, description and code must match

121

DocumentInvalidDateFormatDDMMYY

Date format must be DDMMYY

122

PaymentAmountDoesntMatchInvoice

Total receivables must be positive

123

DocumentAmountInvalid

Amount must be double

124

CashInvalidAmount

Cash amount must be double

125

CheckInvalidAmount

Check amount must be double

126

CCInvalidAmount

Credit card amount must be double

127

TransInvalidAmount

Transaction amount must be double

128

CheckInvalidDateFormatDDMMYY

Check date format must be DDMMYY

129

CCInvalidDateFormatDDMMYY

CC date format must be DDMMYY

130

TransInvalidDateFormatDDMMYY

Transaction date format must be DDMMYY

131

PaymentTotalMustBeEqualToInvoiceTotal

Payment must equal invoice total

132

TaxRateInTheDocsIsNotEqual

Tax rate mismatch in documents

133

ClientCompanyNameAlreadyExists

Company name already exists

134

ClientTicketAlreadyExists

Client ticket already exists

Invoice vendor response messages are always returned in English.

addCgInvoice - Create new invoices
inquireInvoice - Query invoice information
refundDeal - Process transaction refunds
doDeal - Process payments with automatic invoice generation

Best practices

Use invoiceAtranId - This is the most reliable identifier for refund processing
Always create credit notes - Set createInvoice to 1 to generate proper documentation
Support partial refunds - Allow customers to refund partial amounts for damaged or incomplete orders
Validate refund amounts - Ensure refund amounts don't exceed the original invoice total
Store credit note information - Keep track of credit note numbers and URLs for customer service
Handle tax implications - Credit notes properly handle VAT and tax reversals for compliance

PreviousinquireInvoice NextrefundDeal

Last updated 3 months ago

Was this helpful?

Good afternoon

Overview

Use cases

Request structure

HTTP request format

XML request structure

Required parameters

Response structure

Success response

Error responses

Example 1: No invoice found for source transaction

Example 2: Transaction type mismatch

Code examples

Error codes

CG Gateway invoice error codes

Invoice vendor response codes

Related commands

Best practices