Jarvix Pay online payment API Document ==== ## Revision History | Revision Date | Version | Updated by | Summary of Changes | | ------------- | ------- | ----------- |:----------------------------------- | | 15-07-2019 | 0.1 | Thomas Lee | Architecture Design | | 25-07-2019 | 0.2 | Paul Chan | Initial version | | 11-10-2019 | 1.0 | Thomas Lee | API updated | | 18-10-2019 | 1.2 | Paul Chan | API updated | | 24-10-2019 | 1.2 | Dickson Lok | UI Updated | | 28-10-2019 | 1.2 | Dickson Lok | UI Updated | | 01-11-2019 | 1.3 | Paul Chan | API Endpoints Added | | 05-11-2019 | 1.4 | Thomas Lee | Process Flow Updated | | 08-05-2020 | 1.5 | Paul Chan | Supported currencies updated | | 08-06-2020 | 1.6 | Paul Chan | Supported disable phone number | | 25-09-2020 | 2.0 | Paul Chan | New Version Released | | 04-11-2020 | 2.1 | Paul Chan | Metadata and Disable Webhook | | 10-11-2020 | 2.2 | Paul Chan | Bulk get api Added | | 27-08-2021 | 2.3 | Paul Chan | Added checksum field in the webhook | ## Contents - [Abstract](#Abstract) - [Overview](#Overview) - [Process flow](#Process-flow) - [Schema](#Schema) - [API List](#API-List) - [Appendix](#Appendix) ## Abstract This describes the resources that make up the official Jarvix Pay Gateway REST API v2.0. If you have any problems or requests, please contact [Jarvix Pay Support](https://www.aigniter.com/zh-hk#about). ## Overview Jarvix Pay Online Payment enables customers to pay credit cards, including Visa, MasterCard, American Express on your websites. You can then use this payment API to accept customer's credit card payment with simple integration on your website. Merchant benefits with Javix Pay Online Payment include: 1. Streamlined Payment Experiences - Customers can simply fill in credit card information and pay in seconds. 2. Apple Pay and Google Pay supported - Customers can pay with Apple Pay and Google Pay via their Apple devices or Chrome browser. 3. Flexible Redirect Links - You could customize your redirect links in different situations, including successful payment, failure payment or payment cancellation. 4. Secure & Extensible Data Handling - Jarvix Pay handles complicated payment process securely while you handle customer information. Meanwhile, Jarvix Pay can handle customer information when you authorized. Also, Jarvix Pay API provided a variety of programmatic status queries. 5. Responsive design - The user experience is optimized for desktop and mobile browsers. ## Process flow ![](https://i.imgur.com/Dqt4bqw.png) `Business Flow` 1. When a customer clicks the checkout on the merchant's website, it redirects to Jarvix Pay Online Payment Page. 2. Customer input payment details and trigger payment progress. 3. Payment Scenarios 3.1. It redirects customers back to the merchants' website after the successful payment. 3.2. It prompts a customer for payment retry after the failed payment. 3.3. It redirects customers back to the merchants' website if customers cancel the payment process. `Technical Flow` 1. Merchant's website sends `POST /order` request, including **payment details** and **checksum**, to Jarvix Pay API server to create an order for payment pre-processing. 2. Jarvix Pay API server verifies the checksum and throws the error if it's invalid. 3. The response redirects the customer to Jarvix Pay Online Payment Page and retrieves payment details from Jarvix Pay API server. 4. User types his/her credit card information and Jarvix Pay Online Payment Page will complete the payment process. 5. Jarvix Pay API server `POST` requests to **merchant's webhook URL** and pass with payment information with status. 6. When the customer finishes the payment, Jarvix Pay Online Payment Page redirects to **merchant's website**. ## Schema All API access is over **HTTPS**, and accessed from In REST API calls, including the URL to the API service for the environment: Base URL Sandbox > `https://api.staging.pay.jarvix.ai/api/v2/online_payment` Base URL Production > `https://api.customer.pay.jarvix.ai/online_payment` ## API List ### `POST /order` - Create the order in payment gateway before customers pay #### Resource URL > Sandbox: `https://api.staging.pay.jarvix.ai/api/v2/online_payment/order` > Production: `https://api.customer.pay.jarvix.ai/online_payment/order` #### Resource Information |Request Content-Type|Response formats|Requires authentication| |-|-|-| |`application/x-www-form-urlencoded`|`application/json; charset=utf-8`|No| #### Parameters | Name | type | Required | Description | Default | Example | | ----------------- | ----------------------------- | -------- |:----------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------- | | reference_id | string or number | required | Unique Reference Id for Merchant's order | | ord8824121-19xmas-1572491224 | | account_id | string | required | Account Id in Jarvix Pay | | 146b80f5-a220-4377-82ee-7dcc4cf72e59 | | price | number | required | Total price of the order | | 23500.2 | | currency | string(**lowercase**) | required | Country Currency Codes(ISO 4217), please refer to the appendix | | hkd | | order_description | string | required | Order description | | xmas packages | | remarks | string | optional | Remarks for merchants order (additional information) | | morning session | | success_url | string | required | Page to navigate after successful payment | | https://example.com/order/ord8824121-19xmas-1572491224/success | | failed_url | string | required | Page to navigate after failure payment | | https://example.com/order/ord8824121-19xmas-1572491224/failure | | cancel_url | string | required | Page to navigate when canceling payment | | https://example.com/order/ord8824121-19xmas-1572491224 | | notify_url | string | required | The webhook URL will be notified to update the status of the order. When customer pay, Jarvix Pay will POST a notify request to the notify_url. | | https://example.com/webhook/order/ord8824121-19xmas-1572491224/status | | metadata | string | optional | Metadata for the request | | {"from_magento":1} | | cmd | string (redirect, return_url) | required | The API can perform redirect to our gateway(redirect) or get an url for the gateway payment page(return_url) | | | | force_redirect | string(true) or boolean | optional | If this field set to true, the page will redirect to success page immediately after success payment, instead of showing the receipt page. | | | | webhook_require | string(false) or boolean | optional | If this field set to false, the webhook will not be sent | | | | checksum | string | required | A checksum value to avoid tampered information (Please refer to section Checksum algorithm(A)) | | 534dee136c961c6acec356af369340da7b1ee400c2e5df5134cb79caf5702d52 | #### Checksum algorithm(A) - To prevent the payment information tampered by malicious attackers. A checksum field is required for some APIs. The `checksum` is calculated as follows: `checksum = SHA256(reference_id + price + currency + account_id + secret_key)`(`+` is string concatenation operator). - `secret_key` should not be publicly accessible, so the malicious attacker cannot generate a valid checksum - `checksum` should be generated by **backend** #### Example Request ```console curl -X POST \ "https://api.staging.pay.jarvix.ai/api/v2/online_payment/order" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Postman-Token: 6935d8ff-148f-4ed3-9828-0a7acadb5064" \ -H "cache-control: no-cache" \ -d "reference_id=ord8824121-19xmas-1572491224&account_id=146b80f5-a220-4377-82ee-7dcc4cf72e59&price=888&currency=hkd&order_description=xmas%20packages&remarks=morning%20session&success_url=https%3A%2F%2Fexample.com%2Forder%2Ford8824121-19xmas-1572491224%2Fsuccess&failed_url=https%3A%2F%2Fexample.com%2Forder%2Ford8824121-19xmas-1572491224%2Ffailure&cancel_url=https%3A%2F%2Fexample.com%2Forder%2Ford8824121-19xmas-1572491224&notify_url=https%3A%2F%2Fexample.com%2Fwebhook%2Forder%2Ford8824121-19xmas-1572491224%2Fstatus&cmd=redirect&checksum=534dee136c961c6acec356af369340da7b1ee400c2e5df5134cb79caf5702d52" ``` Or using HTML form ```html <form action="https://api.staging.pay.jarvix.ai/api/v2/online_payment/order" accept-charset="UTF-8" class="" id="contestForm" method='POST'> reference_id:<br> <input type="text" name="reference_id" value="ord8824121-19xmas-1572491224" size="30"> <br>account_id</br> <input type="text" name="account_id" value="146b80f5-a220-4377-82ee-7dcc4cf72e59" size="30"> <br>price:</br> <input type="text" name="price" value="888" size="30"> <br>order_description:</br> <input type="text" name="order_description" value="xmas packages" size="30"> <br>currency:</br> <input type="text" name="currency" value="hkd" size="30"> <br>remark:</br> <input type="text" name="remark" value="morning session" size="30"> <br>success_url:</br> <input type="text" name="success_url" value="https://example.com/order/ord8824121-19xmas-1572491224/success" size="30"> <br>notify_url:</br> <input type="text" name="notify_url" value="https://example.com/order/ord8824121-19xmas-1572491224/failure" size="30"> <br>failed_url:</br> <input type="text" name="failed_url" value="https://example.com/order/ord8824121-19xmas-1572491224" size="30"> <br>cancel_url:</br> <input type="text" name="cancel_url" value="https://example.com/webhook/order/ord8824121-19xmas-1572491224/status" size="30"> <br>cmd:</br> <input type="text" name="cmd" value="redirect" size="30"> <br>checksum:</br> <input type="text" name="checksum" value="534dee136c961c6acec356af369340da7b1ee400c2e5df5134cb79caf5702d52" size="30"> <br></br> <input type="submit" value="Submit"> </form> ``` #### Example Response ```JSON { "success": true, "data": "https://online-payment.staging.pay.jarvix.ai/pay/v2/48086141-afdb-47f0-a902-fee28b781f6f" } ``` #### Example Webhook Notification(in POST request) | Field name | Type | Description | Example | | ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `order_id` | uuid | The id of the online payment order | 48086141-afdb-47f0-a902-fee28b781f6f | | `transaction_id` | uuid | The id of the transaction | 6448a3ca-0b55-4f8a-8610-a9f305091b3e | | `reference_id` | uuid | Unique Reference Id for Merchant's order | ord8824121-19xmas-1572491224 | | `price` | number | The price of the order | 888 | | `currency` | string | The currency of the order | hkd | | `credit_card_last4` | string | the last 4 digits of the credit card | 4242 | | `cardholder` | string | the masked cardholder's name | CHAN S** M** | | `status` | string(succeeded or failed) | The status of this transaction | succeeded | | `remarks` | string(nullable) | The remarks of the order | morning session | | `created_at` | string | The time when the transaction was created | 2021-08-27T10:03:03.000Z | | `created_at_timestamp` | number | The unix timestamp when the transaction was created | 1630058583 | | `checksum` | string | A checksum value to avoid tampered information (Please refer to section Checksum Algorithm(B)) | 13097fd52b07a21c907598435156c64c2dd091f97d6100d6f6d07176a5b0be5a | #### Checksum algorithm(B) - To prevent the forged webhook request by malicious attackers. A checksum field is added to the webhook to provide data integrity and identity authentication. The `checksum` is calculated as follows: `checksum = SHA256(reference_id + price + currency + credit_card_last4 + cardholder + status + created_at_timestamp + secret_key)`(`+` is string concatenation operator). - `secret_key` should not be publicly accessible, so the malicious attacker cannot generate a valid checksum ```JSON { "order_id": "48086141-afdb-47f0-a902-fee28b781f6f", "transaction_id": "6448a3ca-0b55-4f8a-8610-a9f305091b3e", "reference_id": 'ord8824121-19xmas-1572491224', "price": 888, "currency": 'hkd', "credit_card_last4": "4242", "cardholder": "CHAN S** M***", "status": "succeeded", "remarks": "morning session", "created_at": "2021-06-29T15:33:00", "created_at_timestamp": 1630057541, "checksum": "13097fd52b07a21c907598435156c64c2dd091f97d6100d6f6d07176a5b0be5a" } ``` ### `GET /order/status/:referenceId?account_id=:accountId&secret_key=:secretKey` - Get Order Information by Order Reference ID with account credentials #### Resource URL > Sandbox: `https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/status/:referenceId?account_id=:account_id&secret_key=:secret_key` > Production: `https://api.customer.pay.jarvix.ai/online_payment/order/status/:referenceId?account_id=:account_id&secret_key=:secret_key` #### Resource Information | Request Content-Type | Response formats | Requires authentication | | ----------------------------------- | --------------------------------- | ----------------------- | | `application/x-www-form-urlencoded` | `application/json; charset=utf-8` | Yes | #### Parameters | Name | type | Required | Description | Default | Example | |:----------- | ---------------- |:-------- | ----------------------------- | ------- | ------------------------------------ | | referenceId | string or number | Required | The referenceId of your order | | ord8824121-19xmas-1572491224 | | account_id | string | Required | Account Id in Jarvix Pay | | 146b80f5-a220-4377-82ee-7dcc4cf72e59 | | secret_key | string | Required | Secret Key for your account | | luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR | #### Example Request ```console curl -X GET \ 'https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/status/ord8824121-19xmas-1572491224?account_id=146b80f5-a220-4377-82ee-7dcc4cf72e59&secret_key=luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR' \ -H 'Accept: */*' \ -H 'Accept-Encoding: gzip, deflate' \ -H 'Cache-Control: no-cache' \ -H 'Connection: keep-alive' \ -H 'Host: api.staging.pay.jarvix.ai' \ -H 'cache-control: no-cache' ``` #### Example Response ```JSON { "success":true, "data":{ "id":"48086141-afdb-47f0-a902-fee28b781f6f", "reference_id":"ord8824121-19xmas-1572491224", "price":888, "currency":"hkd", "current_status":"succeeded", "order_description":"xmas packages", "remarks":null, "metadata":null, "success_url":"https://example.com/order/ord8824121-19xmas-1572491224/success", "notify_url":"https://example.com/order/ord8824121-19xmas-1572491224/failure", "failed_url":"https://example.com/order/ord8824121-19xmas-1572491224", "cancel_url":"https://example.com/webhook/order/ord8824121-19xmas-1572491224/status", "created_at":"2019-11-04 18:23:31 HKT", "webhook_error_message":[ { "webhook_error_id":"046e2c04-10d4-47a0-98a4-3bfeaaa13f9e", "error_message":"Request failed with status code 404", "created_at":"2019-11-04 18:28:04 HKT" }, { "webhook_error_id":"4cb20437-03e5-4222-a9b7-cb90adf7af5b", "error_message":"Request failed with status code 404", "created_at":"2019-11-04 18:28:16 HKT" } ], "transaction_history":[ { "transaction_id":"6448a3ca-0b55-4f8a-8610-a9f305091b3e", "status":"succeeded", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:15 HKT" }, { "transaction_id":"fb070c83-9c7b-4ac4-b00a-a82a8cecd78d", "status":"failed", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:03 HKT" } ] } } ``` ### `POST /order/:reference_id/Receipt/external` - Send email receipt #### Resource URL > Sandbox: `https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/:reference_id/Receipt/external` > Production: `https://api.customer.pay.jarvix.ai/online_payment/order/:reference_id/Receipt/external` #### Resource Information | Request Content-Type | Response formats | Requires authentication | | ----------------------------------- | --------------------------------- | ----------------------- | | `application/x-www-form-urlencoded` | `application/json; charset=utf-8` | Yes #### Parameters | Name | type | Required | Description | Default | Example | |:------------------- | ----------------------------- |:-------- |:--------------------------- | ------- |:------------------------------------ | | client_email | string (email address format) | Required | the customer's email | | abc@xyz.com | | client_name | string | Required | The customer's name | | Alice | | client_phone_number | string or number | Optional | The customer's phone number | | 94910231 | | account_id | string | Required | Account Id in Jarvix Pay | | 146b80f5-a220-4377-82ee-7dcc4cf72e59 | | secret_key | string | Required | Secret Key for your account | | luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR | #### Example Request ```console curl -X POST \ "https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/31231/Receipt/external" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Postman-Token: 6935d8ff-148f-4ed3-9828-0a7acadb5064" \ -H "cache-control: no-cache" \ -d "client_email=abc@xyz.com&client_name=Alice&client_phone_number=94910231&account_id=146b80f5-a220-4377-82ee-7dcc4cf72e59&secret_key=luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR" ``` #### Example Response ```JSON { "success": true, "data": "250 2.0.0 OK 1600998529 134sm521087pgf.55 - gsmtp" } ``` ### `POST /order/status/bulk?account_id=:accountId&secret_key=:secretKey` - Bulk Get all Order Information by reference id list with account credentials #### Resource URL > Sandbox: `https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/status/bulk?account_id=:account_id&secret_key=:secret_key` > Production: `https://api.customer.pay.jarvix.ai/online_payment/order/status/bulk?account_id=:account_id&secret_key=:secret_key` #### Resource Information | Request Content-Type | Response formats | Requires authentication | | ----------------------------------- | --------------------------------- | ----------------------- | | `application/json; charset=utf-8` | `application/json; charset=utf-8` | Yes | #### Parameters | Name | type | Required | Description | Default | Example | | |:---------- | ----------------- |:-------- | --------------------------- | ------- | ------------------------------------ | --- | | account_id | string | Required | Account Id in Jarvix Pay | | 146b80f5-a220-4377-82ee-7dcc4cf72e59 | | | secret_key | string | Required | Secret Key for your account | | luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR | | #### Body - The post body contains the list of `reference_id` that you want to query. Maximum number of `reference_id` in the list is **100**. ```JSON { "reference_id_list": [ '1234', '5678', '91011' ... ] } ``` ### Example Request ```console curl --location --request POST '{{baseURL}}/online_payment/order/status/bulk?account_id=d42ddd62-bcad-45ea-ab66-9bcd308ce000&secret_key=bp6vvOczctNpDjbAeAiEdKFgGlSsuuYKQzub' \ --header 'Content-Type: application/json' \ --data-raw '{ "reference_id_list": [ "uZpr", "S0an", ] }' ``` #### Example Response ```JSON { "success":true, "data":{ "id":"48086141-afdb-47f0-a902-fee28b781f6f", "reference_id":"uZpr", "price":888, "currency":"hkd", "current_status":"succeeded", "order_description":"xmas packages", "remarks":null, "metadata":null, "success_url":"https://example.com/order/ord8824121-19xmas-1572491224/success", "notify_url":"https://example.com/order/ord8824121-19xmas-1572491224/failure", "failed_url":"https://example.com/order/ord8824121-19xmas-1572491224", "cancel_url":"https://example.com/webhook/order/ord8824121-19xmas-1572491224/status", "created_at":"2019-11-04 18:23:31 HKT", "webhook_error_message":[ { "webhook_error_id":"046e2c04-10d4-47a0-98a4-3bfeaaa13f9e", "error_message":"Request failed with status code 404", "created_at":"2019-11-04 18:28:04 HKT" }, { "webhook_error_id":"4cb20437-03e5-4222-a9b7-cb90adf7af5b", "error_message":"Request failed with status code 404", "created_at":"2019-11-04 18:28:16 HKT" } ], "transaction_history":[ { "transaction_id":"6448a3ca-0b55-4f8a-8610-a9f305091b3e", "status":"succeeded", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:15 HKT" }, { "transaction_id":"fb070c83-9c7b-4ac4-b00a-a82a8cecd78d", "status":"failed", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:03 HKT" } ] } } ``` ### `GET /order/status?date=:date&account_id=:accountId&secret_key=:secretKey` - Get all Order Information in a particular date with account credentials #### Resource URL > Sandbox: `https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/status/?date=:date&account_id=:account_id&secret_key=:secret_key` > Production: `https://api.customer.pay.jarvix.ai/online_payment/order/status/?date=:date&account_id=:account_id&secret_key=:secret_key` #### Resource Information | Request Content-Type | Response formats | Requires authentication | | ----------------------------------- | --------------------------------- | ----------------------- | | `application/x-www-form-urlencoded` | `application/json; charset=utf-8` | Yes | #### Parameters | Name | type | Required | Description | Default | Example | | |:---------- | ----------------- |:-------- | --------------------------- | ------- | ------------------------------------ | --- | | date | string (YYYYMMDD) | Required | the date of records | | 20191104 | | | account_id | string | Required | Account Id in Jarvix Pay | | 146b80f5-a220-4377-82ee-7dcc4cf72e59 | | | secret_key | string | Required | Secret Key for your account | | luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR | | #### Example Request ```console curl -X GET \ 'https://api.staging.pay.jarvix.ai/api/v2/online_payment/order/status?date=20191104&account_id=146b80f5-a220-4377-82ee-7dcc4cf72e59&secret_key=luuqP5K7CIMJvsPlUuqnzk2qWieKXGXR' \ -H 'Accept: */*' \ -H 'Accept-Encoding: gzip, deflate' \ -H 'Cache-Control: no-cache' \ -H 'Connection: keep-alive' \ -H 'Host: api.staging.pay.jarvix.ai' \ -H 'cache-control: no-cache' ``` #### Example Response ```JSON { "success":true, "data":[ { "id":"48086141-afdb-47f0-a902-fee28b781f6f", "reference_id":"ord8824121-19xmas-1572491224", "price":888, "currency":"hkd", "current_status":"succeeded", "order_description":"xmas packages", "remarks":null, "metadata": null, "success_url":"https://example.com/order/ord8824121-19xmas-1572491224/success", "cancel_url":"https://example.com/webhook/order/ord8824121-19xmas-1572491224/status", "failed_url":"https://example.com/order/ord8824121-19xmas-1572491224", "notify_url":"https://example.com/order/ord8824121-19xmas-1572491224/failure", "created_at":"2019-11-04 18:23:31 HKT", "transaction_history":[ { "transaction_id":"6448a3ca-0b55-4f8a-8610-a9f305091b3e",![](https://i.imgur.com/PcGa9pW.png) "status":"succeeded", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:15 HKT" }, { "transaction_id":"fb070c83-9c7b-4ac4-b00a-a82a8cecd78d", "status":"failed", "amount":888, "currency":"hkd", "created_at":"2019-11-04 18:28:03 HKT" } ] } ] } ``` ## Appendix ### Supported Currencies | Currency Name | ISO Code | |:--------------------:|:--------:| | Hong Kong dollar | hkd | | United States Dollar | usd | | Japanese yen | jpy | | Macau Pataca | mop | | Pound sterling | gbp | | Rénmínbì | cny | | Singapore Dollar | sgd | | Malaysian Ringgit | myr | | Thai baht | thb | ### Test card number | Card Number | Brand | CVC | Date(MM/YYYY) | Description | | ------------------- | ---------------- | ------------ | --------------- | ------------------ | | 4242 4242 4242 4242 | Visa | Any 3 digits | Any future date | successful payment | | 5555 5555 5555 4444 | Master | Any 3 digits | Any future date | successful payment | | 3782 822463 10005 | American Express | Any 4 digits | Any future date | successful payment | | 4000 0000 0000 0002 | - | Any 3 digits | Any future date | declined charege | ### Email Receipt template ![](https://i.imgur.com/25PpndB.png) ### FAQ > The response shows "The user is unauthorized" - Please check your account_id > The response shows "The request checksum does not match" - Please check your checksum