0 - execution successful. The data may be provided.
1 - execution failed. The error list will be provided.
Offset pagination with properties:
Offset - Skip the first number rows.
Limit - Max row number to return.
Total - Total rows
Retail deposit and POLi payment status mapping as below:
| Channel | Retail Deposit Status | Payment Status (POLi Status) |
| SEEDPOLi | Open | Initiated FinancialInstitution Selected EulaAccepted InProcess Unknown |
| Cancelled | Cancelled Failed TimedOut |
|
| Paid | ReceiptUnverified Completed |
|
| Settled | N/A |
| IBANK ACCESS DETAILS | |
| iBank Login Username/Password | DemoShopper (to simulate Completed and Cancelled payments) |
| iBank Login Username/Password | Shopper10 (to simulate a Failed/Receipt Unverified payments) |
| Test bank login credentials | |
| Username | WindcaveA2ATest |
| Password | Windcave1234 |
System will return a map contains retail deposit with payment status.
If the retail deposit status in paid/settled, the map also contains payer info. Below are two JSON samples:
Sample 1:
{
"status": 0,
"errors": [],
"data": {
"RetailDeposit": {
"retailDepositID": 23,
"retailClientID": 2,
"customerID": 42559,
"userID": 40020808,
"currency": "NZD",
"amount": 63,
"tradeDate": "2020-12-03 07:43:51.860+0000",
"paymentMethod": "SEEDPOLi",
"paymentKey": "KO5gMle5WAJ9fEPG3sqgQswd7ZmlI9xl",
"paymentUrl": "https://txn.apac.paywithpoli.com/?Token=KO5gMle5WAJ9fEPG3sqgQswd7ZmlI9xl",
"paymentStatus": "TimedOut",
"status": "Cancelled",
"remark": null,
"depositDealNo": 0,
"refund": false,
"withdrawDealNo": 0
}
}
}
Sample 2:
{
"status": 0,
"errors": [],
"data": {
"Payer": {
"countryCode": "NZ",
"financialInstitutionName": "iBank NZ 01",
"payerAccountNumber": "98742364",
"payerFirstName": "Mr",
"payerFamilyName": "DemoShopper",
"payerAccountSortCode": "123456",
"payerAccountSuffix": "",
"transactionRefNo": "996405873828"
},
"RetailDeposit": {
"retailDepositID": 28,
"retailClientID": 1,
"customerID": 42559,
"userID": 40020808,
"currency": "NZD",
"amount": 2001,
"tradeDate": "2020-12-08 03:36:55.797+0000",
"paymentMethod": "SEEDPOLi",
"paymentKey": "RCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentUrl": "https://txn.apac.paywithpoli.com/?Token=RCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentStatus": "Completed",
"status": "Settled",
"remark": null,
"depositDealNo": 736885,
"refund": true,
"withdrawDealNo": 736887
}
}
}
Retail deposit has properties to store the dealNo which mapping to backend system. Customer can check the deal in GCFX web system.
Once the retail deposit get paid successfully, the dealNo will be generated and stored in property "depositDealNo". Here is the JSON sample:
{
"retailDepositID": 24,
"retailClientID": 2,
"customerID": 42559,
"userID": 40020808,
"currency": "NZD",
"amount": 2000,
"tradeDate": "2020-12-07 06:56:00.453+0000",
"paymentMethod": "SEEDPOLi",
"paymentKey": "2GX3%2fghJDSd%2f4nupDoF5Bhz5Z3aTPZtv",
"paymentUrl": "https://txn.apac.paywithpoli.com/?Token=2GX3%2fghJDSd%2f4nupDoF5Bhz5Z3aTPZtv",
"paymentStatus": "Completed",
"status": "Paid",
"remark": null,
"depositDealNo": 736879,
"refund": false,
"withdrawDealNo": 0
}
It also allows the refund for a paid retail deposit.
After refund request made, the dealNo will be generated and stored in property "withdrawDealNo" for withdrawal. Here is JSON sample:
{
"retailDepositID": 28,
"retailClientID": 1,
"customerID": 42559,
"userID": 40020808,
"currency": "NZD",
"amount": 2001,
"tradeDate": "2020-12-08 03:36:55.797+0000",
"paymentMethod": "SEEDPOLi",
"paymentKey": "RCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentUrl": "https://txn.apac.paywithpoli.com/?Token=RCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentStatus": "Completed",
"status": "Settled",
"remark": null,
"depositDealNo": 736885,
"refund": true,
"withdrawDealNo": 736887
}
Callbacks are a useful way of notifying you when statuses or entities change. For example, if an RetailClient changes state because we have processed verification, we will POST a JSON payload with the entity object attributes to the URL provided.
| Type | Trigger | Payload Examples |
| RetailClient |
|
{
"RetailClient": {
"retailClientID": 1,
"customerID": 42559,
"referenceID": "CU42559-2",
"firstName": "t1 change",
"lastName": "t1last name",
"birthday": "2000-05-06 00:00:00.000+0000",
"gender": "Femal",
"title": "Miss",
"nationality": "China",
"idType": "ID",
"idNumber": "K1234567",
"idIssueCountry": "Hong Kong",
"phoneNumber": "888888888",
"residentialAddress": "aaa",
"residentialStreet": "bbb",
"residentialCity": "ccc",
"residentialState": "ddd",
"residentialPostalCode": "",
"residentialCountry": "Hong Kong",
"email": "ttt@noemail.com",
"industry": "Marketing",
"jobLevel": "3",
"occupation": "manager",
"currencyPair": "",
"fatcaDeclaration": true,
"masterAgreementConfirm": true,
"jumioResult": "xxxx-xxxx-xxxxx-xxxxx",
"status": "Pending"
}
}
|
| RetailDeposit |
|
{
"RetailDeposit": {
"retailDepositID": 28,
"retailClientID": 1,
"customerID": 42559,
"userID": 40020808,
"currency": "NZD",
"amount": 2001.0,
"tradeDate": "2020-12-08 03:36:55.797+0000",
"paymentMethod": "SEEDPOLi",
"paymentKey": "RCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentUrl": "https://txn.apac.paywithpoli.com/?Token\u003dRCNSW13rEVY6yRqJUkkDwSyU7tktNE4m",
"paymentStatus": "Completed",
"status": "Settled",
"depositDealNo": 736885,
"refund": true,
"withdrawDealNo": 736887
}
}
|
| PaymentLinkStatus |
|
{
"PaymentLinkStatus":{
"requestID":10000393,
"customerID":149619,
"userID":40123452,
"bunitID":108535,
"region":"HKG",
"customerName":null,
"payerBankAccountID":156902,
"payerCompanyName":"ABC Company Ltd",
"payerCompanyPhone":"+852 1234 5678",
"payerCompanyAddress":"Payer Company Address",
"payerName":"John Smith",
"payerEmail":"noemail@noemail.com",
"description":"Payment link from ABC Company Ltd",
"comment":"ACCOUNTING_SERVICE",
"requestTime":"2023-05-24 15:14:34.297+0000",
"currency":"USD",
"amount":100.0,
"linkID":"550FA897-82C3-4A27-B354-F041469CBA42",
"paymentURL":null,
"linkExpiry":"2023-05-30 00:00:00.000+0000",
"status":"Paid",
"eventID":215,
"dealNo":759225,
"dealSetID":232680,
"failTimes":0,
"creationTime":"2023-05-24 15:14:36.053+0000",
"createdBy":"40123452",
"lastUpdateTime":"2023-05-24 18:41:37.320+0000",
"lastUpdatedBy":"40123452"
}
}
|
| RetailClientComment |
|
{
"RetailClientComment": {
"id": 7,
"retailClientID": 2,
"source": "KVB",
"comment": "this is comment content 5",
"creationTime": "2021-01-12 09:38:14.284+0800"
}
}
|
| DepositReceived |
|
Example 1: DBS deposit received {
"DepositReceived": {
"dealID": 12345,
"externalDealSetID": 4888,
"virtualAccountNo": "838822-3883",
"virtualAccountName": "Test Name",
"txnDate": "2021-03-31 03:12:05.999+0000",
"currency": "HKD",
"txnAmt": 2000.0,
"comment":"KVBH - TTT International Trading Limited,79914152957,VIPSHOP INTERNATIONAL HOLDINGS,1251965036,1513IT285678301",
"txnFees":[{
"type": "BankCharge",
"currency": "HKD",
"amount": 20
}],
"remark":{
"line1":"PAY FOR GOODS",
"line2":"/SPRO/01"
}
}
}
DBS Remark:- line1: PaymentDetail - line2: AdditionalDetail Example 2: Banking Circle deposit received {
"DepositReceived": {
"dealID": 12345,
"externalDealSetID": 4888,
"virtualAccountNo": "838822-3883",
"virtualAccountName": "Test Name",
"txnDate": "2021-03-31 03:12:05.999+0000",
"currency": "HKD",
"txnAmt": 2000.0,
"comment":"KVBH - TTT International Trading Limited,79914152957,VIPSHOP INTERNATIONAL HOLDINGS,1251965036,1513IT285678301",
"txnFees":[{
"type": "BankCharge",
"currency": "HKD",
"amount": 20
}],
"remark":{
"line1":"PAYMENT OF MARKETING SUPPORT CHARGE",
"line2":"S AS PER INV NO 023 2022 07 ISN 055",
"line3":"158 OSN 052244 SSN 0320835/RFB/SWF",
"line4":"OF 22/08/30"
}
}
}
|
| VirtualBankAccount |
|
Example 1: callback when virtual account created {
"VirtualBankAccount": {
"requestID": "93E0F564-30A3-4BE6-B5A2-4A8965E3B68A",
"customerReference": "Ref 1",
"virtualBankID": 1011,
"virtualBankName": "DBS Bank (Hong Kong) Limited",
"virtualBankAccountNo": "79932154715",
"virtualBankAccountName": "MEGGIE INTERNATIONAL HOLDINGS LIMITED",
"accountStatus": "Enabled",
"action": "Create"
}
}
Example 2: callback when virtual account updated with KYC data fields {
"VirtualBankAccount": {
"requestID": "93E0F564-30A3-4BE6-B5A2-4A8965E3B68A",
"customerReference": "Ref 1",
"virtualBankID": 1011,
"virtualBankName": "DBS Bank (Hong Kong) Limited",
"virtualBankAccountNo": "79932154715",
"virtualBankAccountName": "MEGGIE INTERNATIONAL HOLDINGS LIMITED",
"accountStatus": "Enabled",
"action": "Update",
"externalCustomerType": "CORPORATION",
"countryOfIncorporation": "HK",
"dateOfIncorporation": "2000-11-19",
"alias": "MEGGIE INTERNATIONAL HOLDINGS HK LIMITED",
"customerIDType": "BUSINESS REGISTRATION CERTIFICATE",
"customerIDNumber": "BA-123456",
"customerIDIssuanceCountry": "HK",
"registeredAddress": {
"street": "11 street",
"city": "22 city",
"state": "33 state",
"postalCode": "44444",
"country": "HK"
},
"businessAddress": {
"street": "11 street",
"city": "22 city",
"state": "33 state",
"postalCode": "44444",
"country": "HK"
}
}
}
Remark:- accountStatus: Enabled/Disabled - action: Create/Update/Remove - externalCustomerType: show if it is added or modified - countryOfIncorporation: show if it is added or modified - dateOfIncorporation: show if it is added or modified - alias: show if it is added or modified - customerIDType: show if it is added or modified - customerIDNumber: show if it is added or modified - customerIDIssuanceCountry: show if it is added or modified - registeredAddress: show if it is added or modified - businessAddress: show if it is added or modified |
| DealStatus |
|
{
"DealStatus": {
"dealID": 123456,
"status": "settled",
"remark": null
}
}
Remark:- status: settled/unsettled/fundreceived |
| RetailDeposit |
|
{
"RetailDeal": {
"retailDealID": 123,
"referenceID": "ref10001",
"buyCcy": "CNH",
"buyAmount": 501.1,
"sellCcy": "AUD",
"sellAmount": 100,
"contractRate": 5.011,
"tradeDate": "2021-01-07 08:28:29.770+0000",
"valueDate": "2021-01-07 16:00:00.000+0000",
"dealNo": 727660,
"highPriority": true
}
}
|
There are a few measures that can be taken to ensure callbacks are secure. HTTPS URLs are supported and require a valid SSL certificate.
| Method | Description |
| IP whitelisting |
Whitelist the following IPs that callbacks will be sent from: 220.241.200.241
157.120.243.42 |
Create a callback
Use Create Callback to create your callback within GCFX. Pass a valid HTTPS URL that will accept a POST request. This URL will receive a POST call when the callback object is triggered. When creating a Callback, the URL provided will be sent a test JSON payload and will only be successfully created if the response created is successful.
The output of the test you will receive from us is:
{ "message": "EFX callback test"}
Trigger callback
To trigger a callback, update the object you have created a callback for.
An example of this would be to Update for an Retail Client, if the callback you created was for an RetailClient.
List callback responses
Use List Callback Responses to view a list of the triggers for the callback you created. Each time the callback is triggered, a response will be added.
Client application will need to perform the encryption and decryption, and signing and verfication of the message using the security software
Service URL Base https://domain/EFXExtApi/ws/auth
| Service | URL |
| Retail Quote | https://domain/EFXExtApi/ws/auth/retailquote |
| Retail Deal | https://domain/EFXExtApi/ws/auth/retaildeals |
| Limit Order | https://domain/EFXExtApi/ws/auth/orders |
The message starts with a header that contains the following information:
X-KVB-ClientKey: <clientKey> Accept: application/json Content-Type: application/json
<clientKey> is provided by KVB.
If the message body is required, it should be encrypted using PGP with the KVB's public key.
For the message body definition, please refer to related module in online document:
Retail Quote
Create Retail Deal
Search Retail Deal
Create Limit Order
Search Limit Order
Request Order Cancel
Each request message should have one response message if response code=200.
The response message should be decrypted using PGP with the client's private key.
For the response message definition, please refer to related module in online document as above links.
| Country Code | Name |
| AU | Australia |
| BE | Belgium |
| BN | Brunei |
| BG | Bulgaria |
| KH | Cambodia |
| CA | Canada |
| CN | China |
| FR | France |
| DE | Germany |
| GB | Great Britain |
| HK | Hong Kong |
| IN | India |
| ID | Indonesia |
| IE | Ireland |
| IT | Italy |
| JP | Japan |
| LV | Latvia |
| MO | Macau |
| MY | Malaysia |
| NL | Netherlands |
| NZ | New Zealand |
| PH | Philippines |
| KR | S Korea |
| SG | Singapore |
| ES | Spain |
| CH | Switzerland |
| TW | Taiwan |
| TH | Thailand |
| US | United States |
| VN | Vietnam |
| OT | Other |