API Documentation
Create Checkout Order
3 min
this api creates a payin order to enable users to make checkout transactions 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 access token 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 prod pay3 app/v1/client/checkout/create order' \\\\\n header 'signature {{signature}}' \\\\\n header 'access token eyjrawqioiixymi5nja1yzm2zvrcwkjmohllmdrmcjbkceo2otm4njgzmdiwmmiyzcisinr5cci6ikpxvcisimfszyi6iljtmju2in0 eyjzdwiioiixy2vjogm3ys1knjmzltqzmdutymjkzi00n2m3zwjlywu1ymeilcjpc3mioijodhrwczovl3m4zxftbwe5zdguzxhly3v0zs1hcgkudxmtzwfzdc0xlmftyxpvbmf3cy5jb20vchjvzc92ms91c2vylw1hbmfnzw1lbnqvlndlbgwta25vd24vandrcy5qc29uiiwiawf0ijoxnzu2ndu2mtgxlcjlehaioje3nty0ntc5odf9 mzrmtnht4tsguqpv5p qfndlodyq12ootg hmb5nelsfpojiipmk2xz9rriqtvqg3uvxvzxdrl5vjksi9hbikcaj543fubjtesumfnygavbbrxcvki tuanwyzpi4gcjs7jd7va35afwbiec0spygn9quxhyiehu9n5u0 05kf11geda99hnchgsxkxyy0aofgwcdoietzighizjqqerzmnmr8ehuszzt7 uld2vrpj8oowrvdbhlbokickalnquzgrotwuqrpfmrrb5yrepicffjeyujzjtewunqh5m2oegzwutbzaxosdzda7uhmp7hfh5lm5whvmz6hr k8gndw' \\\\\n header 'content type application/json' \\\\\n data raw '{\n \\"currencyid\\" \\"inr in\\",\n \\"fiatamount\\" \\"10 00\\",\n \\"paymentmethodid\\" \\"all\\",\n \\"email\\" \\"ritik\@pay3 money\\",\n \\"clientid\\" \\"4894a422 1209 4371 9961 7e60008ec3e1\\",\n \\"requestid\\" \\"889938983\\",\n \\"mode\\" \\"returnurl\\",\n \\"callbackurl\\" \\"https //www google com\\"\n}'", "customlabel" "" } ], "selectedlanguageid" "nyfshp7j nrsuqth3fw7t" }, "results" { "languages" \[ { "id" "vqyrchsr38ubbehatupjh", "language" "200", "code" "{\n \\"requestid\\" \\"9824649238\\",\n \\"token\\" \\"a35dc551 9fb4 491c 9f9b 44d9c2ef4b32\\",\n \\"status\\" \\"created\\",\n \\"offerinfodata\\" {\n \\"useraddress\\" \\"user\@email com\\",\n \\"clientid\\" \\"your client id\\",\n \\"selectedpaymentmethod\\" \\"your paymentmethodid\\",\n \\"totalfiatamount\\" \\"1 00\\",\n \\"expiryts\\" \\"2025 04 21t16 12 09 287975+00 00\\",\n \\"currencyid\\" \\"your currency id\\",\n \\"type\\" \\"buy\\"\n }\n}", "customlabel" "" }, { "id" "tivoqbuskgnrqallvndvq", "language" "401", "code" "{\n error {\n code '7001',\n message 'order already exists for given requestid'\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" "email", "kind" "required", "type" "string", "description" "user email to identify the user, which will be available in reporting dashboard", "" "required" }, { "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" "clientid", "kind" "required", "type" "string", "description" "client id application's identifier", "children" \[] }, { "name" "paymentmethodid", "kind" "optional", "type" "string", "description" "unique string identifier this will be provided by pay3 during onboarding ", "" "optional" }, { "name" "userid", "kind" "optional", "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 ", "" "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 " }, { "name" "usermessage", "kind" "optional", "type" "string", "description" "short meaningful name of the asset user is about to purchase ", "" "short meaningful name of the asset user is about to purchase " }, { "name" "firstname", "kind" "optional", "type" "string", "description" "first name of the user with maximum length of 50 characters ", "" "first name of the user with maximum length of 50 characters " }, { "name" "lastname", "kind" "optional", "type" "string", "description" "last name of the user with maximum length of 50 characters ", "" "last name of the user with maximum length of 50 characters " }, { "name" "phonenumber", "kind" "optional", "type" "string", "description" "this is the phone number of the user in e 164 format \[+]\[country code]\[number including area code] which can have a maximum of fifteen digits ", "" "this is the phone number of the user in e 164 format \[+]\[country code]\[number including area code] which can have a maximum of fifteen digits " }, { "name" "mode", "kind" "optional", "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\nreturnappurl in this mode, the api will return supported android / ios application url this requires valid targetapp parameter in the body ", "" "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\nreturnappurl in this mode, the api will return supported android / ios application url this requires valid targetapp parameter in the body " }, { "name" "targetapp", "kind" "optional", "type" "string", "description" "this is required when the user chooses a perticular ios/android application to complete the payment ", "" "this is required when the user chooses a perticular ios/android application to complete the payment " }, { "name" "devicecontext", "kind" "optional", "type" "object", "description" "information about the mobile environment", "" "information about the mobile environment", "children" \[ { "name" "deviceos", "kind" "optional", "type" "string", "description" "android or ios" } ], "schema" \[ { "name" "deviceos", "kind" "optional", "type" "string", "description" "android or ios" } ] }, { "name" "pixkey", "kind" "optional", "type" "string", "description" "this is the unique identifier for a user in the pix system, provided by the user it can be an email address, phone number, cpf, or a random key ", "" "this is the unique identifier for a user in the pix system, provided by the user it can be an email address, phone number, cpf, or a random key " }, { "name" "intlbankaccount", "kind" "optional", "type" "string", "description" "this is the international bank account number (iban) entered by the user it follows the standard iban format, which includes the country code, check digits, and the bank account number ", "" "this is the international bank account number (iban) entered by the user it follows the standard iban format, which includes the country code, check digits, and the bank account number " }, { "name" "bankaccount", "kind" "optional", "type" "string", "description" "this is the bank account number entered by the user it is specific to the user's bank and is used to identify the user's account within the financial institution ", "" "this is the bank account number entered by the user it is specific to the user's bank and is used to identify the user's account within the financial institution " }, { "name" "doctype", "kind" "optional", "type" "string", "description" "this specifies the type of document, which for instance for brazil is cpf (cadastro de pessoas físicas) cpf is the brazilian individual taxpayer registry identification ", "" "this specifies the type of document, which for instance for brazil is cpf (cadastro de pessoas físicas) cpf is the brazilian individual taxpayer registry identification " }, { "name" "docid", "kind" "optional", "type" "string", "description" "this is the documentation id, entered by the user it corresponds to the specific identifier for the type of document (e g , cpf number) provided ", "" "this is the documentation id, entered by the user it corresponds to the specific identifier for the type of document (e g , cpf number) provided " }, { "name" "callbackurl", "kind" "optional", "type" "string", "description" "application can provide a url in this parameter after completion of the transaction, user will be redirected to this url an additional parameter data query parameter will be added to the url ", "" "application can provide a url in this parameter after completion of the transaction, user will be redirected to this url an additional parameter data query parameter will be added to the url " }, { "name" "lang", "kind" "optional", "type" "string", "description" "this parameter specifies the language preference for the pay3 sdk the strings used follow two letter language code as in iso 639 1 example pt for portuguese, en for english ", "" "this parameter specifies the language preference for the pay3 sdk the strings used follow two letter language code as in iso 639 1 example pt for portuguese, en for english " } ], "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 import javax crypto mac import javax crypto spec secretkeyspec class signature { fun getpay3signature(secretkey string, requestid string, fiatamount string, currencyid string) string { return try { val stringtosign = "currencyid=$currencyid\&fiatamount=$fiatamount\&requestid=$requestid" val mac = mac getinstance("hmacsha256") val secretkeyspec = secretkeyspec(secretkey tobytearray(), "hmacsha256") mac init(secretkeyspec) val hash = mac dofinal(stringtosign tobytearray(charsets utf 8)) base64 getencoder() encodetostring(hash) } catch (e exception) { throw runtimeexception("error generating signature", e) } } }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 clientid = "your client id"; const accesstoken = "dynamic access token"; const getsignature = (secretkey, fiatamount, requestid) => { // prepare the string to sign in same format // fiatamount followed by requestid const stringtosign = 'fiatamount=' + fiatamount + '\&requestid=' + requestid; // 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);