API Documentation
Create Fiat Payout Order
2 min
this api creates a payout order to enable users to withdraw funds 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 docid\ wr9g8 0vvao95lsm3g1ye this api requires access token that can be generated using docid\ lq v6ff 2i h1o3xd5kka api note actual response may change based on partner integration { "name" "create fiat payout order", "method" "post", "url" "https //your hostname pay3 app/v1/client/payout/create order", "description" "create an order with payout details from application's backend", "tab" "examples", "examples" { "languages" \[ { "id" "exhyhl9rwxfgu lg6oq1q", "language" "curl", "code" "curl location 'https //your hostname pay3 app/v1/client/payout/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 \\"currencyid\\" \\"currency id\\",\n \\"fiatamount\\" \\"0 02\\",\n \\"requestid\\" \\"9824649238\\",\n \\"paymentmethodid\\" \\"payment method id\\",\n \\"email\\" \\"user\@address com\\",\n \\"clientid\\" \\"your client id\\",\n \\"firstname\\" \\"john\\",\n \\"lastname\\" \\"doe\\",\n \\"taxid\\" \\"tax id\\"\n}'", "customlabel" "" } ], "selectedlanguageid" "exhyhl9rwxfgu lg6oq1q" }, "results" { "languages" \[ { "id" "vqyrchsr38ubbehatupjh", "language" "200", "code" "{\n \\"requestid\\" \\"3966274f f8b2 4992 9313 56962699b2fa\\",\n \\"token\\" \\"f52d592a a67a 4037 b8a2 8b7020332c6d\\",\n \\"url\\" null,\n \\"warning\\" \\"the payout account balance (999999999992444999 55) is below the configured threshold (999999999992549599 55) \\",\n \\"verificationdetails\\" {\n \\"isverificationenabled\\" true,\n \\"isverified\\" true,\n \\"fullname\\" \\"john doe\\",\n \\"accountnumber\\" \\"xxxxxx8292\\",\n \\"bankname\\" \\"bank bri\\",\n \\"message\\" \\"account verified\\"\n \\"fullname\\" \\"john doe\\",\n \\"pixkey\\" \\"user\@address com\\"\n }\n}\n", "customlabel" "" }, { "id" "66dvgm2ssfyrrj4nnmnj1", "language" "400", "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" "requestid", "kind" "required", "type" "string", "description" "identifier that is created by application's backend this will be passed in relevant events and webhooks from pay3 to application", "children" \[] }, { "name" "currencyid", "kind" "required", "type" "string", "description" "currency id supported in the payout flow this will be provided by pay3 during onboarding" }, { "name" "fiatamount", "kind" "required", "type" "string", "description" "amount user can withdraw in string format maximum two decimal places are allowed", "children" \[] }, { "name" "paymentmethodid", "kind" "required", "type" "string", "description" "unique string identifier this will be provided by pay3 during onboarding ", "children" \[] }, { "name" "clientid", "kind" "required", "type" "string", "description" "client id application's identifier", "children" \[] }, { "name" "email", "kind" "required", "type" "string", "description" "user email to identify the user, which will be available in reporting dashboard", "children" \[] }, { "name" "taxid", "kind" "required", "type" "string", "description" "tax id issued to the user by their country", "" "required" }, { "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" "firstname", "kind" "optional", "type" "string", "description" "optional first name of the user", "children" \[] }, { "name" "lastname", "kind" "optional", "type" "string", "description" "optional last name of the user", "children" \[] }, { "name" "pixkey", "kind" "optional", "type" "string", "description" "pix key is a unique identifier that links to a brazilian user’s bank account and determines where the funds will be received ", "children" \[] }, { "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 \n\ncreateverify in this mode, the api does not generate any website url or ui instead, it returns the verification details required by the downstream partner these fields allow the partner to verify the beneficiary and then process the payout directly based on the verified information ", "" "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 \n\ncreateverify in this mode, the api does not generate any website url or ui instead, it returns the verification details required by the downstream partner these fields allow the partner to verify the beneficiary and then process the payout directly based on the verified information " }, { "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 ", "" "callbackurl" }, { "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 ", "" "lang" } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "response" \[ { "name" "requestid", "kind" "optional", "type" "string", "description" "identifier that is created by application's backend this will be passed in relevant events and webhooks from pay3 to application" }, { "name" "token", "kind" "optional", "type" "string", "description" "a unique token returned after creating the payout/verification order this token must be passed to the execute api to complete the processing flow ", "children" \[] }, { "name" "url", "kind" "optional", "type" "string", "description" "returned only when the mode supports ui flow (mode = returnurl) when no ui is required (mode = createverify) this field will be null ", "children" \[] }, { "name" "warning", "kind" "optional", "type" "string", "description" "may provide additional information or caution related to the payout session, eg payout wallet balance is lesser than threshold ", "children" \[] }, { "name" "verificationdetails", "kind" "optional", "type" "object", "description" "this block contains the results of the beneficiary verification process, including indicators of whether verification is required and completed, along with the validated user information returned by the downstream partner ", "children" \[ { "name" "isverificationenabled", "kind" "optional", "type" "boolean", "description" "indicates whether verification is required for this transaction flow based on configuration or partner rules " }, { "name" "isverified", "kind" "optional", "type" "boolean", "description" "shows whether the user’s account or payment details have been successfully verified by the downstream partner " }, { "name" "fullname", "kind" "optional", "type" "string", "description" "the full verified name of the user returned by the partner " }, { "name" "pixkey", "kind" "optional", "type" "string", "description" "the verified pix key associated with the user " }, { "name" "accountnumber", "kind" "optional", "type" "string", "description" "a masked version of the verified account number returned by the partner " }, { "name" "bankname", "kind" "optional", "type" "string", "description" "the name of the bank with which the user’s payment account is registered " }, { "name" "message", "kind" "optional", "type" "string", "description" "a partner provided message summarizing the verification outcome (e g , \\"account verified\\") " } ] } ] } signature generation the request for creating payout order requires a header signature this can be generated using following javascript code snippet const crypto = require('crypto'); // required parameters const secretkey="api secret provided by pay3"; const currencyid = "currency id"; const fiatamount = "0 02"; const requestid = "order id generated by application"; const clientid = "your client id"; const accesstoken = "dynamic access token"; const getsignature = (secretkey, currencyid, fiatamount, requestid) => { // prepare the string to sign in same format // currencyid followed by fiatamount followed by requestid const stringtosign = 'currencyid=' + currencyid + '\&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, currencyid, fiatamount, requestid);