--- title: Direct API integration Guide slug: direct-api-integration-guide icon: {"faIcon":"fa-solid fa-code"} docTags: createdAt: 2022-04-26T04:00:58.000Z --- # Introduction This guide aims to assist you in incorporating our Direct APIs into your system. If you have no intention of utilising octifi-websdk.js, kindly proceed with reading the following information. ### Recommendation We recommend using our provided SDK if you're comfortable using JavaScript on your client-side, as it hides complexity and is the suggested way to integrate with our APIs. You can learn more about using it in our [web integration guide.](https://docs.sg.latitudepay.com/web-integration-guide) ### Alternatively, you can use the REST APIs and manually redirect the user in simple steps ![](https://api.archbee.com/api/optimize/uMLzTav_HIzdTyGRmLuEG/ZYTXt4IlRmfg5FKbRbFc4_screenshot-2023-03-28-at-62915-pm.png "Integration Architecture") :::hint{type="info"} **NOTE** For** REST APIs** use the below Base URL and Resource path - Staging/SG/MY - [https://k2.latitudepay.me/api/v1/](https://k2.latitudepay.me/api/v1/) - Production(SG) - [https:// k2.sg.latitudepay.com/api/v1/](https://k2.sg.latitudepay.com/api/v1/) - Production(MY) - [https:// k2.my.latitudepay.com/api/v1/](#) For **Redirection** - Staging/SG/MY - [`https://latitudepay.me/webview/checkout/${precheckoutid}/?merchant_public_key=${public_key}`](https://latitudepay.me/webview/checkout/$\{precheckoutid}/?merchant_public_key=$\{public_key}) - Production(SG) - [https://app.sg.latitudepay.com/webview/checkout/${precheckoutid}/?merchant\_public\_key=${public\_key}](https://app.sg.latitudepay.com/webview/checkout/$\{precheckoutid}/?merchant_public_key=$\{public_key}) - Production(MY) -[https://app.my.latitudepay.com/webview/checkout/${precheckoutid}/?merchant\_public\_key=${public\_key}](https://app.my.latitudepay.com/webview/checkout/$\{precheckoutid}/?merchant_public_key=$\{public_key}) ::: :::ApiMethodV2 ```json { "tab": "examples", "url": "https://k2.latitudepay.me/api/v1/webview/", "name": "Step 1: GET pre-checkout token", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "kind": "required", "name": "Authorization", "type": "String", "children": [], "description": "Api-Key " } ], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "7bsE41bBTYyxOXcfLbrT9", "code": "{\n \"status_code\": 200,\n \"message\": \"success\",\n \"data\": {\n \"id\": \"55498c18-32ef-4316-87ba-8c4c014b3310\",\n \"checkout\": {\n \"checkout\": {\n \"checkout\": {\n \"merchant\": {\n \"name\": \"Merchant Name\"\n },\n \"bill\": {\n \"display_name\": \"Product \n purchase name\",\n \"tax_amount\": 0,\n \"total_amount\": 2400.99,\n \"currency\": \"MYR\",\n \"merchant_order_id\": \n \"487b0b67-7924-4484-ab14-ee7e51fb7c3d\"\n },\n \"customer\": {\n \"phone_number\": \"\",\n \"email\": \n \"joedoe@123fakestreet.com\",\n \"country_code\": \"\"\n }\n }\n },\n \"modal\": false\n },\n \"config\": {\n \"modal\": false,\n \"public_api_key\": \"your public key\",\n \"merchant_logo\": \"\",\n \"redirect_confirmation_url_action\": \"GET\",\n \"redirect_callbacks\": {\n \"onSuccess\": \n \"https://your_app.com/callback/success/\",\n \"onFail\": \n \"https://your_app.com/callback/failed/\"\n }\n }\n },\n \"errors\": null,\n \"errors_code\": {}\n}", "language": "200", "customLabel": "" }, { "id": "MdMhnqEyNIbh65-oQDKGs", "code": "{\n \"status_code\": 400,\n \"message\": \"Failed\",\n \"data\": null,\n \"errors\": {\n \"checkout\": [\n \"This field is required.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "400", "customLabel": "" }, { "id": "bN7CJ4pAXH_gsMQMsQH1T", "code": "{\n \"status_code\": 403,\n \"message\": \"Authentication credentials were not provided.\",\n \"data\": {},\n \"errors\": {\n \"non_field_errors\": [\n \"Authentication credentials were not provided.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "403", "customLabel": "" } ], "selectedLanguageId": "7bsE41bBTYyxOXcfLbrT9" }, "examples": { "languages": [ { "id": "dPTtpS3RQZTC1rPJz9wCG", "code": "{\n\t\"config\": {\n\t\t\"modal\": false,\n\t\t\"public_api_key\": \"your public key\",\n\t\t\"merchant_logo\": \"\",\n\t\t\"redirect_confirmation_url_action\": \"GET\",\n\t\t\"redirect_callbacks\": {\n\t\t\t\"onSuccess\": \n \"https://your_app.com/callback/success/\",\n\t\t\t\"onFail\": \n \"https://your_app.com/callback/failed/\"\n\t\t}\n\t},\n\t\"checkout\": {\n\t\t\"checkout\": {\n\t\t\t\"checkout\": {\n\t\t\t\t\"merchant\": {\n\t\t\t\t\t\"name\": \"Merchant Name\"\n\t\t\t\t},\n\t\t\t\t\"bill\": {\n\t\t\t\t\t\"display_name\": \"Product purchase \n name\",\n\t\t\t\t\t\"tax_amount\": 0,\n\t\t\t\t\t\"total_amount\": 2400.99,\n\t\t\t\t\t\"currency\": \"MYR\",\n\t\t\t\t\t\"merchant_order_id\": \"487b0b67- \n 7924-4484-ab14-ee7e51fb7c3d\" \n\t\t\t\t},\n\t\t\t\t\"customer\": {\n\t\t\t\t\t\"phone_number\": \"\",\n\t\t\t\t\t\"email\": \n \"joedoe@123fakestreet.com\",\n\t\t\t\t\t\"country_code\": \"\"\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\t\"modal\": false\n\t}\n}", "language": "curl", "customLabel": "Body" }, { "id": "BINDt6qcfaEl5LnjBEO6S", "code": "curl --location --request POST '/api/v1/webview/' \\\n--header 'Authorization: Api-Key demo_hardcoded_public_key_btL7eqg9_fixed' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\t\"config\": {\n\t\t\"modal\": false,\n\t\t\"public_api_key\": \"your public key\",\n\t\t\"merchant_logo\": \"\",\n\t\t\"redirect_confirmation_url_action\": \"GET\",\n\t\t\"redirect_callbacks\": {\n\t\t\t\"onSuccess\": \n \"https://your_app.com/callback/success/\",\n\t\t\t\"onFail\": \n \"https://your_app.com/callback/failed/\"\n\t\t}\n\t},\n\t\"checkout\": {\n\t\t\"checkout\": {\n\t\t\t\"checkout\": {\n\t\t\t\t\"merchant\": {\n\t\t\t\t\t\"name\": \"Merchant Name\"\n\t\t\t\t},\n\t\t\t\t\"bill\": {\n\t\t\t\t\t\"display_name\": \"Product purchase \n name\",\n\t\t\t\t\t\"tax_amount\": 0,\n\t\t\t\t\t\"total_amount\": 2400.99,\n\t\t\t\t\t\"currency\": \"MYR\",\n\t\t\t\t\t\"merchant_order_id\": \"487b0b67- \n 7924-4484-ab14-ee7e51fb7c3d\" \n\t\t\t\t},\n\t\t\t\t\"customer\": {\n\t\t\t\t\t\"phone_number\": \"\",\n\t\t\t\t\t\"email\": \n \"joedoe@123fakestreet.com\",\n\t\t\t\t\t\"country_code\": \"\"\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\t\"modal\": false\n\t}\n}'", "language": "curl", "customLabel": "" } ], "selectedLanguageId": "dPTtpS3RQZTC1rPJz9wCG" }, "description": "Obtain a pre-checkout token by sending a POST request to the endpoint provided below, using your public key. The API response will contain the pre-checkout token.", "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" } } ``` ::: | Key | Required | Description | Example Value | | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `config` | Yes | Configuration settings for the payment modal. | Object | | `modal` | Yes | Indicates whether a modal (popup) should be displayed for the payment process.
Note: It should be always `false`. As we deprecated the modal popup | `false` | | `public_api_key` | Yes | Public API key used for authentication. | `"your public key"` | | `merchant_logo` | No | URL or path to the merchant's logo image. | `""` (empty string, no logo specified) | | `redirect_confirmation_url_action` | Yes | The HTTP method (GET ) used to redirect users to the confirmation URL.
Note: `POST` method deprecated. | `"GET"` | | `redirect_callbacks` | Yes | Configuration for redirect URLs upon payment success and failure. | Object | | `onSuccess` | Yes | URL to redirect to when the payment is successful. | `"https://your_app.com/callback/success/"` | | `onFail` | Yes | URL to redirect to when the payment fails. | `"https://your_app.com/callback/failed/"` | | `checkout` | Yes | Payment checkout details. | Object | | `checkout` | Yes | Nested object for payment checkout. | Object | | `checkout` | Yes | Nested object for payment checkout. | Object | | `merchant` | Yes | Information about the merchant. | Object | | `name` | Yes | Name of the merchant. | `"Merchant Name"` | | `bill` | Yes | Billing details for the purchase. | Object | | `display_name` | No | Display name or description of the product being purchased. | `"Product purchase name" ` | | `tax_amount` | Yes | The tax amount for the purchase (if applicable). | `0` | | `total_amount` | Yes | The total purchase amount. | `"500" or "500.98" ` | | `currency` | Yes | The currency code for the purchase. | `"MYR" or "SGD"` | | `merchant_order_id` | Yes | Unique identifier for the merchant's order. Can we UUID or numeric or alpha numeric | `"487b0b67-7924-4484-ab14-ee7e51fb7c3d" or "1234555" or "ORD_123123"` | | `customer` | Yes | Customer details. | Object | | `phone_number` | No | Customer's phone number. For better user experience | `""` (empty string, no phone number specified) | | `email` | No | Customer's email address. | `"joedoe@123fakestreet.com"` | | `country_code` | No | Country code for the customer's location. | `""` (empty string, no country code specified) | | `modal` | Yes | Indicates whether a modal (popup) should be displayed for the payment process within the `checkout` section.
Note: It should be always `false`. As we deprecated the modal popup | `false` | :::ApiMethodV2 ```json { "tab": "examples", "url": "https://k2.latitudepay.me/api/v1/checkout/create/", "name": "Step 2: Create checkout token using pre-checkout token.", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "kind": "required", "name": "Authorization", "type": "String", "children": [], "description": "Api-Key " } ], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "7bsE41bBTYyxOXcfLbrT9", "code": "{\n \"status_code\": 200,\n \"message\": \"success\",\n \"data\": \"5c11f0a8-b32d-4fc9-8094-74c81fd24055\",\n \"errors\": null,\n \"errors_code\": {}\n}", "language": "200", "customLabel": "" }, { "id": "MdMhnqEyNIbh65-oQDKGs", "code": "{\n \"status_code\": 400,\n \"message\": \"Failed\",\n \"data\": null,\n \"errors\": {\n \"customer_mobile_number_or_email\": [\n \"This field may not be blank.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "400", "customLabel": "" } ], "selectedLanguageId": "7bsE41bBTYyxOXcfLbrT9" }, "examples": { "languages": [ { "id": "dPTtpS3RQZTC1rPJz9wCG", "code": "{\n \"customer_mobile_number_or_email\": \"+6559937160\",\n \"bill_merchant_order_id\": \"ORD12345\",\n \"customer_card_id\": \"pm_1MqEVHBbPvOGtj8fI9F7Ece6\",\n \"coupon\": \"\",\n \"details\": {\n \"test\": \"demo\"\n },\n \"bill_amount\": 100,\n \"bill_tax_amount\": 0,\n \"bill_total_amount\": 100,\n \"bill_currency\": \"SGD\",\n \"optional_pre_checkout_token\": \"3c215875-b118-41ca-8857-6faeaee21e51\"\n}", "language": "curl", "customLabel": "Body" } ], "selectedLanguageId": "dPTtpS3RQZTC1rPJz9wCG" }, "description": "Generate a checkout token using the pre-checkout token obtained in Step 1. To obtain the checkout token, send a POST request to the endpoint provided below, using your public key. The API response will contain the checkout token.", "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" } } ``` ::: :::ApiMethodV2 ```json { "tab": "examples", "url": "https://k2.latitudepay.me/api/v1/charge/create//", "name": "Step 3: Create charge using checkout token.", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "kind": "required", "name": "Authorization", "type": "String", "children": [], "description": "Api-Key " } ], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "7bsE41bBTYyxOXcfLbrT9", "code": "{\n \"status_code\": 200,\n \"message\": \"charge created\",\n \"data\": {\n \"order_detail\": {\n \"merchant_id\": 1,\n \"name\": \"cx-117520\",\n \"is_late\": false,\n \"next_payment\": 33.34,\n \"company_name\": \"merchant: sg.sdk-demo-merchant\",\n \"payment_method\": \"Credit Card\",\n \"advance_amount\": \"33.33\",\n \"customer_mobile_number\": \"+65599994588\",\n \"date\": \"Mar 28, 2023 06:28 P\",\n \"date_year\": \"2023\",\n \"date_month\": \"March\",\n \"date_day\": \"28\",\n \"total_installments\": 3,\n \"completed_installments\": 1,\n \"next_installment_due_date\": \"2023-04-27\",\n \"installment_status\": \"Incomplete\",\n \"installment_status_description\": \"Incomplete\",\n \"fuid\": \"1000000002\",\n \"type\": \"Pay Later\",\n \"description\": \"Order for merchant 1 is created.\",\n \"reference_invoice_number\": \"ORD12345\",\n \"amount\": 100.0,\n \"country\": \"SINGAPORE\",\n \"currency\": \"SGD\",\n \"tax_amount\": 0.0,\n \"order_total_amount\": 100.0,\n \"order_version\": \"v1\",\n \"loan_amount\": \"66.67\",\n \"is_settled\": false,\n \"order_card\": 1,\n \"status\": \"CONFIRMED\",\n \"status_description\": \"CONFIRMED\",\n \"state\": \"CONFIRMED\",\n \"loan_status\": \"OPEN (Current)\",\n \"loan_status_description\": \"OPEN (Current)\",\n \"store_name\": \"default\",\n \"store_id\": 1,\n \"terminal_id\": 1,\n \"staff_name\": \"SDK Demo Merchant:Singapore\",\n \"terminal_name\": \"default\",\n \"created_by\": 3,\n \"created_by_name\": \"SDK Demo Merchant:Singapore\",\n \"created_by_email\": \"sg.sdk-demo-merchant@t.com\",\n \"created_by_mobile_number\": \"+65999943871\",\n \"source\": \"ECOMMERCE\",\n \"read_only\": true,\n \"read_only_message\": \"Order can only be paid on merchant website\",\n \"refunds\": [],\n \"loan_scheme_snapshot\": {\n \"name\": \"SCHEME-8001862\",\n \"country\": 90,\n \"merchant\": null,\n \"installment_count\": 3,\n \"installment_interval\": 30,\n \"upfront_required\": false,\n \"min_upfront_percentage\": 33.0,\n \"min_upfront_amount\": \"30.00\",\n \"fixed_fee_amount\": \"0.00\",\n \"min_basket_amount\": \"50.00\",\n \"max_basket_amount\": \"5000.00\",\n \"active\": true,\n \"uid\": \"1c6f5d38-f8ca-4a32-9168-bc7200032005\",\n \"default\": true\n },\n \"barcode\": {\n \"data\": null,\n \"code\": \"CODE128\"\n },\n \"late_fee_details\": []\n },\n \"order_payment_details\": {\n \"result\": true,\n \"message\": \"payment done\",\n \"data\": {\n \"txn_number\": \"1000000002\",\n \"merchant_id\": 1,\n \"name\": \"cx-117520\",\n \"is_late\": false,\n \"next_payment\": 33.34,\n \"company_name\": \"merchant: sg.sdk-demo-merchant\",\n \"payment_method\": \"Credit Card\",\n \"advance_amount\": \"33.33\",\n \"customer_mobile_number\": \"+65599994588\",\n \"date\": \"Mar 28, 2023 06:28 P\",\n \"date_year\": \"2023\",\n \"date_month\": \"March\",\n \"date_day\": \"28\",\n \"total_installments\": 3,\n \"completed_installments\": 1,\n \"next_installment_due_date\": \"2023-04-27\",\n \"installment_status\": \"Incomplete\",\n \"installment_status_description\": \"Incomplete\",\n \"fuid\": \"1000000002\",\n \"type\": \"Pay Later\",\n \"description\": \"Order for merchant 1 is created.\",\n \"reference_invoice_number\": \"ORD12345\",\n \"amount\": 100.0,\n \"country\": \"SINGAPORE\",\n \"currency\": \"SGD\",\n \"tax_amount\": 0.0,\n \"order_total_amount\": 100.0,\n \"order_version\": \"v1\",\n \"loan_amount\": \"66.67\",\n \"is_settled\": false,\n \"order_card\": 1,\n \"status\": \"CONFIRMED\",\n \"status_description\": \"CONFIRMED\",\n \"state\": \"CONFIRMED\",\n \"loan_status\": \"OPEN (Current)\",\n \"loan_status_description\": \"OPEN (Current)\",\n \"store_name\": \"default\",\n \"store_id\": 1,\n \"terminal_id\": 1,\n \"staff_name\": \"SDK Demo Merchant:Singapore\",\n \"terminal_name\": \"default\",\n \"created_by\": 3,\n \"created_by_name\": \"SDK Demo Merchant:Singapore\",\n \"created_by_email\": \"sg.sdk-demo-merchant@t.com\",\n \"created_by_mobile_number\": \"+65999943871\",\n \"source\": \"ECOMMERCE\",\n \"read_only\": true,\n \"read_only_message\": \"Order can only be paid on merchant website\",\n \"refunds\": [],\n \"loan_scheme_snapshot\": {\n \"name\": \"SCHEME-8001862\",\n \"country\": 90,\n \"merchant\": null,\n \"installment_count\": 3,\n \"installment_interval\": 30,\n \"upfront_required\": false,\n \"min_upfront_percentage\": 33.0,\n \"min_upfront_amount\": \"30.00\",\n \"fixed_fee_amount\": \"0.00\",\n \"min_basket_amount\": \"50.00\",\n \"max_basket_amount\": \"5000.00\",\n \"active\": true,\n \"uid\": \"1c6f5d38-f8ca-4a32-9168-bc7200032005\",\n \"default\": true\n },\n \"barcode\": {\n \"data\": null,\n \"code\": \"CODE128\"\n },\n \"late_fee_details\": [],\n \"card_funding_type\": \"Credit Card\",\n \"card_last_digits\": \"0005\",\n \"installment_option\": {\n \"admin_fee\": \"0\",\n \"components\": {\n \"downpayment\": \"0.00\",\n \"coupon_amount\": \"0.00\",\n \"installment_amount\": \"33.33\"\n },\n \"total_payable\": \"33.33\",\n \"installment_term\": 1,\n \"installment_due_date\": \"2023-03-28\",\n \"final_installment_amount\": \"33.33\",\n \"total_installment_due_amount\": \"33.33\"\n }\n }\n },\n \"charge_id\": \"f8a28583-afce-4606-ab64-a2bc009a2ed4\"\n },\n \"errors\": null,\n \"errors_code\": {}\n}", "language": "200", "customLabel": "" }, { "id": "MdMhnqEyNIbh65-oQDKGs", "code": "{\n \"status_code\": 400,\n \"message\": \"Failed\",\n \"data\": {},\n \"errors\": {\n \"non_field_errors\": [\n \"“1c77dc50-f509-45d4-b1e6-39fd4852d71” is not a valid UUID.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "400", "customLabel": "" } ], "selectedLanguageId": "MdMhnqEyNIbh65-oQDKGs" }, "examples": { "languages": [ { "id": "dPTtpS3RQZTC1rPJz9wCG", "code": "{\n \"bill_total_amount\":100,\n \"bill_currency\" :\"SGD\",\n \"is_capture\":true\n}", "language": "curl", "customLabel": "Body" } ], "selectedLanguageId": "dPTtpS3RQZTC1rPJz9wCG" }, "description": "Create a charge by sending a POST request to the endpoint provided below, using your private key. The API response will contain a charge ID, which should be saved for future refunds.", "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" } } ``` ::: :::ApiMethodV2 ```json { "tab": "examples", "url": "https://k2.latitudepay.me/api/v1/charge/capture/", "name": "Capture Charge", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "kind": "required", "name": "Authrization ", "type": "string", "children": [], "description": "Api-Key " } ], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "mKuCoRgtbQU2yeiQXf461", "code": "{\n \"status_code\": 200,\n \"message\": {\n \"status_code\": 200,\n \"message\": \"Payment successfully captured.\",\n \"data\": \"Payment successfully captured.\",\n \"errors\": null,\n \"errors_code\": \"\"\n },\n \"data\": {\n \"ChargeStatus\": \"Charge successfully captured\",\n \"internal\": \"duplicate_charge_capture\"\n },\n \"errors\": null,\n \"errors_code\": {}\n}", "language": "200", "customLabel": "" }, { "id": "sedSw09EaedafZiv2PBaz", "code": "{\n \"status_code\": 400,\n \"message\": \"Failed\",\n \"data\": {},\n \"errors\": {\n \"charge_id\": [\n \"This field may not be blank.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "400", "customLabel": "" }, { "id": "IrTVUvjmAaQUYROV3lMMd", "code": "{\n \"status_code\": 403,\n \"message\": \"Authentication credentials were not provided.\",\n \"data\": {},\n \"errors\": {\n \"non_field_errors\": [\n \"Authentication credentials were not provided.\"\n ]\n },\n \"errors_code\": {}\n}", "language": "403", "customLabel": "" } ], "selectedLanguageId": "mKuCoRgtbQU2yeiQXf461" }, "examples": { "languages": [ { "id": "UoXEHKBetg-k_DQ1zyMqw", "code": "{\n \"charge_id\": \"d2c621e6-7db0-48e5-ae2d-859971c2e8b9\"\n}", "language": "none", "customLabel": "Body" } ], "selectedLanguageId": "UoXEHKBetg-k_DQ1zyMqw" }, "description": "If you don't want to capture a charge immediately upon creating it, you can set the is_capture parameter to false in the charge create API (Step 3) . Then, you can use the charge_id to capture the charge at a later time by making another API call.", "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" } } ``` :::