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);