🌐 Language: 🇻🇳 Tiếng Việt · 🇬🇧 English (current)

Giao Hang Nhanh (GHN) for GP247 / S-Cart

Introduction

A free plugin that connects your GP247 / S-Cart shop to Giao Hang Nhanh (GHN): customers see GHN's real fee at checkout, and you book shipments, print labels, cancel and track orders right in the admin. This guide is for shop owners and administrators; no programming needed. After reading it you can register with GHN, get the Token and ShopId, configure the plugin and ship your first order.

The plugin runs on the standard shipping layer of gp247/shop (from the version with "industry-standard shipping").

What the plugin does

The whole setup:

flowchart LR
    subgraph GHN["On the GHN site"]
        direction TB
        A["Register an account"] --> B["Get the Token"]
        B --> C["Find the ShopId"]
    end
    subgraph ADMIN["In the GP247 admin"]
        direction TB
        D["Install and enable the plugin"] --> E["Enter Token and ShopId"]
        E --> F["Set the pick-up warehouse and customer address fields"]
        F --> G["Paste the webhook URL into GHN"]
    end
    GHN --> ADMIN
    ADMIN --> H["Try one order, then switch to live"]

Part 1 — Register with GHN and get the Token and ShopId

GHN has two completely separate environments: accounts, Tokens, ShopIds and webhook settings of one do not work on the other.

1.1. Get the Token

Do this on the portal of the environment you want (start with staging):

1. Open the developer portal (table above) and press Log in at the right end of the header.

2. Enter your phone number and pass the verification step. You can also sign in with Google or Apple. For the live environment, use the phone number of the GHN account your shop ships with.

3. Once signed in, open the account menu at the right and choose Manage token.

4. On the Token API card, click the eye icon. GHN sends a 6-digit OTP to your phone; enter it to reveal the Token.

5. Click the copy icon to copy the Token.

   A Token looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Treat it like a password: paste it only into the GHN settings screen in the admin, never into chat or email.

6. Leave the Allowed IP list empty unless you are sure of your web server's IP. As soon as it holds one IP, GHN blocks every request from any other IP — including your server if you typed the wrong one.

1.2. Find the ShopId

The ShopId is the number of a shop on GHN (one GHN account can have several shops). You find it in the account information on the GHN site.

• A freshly registered staging account usually comes with one shop without an address — that is fine, the plugin sends your pick-up warehouse to GHN (see Part 3).
• If you cannot find the ShopId, enter the Token on the settings screen (Part 2), type any number as ShopId and save. The message "The ShopId does not belong to this token's account" means the Token is right and only the ShopId is wrong.

Part 2 — Install and configure the plugin in the admin

2.1. Install

1. Go to Extension → Plugins.

2. Find Giao Hang Nhanh (GHN), click Install, then Enable.

   If it worked, the Shipping method menu of the shop gets a GHN entry.

2.2. The GHN settings screen

Open Shipping method → GHN (or click ⚙ next to the plugin on the Plugins screen). If you run several stores, pick the store at the top of the screen first.

Click Save. The system checks the connection with GHN and shows one of these:

Part 3 — Shop configuration for shipping

Go to System management → Website configuration → Shop configuration.

3.1. Shipping tab

1. Turn on Enable shipping at checkout.

2. Fill in Pick-up warehouse (sender address) — GHN picks up here and prices from here:

   • Sender / shop name and Warehouse phone (the courier calls this number).
   • Province / city and Ward using the new administrative names (since 1 July 2025). Example: TP. Hồ Chí Minh and Phường Sài Gòn.
   • Street address: house number and street. Example: 12 Lê Lợi.
   • District: leave empty where the district tier was removed.

   The plugin uses this warehouse only when Province / city, Ward and Street address are all filled. If one is missing, GHN uses the address of your GHN shop — and if that shop has no address either, GHN will not quote.

3. Default weight per product (grams): used for products without a weight.

4. Record COD cash on the order when the carrier reports it reconciled: turn on only if you reconcile COD from GHN's reports. Each shipment is recorded once.

5. Click Save. The warning box at the top of the tab must no longer mention the warehouse or the customer address.

3.2. Customer tab

Turn on the Province / city and Ward fields (preferably required) for customer addresses. Without them GHN does not know where to deliver and gives no fee at checkout.

3.3. Currency

The shop must have the VND currency (GHN prices in VND). Orders in another currency are converted with the rates you set.

Part 4 — Webhook: automatic status updates

Without a webhook the plugin still works: the status is fetched from GHN when you open the order or click Sync. The webhook updates it as soon as GHN changes it.

