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 android sdk this api requires access token that can be generated using access token docid\ gi jr7m modsx5dxyfrw 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 your hostname pay3 app v1 client checkout create order n header signature generated signature n header access token dynamic access token n header accept application json n header content type application json n data n requestid input request id n currencyid currency id n fiatamount input amount n clientid your client id n paymentmethodid your paymentmethod id n email user email n customlabel selectedlanguageid nyfshp7j nrsuqth3fw7t results languages id vqyrchsr38ubbehatupjh language 200 customlabel 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 id tivoqbuskgnrqallvndvq language 401 customlabel code n error n code 7001 n message order already exists for given requestid n n 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 unique string identifier this will be provided by pay3 during onboarding 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 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 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);