Cách tích hợp Got It Merchant API
API Integration Document
| Version | Description | Date of record |
|---|---|---|
| 6.0 | Initial document | 21/03/2025 |
Integration Process
Steps to integrate with Got It:
-
Register a business account with Got It's Merchant Department
-
Carry out the integration following the documentation provided
-
Software testing
-
After integrating and testing, Got It will validate your service on the sandbox environment before going to the production environment
-
After validating, your business account will be at status verified
-
Change the integration information for the production environment
-
Implement
Integration Information
Got It provides merchant 2 environments to integrate API with Got It:
-
Testing (Sandbox): Using in the integration process: build features, test, debug, etc. After registering for integration, Got It will provide each Merchant with a Pin Code to identify the store, and a list of voucher codes in the sandbox environment
-
Production: Using to deploy for end user to make payment. To connect Got It's API to the production environment, the Merchant needs to provide an IP for Got It to add to the whitelist.
-
In case the Merchant does not provide an IP for Got It to add to the whitelist: calls from merchant will be limited to maxium 20 codes/request.
Security Requirements
- All API connections must use the TLS v1.2 (or above) protocol
HTTP Request
| Data | Description |
|---|---|
| Content-Type (required) Applied to all operations | “application/json” Default: application.json |
| Domain (required) | Sandbox environment: https://openapi-stg.gotit.vn Production environment: https://openapi.gotit.vn |
References
Voucher State
| State code | State name | Description |
|---|---|---|
| 1 | New | Status means the voucher was generated and Got It returned the voucher information via API response already. |
| 2 | Sent | Voucher was sent via Email or SMS |
| 3 | Opened | Voucher link was opened (by user) |
| 4 | Used | Voucher was used (redeemed by merchant's offline stores or partnership online services (e.g. phone topup, flower order,...) |
| 5 | Downloaded | If a voucher was generated through Got It Biz Portal: status means portal user downloaded the excel file contains voucher information |
| 8 | Expired | Voucher is expired |
| 9 | Cancelled | Voucher was cancelled (by Got It with reasons) |
| 10 | Splitted | Splittable voucher was splitted to be used |
| 11 | Reserved | Voucher has been reserved for a bill number |
| 0 | Inactive | Voucher is waiting for being activated |
Timezone
We are using the time zone: GMT+7
Sequence Diagram
There are two flow to use voucher:
- RESERVE_FLOW: Check voucher -> reserve voucher -> mark use voucher
- DIRECT_FLOW: Check voucher -> mark use voucher
In RESERVE_FLOW, before mark voucher as used, we place it in reserve state. Reserved vouchers cannot be mark used by other merchants or even by other stores of the same merchant as well. This flow is suitable for online application where it need to lock the resource and make payment transaction, then mark resource as consumed when payment completed.
In DIRECT_FLOW, the process is very simple, system only need to check voucher validity then mark it as used. It is suitable for offline payment scenarios, such as in POS at store.