Direct API integration Guide

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 alternatively, you can use the rest apis and manually redirect the user in simple steps note for rest apis use the below base url and resource path staging/sg/my https //k2 latitudepay me/api/v1/ production(sg) 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} { "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 \<public 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 '\<base url>/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 { "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 \<public 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" } } { "tab" "examples", "url" "https //k2 latitudepay me/api/v1/charge/create/\<checkout token>/", "name" "step 3 create charge using checkout token ", "method" "post", "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "kind" "required", "name" "authorization", "type" "string", "children" \[], "description" "api key \<private 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" } } { "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 \<private 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" } }