3️Implementing the Transaction Sync API

This API is used to synchronize balance changes from VietQR back to the partner.

POST API Transaction Sync

https://<client-host>/<basepath>/bank/api/transaction-sync

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Required	Description
bankAccount	String	Yes	Bank account for generating payment codes.
amount	Long	Yes	Transaction amount.
transType	String	Yes	Transaction classification as debit/credit (value: D/C).
content	String	Yes	Transfer description.
transactionId	String	Optional	Transaction ID.
transactionTime	String	Optional	Transaction timestamp.
referenceNumber	String	Optional	Transaction code.
orderId	String	Optional	Order ID.
terminalCode	String	Optional	Store/point of sale code.
serviceCode	String	Optional	Product/service code.
urlLink	String	Optional	Link to navigate after successful payment.
sign	String	Optional	Signature.

Response

200

{
    "error": false,
    "errorReason": "error_code_returned_from_partner",
    "toastMessage": "error_description_returned_from_partner",
    "object": {
        "reftransactionid": "transaction_id"
    }
}

400

{
    "error": false,
    "errorReason": "error_code_returned_from_partner",
    "toastMessage": "error_description_returned_from_partner",
    "object": null
}

---

Code mẫu

Java Code

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class VietQRTransactionSync {
    public static void main(String[] args) {
        try {
            // URL for the API endpoint
            URL url = new URL("https://<client-host>/<basepath>/bank/api/transaction-sync");

            // Open a connection to the URL
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setDoOutput(true);
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Bearer <token>");

            // Create the JSON payload
            String jsonInputString = "{"
                + "\"bankAccount\": \"1234567890\","
                + "\"amount\": 100000,"
                + "\"transType\": \"C\","
                + "\"content\": \"Payment for order #1234\","
                + "\"transactionId\": \"txn_123456\","
                + "\"transactionTime\": \"2024-07-25T12:34:56\","
                + "\"referenceNumber\": \"ref_123456\","
                + "\"orderId\": \"order_1234\","
                + "\"terminalCode\": \"store_001\","
                + "\"serviceCode\": \"service_001\","
                + "\"urlLink\": \"https://example.com/success\","
                + "\"sign\": \"signature_string\""
                + "}";

            // Write the JSON payload to the output stream
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            // Get the response code
            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            // Handle the response (omitted for brevity)
            // ...

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

cURL

curl --location 'https://<BANK_URL>/<path>/bank/api/transaction-sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIxNDUwMzEzLCJleHAiOjE3MjE0NTA2MTN9.u0hK2fZVFvtaZQ3jyVJmMvhyqW8aRFGJIgpL8C71jtXbAPfPhqyJIdGc0Lv-XOY7e1NcjZQWH3FUhc4SXxgqlQ' \
--data '{
    "transactionid": "transaction_id",
    "transactiontime": "payment_time_in_milliseconds",
    "referencenumber": "transaction_code",
    "amount": "transaction_amount",
    "content": "transaction_description",
    "bankaccount": "bank_account",
    "orderId": "paid_order_id",
    "sign": "signature",
    "terminalCode": "store_code",
    "urlLink": "url_redirect_after_successful_payment",
    "serviceCode": "product_code",
    "subTerminalCode": "sub_store_code"
}'

---

FAQs

What is the Transaction Sync API used for?

The Transaction Sync API is used to synchronize transaction data from the VietQR system with the customer’s system. It ensures that information about transactions is always updated and consistent between the two systems.

What should be prepared before implementing the Transaction Sync API?

Before implementation, you need to prepare the authentication information (username and password) provided by VietQR, along with the API endpoint that you will integrate. Ensure that your system is ready to receive and process synchronized data from VietQR.

What data is synchronized through the Transaction Sync API?

The data synchronized through the Transaction Sync API typically includes transaction information such as transaction code, amount, transaction status, and execution time. The specific details will depend on the configuration of VietQR and the specific requirements of your system.

How to handle synchronization failures?

If synchronization fails, the API will return an error code and detailed message. You should recheck the data sent, ensure that the authentication information is correct, and that your system can accept data from the API. If the error persists, contact the technical support team of VietQR.