1. On the GHN settings screen, in Automatic status updates (webhook), copy the webhook URL (like https://<your-domain>/shipping/webhook/ShippingGHN?hash=...).
2. On the GHN developer portal (same environment as the Token), open the account menu → Webhook configuration → Order tab.
3. Paste the URL and click Create webhook. GHN needs about 15 minutes to apply it.
4. When you switch to live, repeat steps 2–3 on developer.ghn.vn — staging settings do not carry over.

⚠️ The webhook URL contains a secret. Do not publish it. If it leaks: tick Generate a new webhook secret on save, click Save, then paste the new URL into GHN. GHN must be able to reach your site over the Internet: local domains (localhost, *.local) never receive webhooks.

Part 5 — Daily use in the admin

5.1. Customer orders

At the Shipping step customers see GHN — Light parcel or GHN — Heavy parcel with the fee and the expected delivery date. That is the fee GHN quotes for exactly that cart and address; the shop pays GHN.

5.2. Book a shipment

1. Open the order, go to the Shipping panel, click Create shipment.

2. Check the recipient, the Weight (grams) and — once packed — the Parcel size (cm). Correct figures keep GHN's fee in line with what the customer paid.

3. Check Cash on delivery: by default it is the amount the customer still owes.

4. Confirm. On success the panel shows the GHN Tracking number (for example L8RWHQ), the carrier fee and the status Awaiting pick-up.

   If the panel says "Carrier fee differs from the fee on the order", the weight or size changed since the customer ordered — check before handing the parcel over.

5.3. Print the label

Click Download label: the browser downloads an .html file made by GHN. Open it and the print dialog appears. You need to be online when opening it (barcode images come from GHN). Change the size with Label size on the settings screen.

5.4. Track, cancel

• Sync: asks GHN for the latest status; the history shows under Tracking history.
• Cancel shipment: only while GHN still allows it (usually before pick-up). After cancelling you can book a new shipment for the same order.
• Delivered, Returned, Cancelled and COD money are always confirmed directly with GHN before being recorded, so a fake notification cannot change the order's money status.

Conditions & Rules (know before you act)

When quoting at checkout

• Total weight at most 50 kg — GHN does not accept heavier parcels, so GHN does not appear at checkout.
• The customer address needs a Province / city and a Ward that match GHN's catalogue (accents and prefixes such as "TP." or "Phường" do not matter). An old address that still has a district is sent as typed in the old format. A name too different ⇒ no GHN fee for that address.
• A pick-up warehouse whose province / ward GHN does not recognise ⇒ no fee — use the new administrative names.

When booking

• Recipient name and phone are required — the courier needs to reach them.
• Cash on delivery at most 50,000,000 VND per order — a GHN limit.
• Insured value at most 5,000,000 VND — above that GHN insures only up to 5,000,000 VND.
• Retrying after a network error never creates a duplicate — GHN returns the shipment it already created.

When cancelling

• Only while GHN allows it; when GHN refuses, the admin shows GHN's reason.

Environments

• Staging Token, ShopId and webhook do not work on live, and vice versa.

API reference

Based on GHN's public documentation (developer.ghn.vn), checked and tested live on staging on 2026-10-18.

License

Free and open source under the GP247 license.

Q&A

Q1: GHN does not show at checkout?

→ Check in order: the GHN settings screen says Connected; the Customer tab has Province and Ward on; the pick-up warehouse has province, ward and street address; VND exists; the cart is at most 50 kg; the plugin is enabled for the store that sells.

Q2: The Token is right but GHN gives no fee, or booking says "Address convert from fail"?

→ GHN does not know where to pick up. Fill in the Pick-up warehouse in Shop configuration → Shipping (Part 3.1), or set an address for your shop on GHN.

Q3: What do I do to switch from staging to live?

→ Get the Token and ShopId on developer.ghn.vn, set Environment = Live (production), paste the new Token, fix the ShopId, Save; then set up the webhook again on the live GHN portal (Part 4).

Q4: GHN charges a different fee than the customer paid?

→ Usually product weights are missing or wrong. Enter product weights (and sizes); when booking, correct the weight and size of the packed box.

Q5: The customer address is still in the old format (with a district)?

→ The plugin sends it as typed in the old format and lets GHN resolve it. If GHN still refuses, fix the address to the new administrative names before booking.

Q6: The order status does not update by itself?

→ Check that the webhook has the right URL, the right environment, and that about 15 minutes have passed. A site on a local domain cannot be reached by GHN — use Sync.

Q7: The label file opens blank or without barcodes?

→ The computer opening it needs Internet access (barcode images come from GHN). If it still fails, click Download label again for a fresh file.

Q8: Can one GHN account serve several stores?

→ Yes. Enter the Token and ShopId at the shared scope; each store sets its own pick-up warehouse in Shop configuration and GHN picks up there. A store that needs its own GHN account picks itself on the settings screen and gets its own Token.

Q9: Where do I see what went wrong?

→ When booking, cancelling or downloading a label, the admin says what to fix (e.g. the Street address names a ward other than the selected one, an invalid phone, no service on the route), followed by GHN's own words in brackets. A Token rejected by GHN is written to the system log so you know to get a new one.

Q10: Does uninstalling lose booked shipments?

→ No. Shipments and their history are stored by the shop; uninstalling only removes the GHN settings.

_{📅 Last updated: 2026-10-18 · ✍️ Author: GP247}