Pay3 API Documentation
Create Subscription Order
2 min
this api creates a subscription order to enable users to make payment and start subscriptions it accepts amount and currency details on creating an order a dynamic token is returned from this api which is required to be passed to pay3 sdk this api requires access token that can be generated using docid\ lq v6ff 2i h1o3xd5kka api { "name" "create checkout order", "method" "post", "url" "https //your hostname pay3 app/v1/client/checkout/create order", "description" "create an order with payin details from application's backend", "tab" "examples", "examples" { "languages" \[ { "id" "nyfshp7j nrsuqth3fw7t", "language" "curl", "code" "curl location 'https //api dev pay3 app/v1/client/subscription/create order' \\\\\n header 'accept application/json' \\\\\n header 'content type application/json' \\\\\n header 'signature {{signature}}' \\\\\n header 'access token ' \\\\\n data raw '{\n \\"currencyid\\" \\"usd usa\\",\n \\"fiatamount\\" \\"1 00\\",\n \\"paymentmethodid\\" \\"all\\",\n \\"email\\" \\"user\@example com\\",\n \\"userid\\" \\" \\",\n \\"clientid\\" \\" \\",\n \\"requestid\\" \\" \\",\n \\"interval\\" \\"monthly\\",\n \\"requestdescription\\" \\"gold plan\\",\n \\"mode\\" \\"returnurl\\"\n}'", "customlabel" "" } ], "selectedlanguageid" "nyfshp7j nrsuqth3fw7t" }, "results" { "languages" \[ { "id" "vqyrchsr38ubbehatupjh", "language" "200", "code" "{\n \\"requestid\\" \\"5a3566b0 b0a9 4329 b48f 2921c715ce44\\",\n \\"url\\" \\"https //dev ui pay3 app/web sdk pay/3b789bdc 3b33 4123 be35 459f58787cee?referrer=https //dev ui pay3 app\&action=subscription\&data=eyjyzxf1zxn0swqioii1ytm1njzimc1imge5ltqzmjktyjq4zi0yotixyzcxnwnlndqilcj0b2tlbii6ijbhzdm3otqxltg2oditndg5nc1imdlklwyzyjg3mzhkoty5zsj9\&lang=en\\",\n \\"token\\" \\"0ad37941 8682 4894 b09d f3b8738d969e\\",\n \\"status\\" null\n}", "customlabel" "" }, { "id" "tivoqbuskgnrqallvndvq", "language" "401", "code" "{\n \\"code\\" \\"7001\\",\n \\"error\\" {\n \\"code\\" \\"500\\",\n \\"message\\" \\"no route found for subscription\\"\n }\n}\n\n{\n \\"code\\" \\"7001\\",\n \\"error\\" {\n \\"code\\" \\"500\\",\n \\"message\\" \\"invalid value for interval daily1\\"\n }\n}", "customlabel" "" } ], "selectedlanguageid" "vqyrchsr38ubbehatupjh" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "signature", "kind" "required", "type" "string", "description" "signature generated with sha256 followed by base64 encoding check below section for more details", "children" \[] }, { "name" "access token", "kind" "required", "type" "string", "description" "access token received from access token api you can reuse the access token across multiple api calls till it is expired", "children" \[] } ], "bodydataparameters" \[ { "name" "currencyid", "kind" "required", "type" "string", "description" "this will be provided by pay3 during onboarding", "" "this will be provided by pay3 during onboarding" }, { "name" "fiatamount", "kind" "required", "type" "string", "description" "amount user have to pay in string format maximum two decimal places are allowed", "" "amount user have to pay in string format maximum two decimal places are allowed" }, { "name" "paymentmethodid", "kind" "required", "type" "string", "description" "unique string identifier this will be provided by pay3 during onboarding ", "" "required" }, { "name" "email", "kind" "required", "type" "string", "description" "user email to identify the user, which will be available in reporting dashboard", "" "required" }, { "name" "userid", "kind" "required", "type" "string", "description" "it is a type of uuid it will used as unique identifier of the user if this is not passed, email will be used as a unique identifier of the user within pay3 ", "" "required" }, { "name" "clientid", "kind" "required", "type" "string", "description" "client id application's identifier", "children" \[] }, { "name" "requestid", "kind" "required", "type" "string", "description" "identifier that is created by client application's backend this will be passed in relevant events and webhooks from pay3 to application it is required to be globally unique example uuid ", "" "identifier that is created by client application's backend this will be passed in relevant events and webhooks from pay3 to application it is required to be globally unique example uuid " }, { "name" "interval", "kind" "required", "type" "string", "description" "defines the billing frequency for the subscription this value determines how often the recurring payment will be charged after the initial payment \n\nallowed values daily, weekly, monthly, yearly\n\nthe interval must match the subscription plan configured on pay3 any mismatch will result in request validation failure ", "" "required" }, { "name" "requestdescription", "kind" "required", "type" "string", "description" "the subscription plan name as displayed on the client’s ui this value is used by pay3 to identify and match the subscription plan associated with the request \n\nthe requestdescription must exactly match the plan name configured on the client side to ensure correct subscription mapping and recurring billing setup ", "" "required" }, { "name" "mode", "kind" "required", "type" "string", "description" "returnurl in this mode, the api returns a pay3 payment url that can be embedded directly into the client’s application this is useful when the client wants to open the pay3 url inside a wkwebview (ios), webview (android/react native), or an \<iframe> in a web app \n", "" "required" } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false } signature generation the request for creating checkout order requires a header signature this can be generated using following code snippet const crypto = require('crypto'); // required parameters const secretkey="api secret provided by pay3"; const fiatamount = "0 02"; const requestid = "order id generated by application"; const currencyid = "currency id"; const interval = "monthly"; const trialperioddays = "7"; const clientid = "your client id"; const accesstoken = "dynamic access token"; const getsignature = (secretkey, fiatamount, requestid) => { // prepare the string to sign in same format // currencyid, fiatamount, requestid and interval (if trialperioddays then add trialperioddays as well) let stringtosign = 'currencyid=' + currencyid + '\&fiatamount=' + fiatamount + '\&requestid=' + requestid + '\&interval=' + interval; if(trialperioddays && trialperioddays != "") { stringtosign = stringtosign + '\&trialperioddays=' + trialperioddays; } // generating signature using sha256 and provided secret and // base64 encode the result const mac = crypto createhmac('sha256', secretkey); return mac update(stringtosign) digest('base64'); } // generate signature const signature = getsignature(secretkey, fiatamount, requestid);