--- page_source: https://docs.juspay.io/payout-brazil/docs/integration/order-create page_title: Order Create --- ## API Version: default # Order Create API is used to create a payout request with Juspay for account , Tokenized Card (Juspay as token requestor), Wallet, and Beneficiary ID based payouts## Endpoints: - Sandbox: https://api.sandbox.juspay.io/payout/merchant/v1/orders - Production: https://api.juspay.io/payout/merchant/v1/orders ## Request Type: POST ## Authorization: #### Basic Auth: Consists of two parts. * Username: API Key obtained from Juspay dashboard * Password: Empty string - Value: Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg== - Tags: String, Mandatory ## Headers: #### x-merchantid: Pass merchant-id provided by Juspay - Tags: string #### Content-Type: application/json - Tags: String ## Sample Code Snippets: ### Sample Request: #### Wallet Code Snippet: ```wallet curl --location --request POST 'https://api.juspay.io/payout/merchant/v1/orders' \ --header 'Content-Type: application/json' \ --header 'x-merchantid: ' \ --header 'Authorization: Basic (b64 encoded API key)' \ --data-raw '{ "orderId": "ONaajHngrONssVSu", "fulfillments": [ { "amount": 1, "beneficiaryDetails": { "details": { "walletIdentifier" : "dummy@email.com", "brand" : "PAGBANK", "payeeAdditionalDetails" : { "documents" : [ { "docId" : "853.513.468-93", "docType" : "CNPJ" } ], "country" : "BRA", "name" : "Tushar" } }, "type": "WALLET" }, "additionalInfo" : { "transactionType" : "B2C" }, "fulfillmentCurrency" : "BRL" } ], "amount": 1, "customerId": "dsgsdgfsdgfsg", "customerPhone": "11987654321", "customerEmail": "name@gmail.com", "type": "FULFILL_ONLY" }' ``` #### Bank Transfer Code Snippet: ```bank transfer curl --location 'https://api.sandbox.juspay.io/payout/merchant/v1/orders' \ --header 'Content-Type: application/json' \ --header 'x-merchantid: ' \ --header 'Authorization: Basic Basic (b64 encoded API key)' \ --data-raw '{ "orderId": "123456789", "fulfillments": [ { "amount": 1, "fulfillmentCurrency": "BRL", "beneficiaryDetails": { "details": { "firstName": "Aniket", "lastName": "Dimri", "bankCountryCode": "BRA", "payeeAccountIdentifier": "+5511995904440", "transferType" : "LOCAL", "payoutMode" : "PIX", "payeeAdditionalDetails" : { "documents" : [ { "docId" : "853.513.468-93", "docType" : "CPF" } ] } }, "type": "BANK_TRANSFER" } } ], "amount": 1, "customerId": "cth_59Yibs1JauYP6WJP", "customerPhone": "923+999999999", "customerEmail": "test@gmail.com", "type": "FULFILL_ONLY" }' ``` ### Sample Response: #### Wallet: ```json { "type": "FULFILL_ONLY", "status": "READY_FOR_FULFILLMENT", "payments": [], "orderId": "ONaajHngrONssVSu", "fulfillments": [ { "updatedBy": "DEFAULT", "updatedAt": "2024-11-13T12:33:38Z", "type": "ORDER", "statusUpdatedAt": "2024-11-13T12:33:38Z", "status": "CREATED", "id": "43795f01ccc402a9848313ee0101c2-f1", "fulfillmentMethodList": [], "fulfillmentCurrency": "BRL", "createdAt": "2024-11-13T12:33:38Z", "beneficiaryDetails": { "details": { "walletIdentifier": "duXXXXXXXXXXXXom", "payeeAdditionalDetails": { "name": "TuXXar", "documents": [ { "docType": "CPF", "docId": "853.XXXXX8-93" } ], "country": "BRA" }, "brand": "PAGBANK" }, "type": "WALLET" }, "amount": 1, "additionalInfo": { "transactionType": "B2C" } } ], "customerId": "dsgsdgfsdgfsg", "amount": 1, "udf1": "udf1", "udf2": "udf2", "udf3": "udf3", "udf4": "udf4", "udf5": "udf5" } ``` #### BANK TRANSFER: ```plaintext { "updatedAt": "2025-02-14T05:02:17Z", "type": "FULFILL_ONLY", "status": "FULFILLMENTS_SUCCESSFUL", "orderId": "123456789", "fulfillments": [ { "updatedBy": "DEFAULT", "updatedAt": "2025-02-14T05:02:17Z", "type": "ORDER", "transactions": [ { "updatedAt": "2025-02-14T05:02:06Z", "txnResponse": { "transactions": [ { "type": "CREDIT", "timestamp": "2025-02-14T05:01:40Z", "state": "AXXXXXXD", "resultCode": 0, "responseText": "Success.", "gatewayProvidedId": "e87280e2-ade4-4800-8b84-e71309232d44", "currency": "BRL", "amount": 1 } ], "status": "CREDITED", "properties": { "INFINIA_TXN_ID": "cbralwnvvdvpqfalytki" }, "paymentType": "WALLET", "paymentMethod": "PIX", "merchantAccount": "JuspayM1", "lineItem": { "taxIncludedInPrice": true, "taxCode": "NT", "description": "PAYOUT", "currency": "BRL", "amount": 1 }, "internalId": "12906148755152896", "id": "32XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXt1", "created": "2025-02-14T05:01:40Z", "amountRemaining": 0 }, "transactionRef": "04d7330cc964d9cbb2f61771623858", "timeStamp": "2025-02-14T05:02:06Z", "status": "SUCCESS", "responseMessage": "CREDITED", "responseDescription": "CREDITED", "responseCode": "CREDITED", "fulfillmentMethod": "PAYAMIGO_BT", "epgTxnId": "32951aa1c484016abdb139d28f3243-f1-t1", "createdAt": "2025-02-14T05:01:39Z", "amount": 1 } ], "statusUpdatedAt": "2025-02-14T05:02:17Z", "status": "SUCCESS", "preferredMethodList": [ "PAYAMIGO_BT" ], "merchantCustomerId": "cth_59Yibs1JauYP6WJP", "id": "32951aa1c484016abdb139d28f3243-f1", "fulfillmentMethodList": [ "PAYAMIGO_BT" ], "fulfillmentCurrency": "BRL", "createdAt": "2025-02-14T05:01:39Z", "beneficiaryDetails": { "details": { "transferType": "LOCAL", "payoutMode": "PIX", "payeeAdditionalDetails": { "documents": [ { "docType": "CPF", "docId": "853.XXXXXX8-93" } ] }, "payeeAccountIdentifier": "+5511995904440", "lastName": "Dimri", "firstName": "Aniket", "bankCountryCode": "BRA" }, "type": "BANK_TRANSFER" }, "amount": 1 } ], "customerId": "cth_59Yibs1JauYP6WJP", "createdAt": "2025-02-14T05:01:39Z", "amount": 1 } ``` ## Body Parameters: ### Parameters: #### orderId: - Description: Unique Reference for the order. This will be the ID for any subsequent communications. orderId can contain alphanumeric values. It can also contain special characters _ , - and @ - Tags: string, Mandatory, Min Length : 4 , Max Length : 64 #### amount: - Description: Total order amount - Tags: Double, Mandatory #### customerId: - Description: Unique ID for the customer generated by the merchant. For BENE ID payouts please use same customer ID passed while creating / validating beneficiary. - Tags: string, Mandatory, Max Length : 64 #### customerPhone: - Description: Customer mobile number - If the actual number is unavailable, you may use a placeholder or dummy value. The number should contain only the digits without any country code or special characters.  For instance, a valid entry for a Brazilian phone number would be: 4112345678. - Tags: string, Mandatory #### customerEmail: - Description: Customer email address - you may pass a dummy value in case this information is not available at your endFor example, example@mail.com, "example" is the email prefix, and "mail.com" is the email domain. - Tags: string, Mandatory #### type: - Description: Pass FULFILL_ONLY for payout order creation - Tags: string, Mandatory #### fulfillments: - Description: fulfilment related details - Value: - **PreferredMethodList**: - Description: This will define the list of methods to be used for fulfillments for instance -[“EBANX_WALLET”, PAYPAL_WALLET”, “PAGSEGURO_WALLET”, ”TAZAPAY_BT”]  preferredMethodList carries a higher priority than distribution logic set on Juspay dashboard. This is an optional param and should be used only in case of unique routing requirements If you have gatewayReferenceId then you have pass in array like  “EBANX_WALLET.gatewayReferenceId” - Tags: array - **Amount**: - Description: Amount to be processed for the particular fulfillment. Sum of all the fulfilment amount should be equal to order amount - Tags: Double, Mandatory - **BeneficiaryDetails**: - Value: - **Type**: - Description: Pass “**WALLET** ”, “**BANK_TRANSFER** “ based on required method **WALLET** for transfer to Mercadopago, PAGBANK and Paypal Wallet Id**BANK_TRANSFER** is used when you have TAXID (CPF), BANK TRANSFER, and PIX TRANSFER . - Tags: String, Mandatory - **Details**: - Value: - **WalletIdentifier**: - Description: Value related to beneficiary’s brand you are selecting.Required in case of Wallet only. Example :-  **Brand WalletIdentifier** MERCADOPAGO [your@email.com](mailto:your@email.com) - Tags: String - **Brand**: - Description: Brand name of the walletRequired in case of Wallet only.Values :- MERCADOPAGO | PAGBANK | PAYPAL | VENMO MERCADOPAGO, used for EbanxPAYPAL used for PaypalPAGBANK used for PagseguroVENMO used for Venmo - Tags: String - **PayeeAdditionalDetails**: - Value: - **Documents**: - Description: An array containing the object of beneficiary’s national identification Number along with its type. * **docId** (string): The beneficiary’s national identification number. * **docType** (string): The type of the national identification number. * **Values** : CPF | CNPJ CPF is 11 digit number formatted asFormat for CPF : XXX.XXX.XXX-XXCNPJ is 14 digit number formatted asFormat for CNPJ: XX.XXX.XXX/XXX-XXexample :- [ { "**docId** " : "853.513.468-93", "d**ocType** " : "CPF" } ][ { "**docId** " : "00.623.904/0001-73", "d**ocType** " : "CNPJ" } ] - Tags: Array, Required - **PayeeType**: - Description: Pass the type of payee**Values:** business or individual - Tags: String - Tags: Object - **BankCountryCode**: - Description: Provide bank country code.Mandatory in case of BANK_TRANSFER - Tags: String - **FirstName**: - Description: Provide your payee First nameMandatory for PAYAMIGOS - Tags: String - **LastName**: - Description: Provide your payee Last nameMandatory for PAYAMIGOS - Tags: String - **PayoutMode**: - Description: Rail to be used for the domestic or international payoutCurrent Available Mode : **PIX** Required in case of **BANK_TRANSFER** - Tags: String, Tag, Required - **TransferType**: - Description: Denotes the type of the transfer - whether local or internationalValues : LOCAL , INTERNATIONALLocal denotes the transfer is a domestic transaction while international denotes the transfer is a cross border transaction Required in **BANK_TRANSFER** - Tags: String, Required - **PayeeAccountIdentifier**: - Description: Provide the account identifier of the payee’s bank account.Required in case of **BANK TRANSFER** _In case of PIX all the valid PIX values can be passed in this field_ - Tags: String - **WalletIdentifierType**: - Description: Brand Type name of the walletRequired in case of Wallet only.Values :- PAYPAL_ID | EMAIL | PHONE | VENMO_IDPAYPAL_ID | EMAIL | PHONE —> For PaypalEMAIL | PHONE | VENMO_ID —> For Venmo - Tags: String - Tags: Object, Required - Tags: object, Required - **Udf1-5**: - Description: Fulfillment level user defined fields. These fields can be used for analytics and routing of fulfillment of the order - Tags: String - **AdditionalInfo**: - Value: - **Remark**: - Description: The parameter will be passed as narration to the downstream gateways (if supported) - Tags: String - **ScheduleTime**: - Description: Time at which fulfillment should be attempted by Juspay - Tags: String - **AttemptThreshold**: - Description: Merchants can use this field to set custom attempt threshold for an order - Tags: Integer - **TransactionType**: - Description: Value :- B2B or B2C - Tags: String - **WebhookDetails**: - Description: Merchants can provide dynamic webhook URL for the order if required - Value: - **Url**: - Description: https URL corresponding to webhook endpoint to which webhook events should be triggered for this order - Tags: String - **Username / password**: - Description: Input values of username and password in corresponding fields. Base 64 encoded value of username:password will be sent as Authorization for webhook - Tags: String - **CustomHeader**: - Description: Merchant can pass custom header if required for webhook to be triggered - Tags: String - Tags: Object - **PayoutMethodType**: - Description: This is specific to PayPal.To create a beneficiary of type _WALLET_ for PayPal, you can use either the beneficiary creation API or the LinkWallet API. While you can choose **EMAIL** or **PAYPAL_ID** as the primary payout method, payouts can still be processed with either option by updating the value in the field as needed. - Tags: String - Tags: Object - **FulfillmentCurrency**: - Description: values are ISO 4217 Standard.Example :- ARS, BRL, CLP, COP, MXN, BOB, CRC, PYG, PEN, UYU, DOP, KES, ZAR, MAD, EGP, INR, IDR, NGN, USD Max length = 3 - Tags: String, Mandatory - **SourceCurrency**: - Description: values are ISO 4217 Standard.Example :- ARS, BRL, CLP, COP, MXN, BOB, CRC, PYG, PEN, UYU, DOP, KES, ZAR, MAD, EGP, INR, IDR, NGN, USD Max length = 3 - Tags: String - Tags: object, Required #### udf1-5: - Description: Order level user defined field. Field can be used for analytics. - Tags: string ## API Responses: ### 200: #### 200 : Payout Response: - Value: - **Type**: - Description: Payout type passed in order create request - Value: FULFILL_ONLY - Tags: String - **Status**: - Description: Relays the current status of order created at Juspay end - Value: READY_FOR_FULFILLMENT - Tags: String - **Orderid**: - Description: orderId passed during order creation - Value: 1703593449 - Tags: String - **Fullfilments**: - Value: - **Amount**: - Description: Amount passed in the fulfillment block - Value: 1.0 - Tags: String - **UpdatedBy**: - Description: Medium via which payout status was updated. Will be DEFAULT in response of create order - Value: DEFAULT - Tags: String - **UpdatedAt**: - Description: Timestamp at which fulfillment payload was last updated at Juspay end - Value: 2023-12-23T16:54:27Z - Tags: String - **Udf1-5**: - Description: Fulfillment level user defined fields passed in order creation request - Tags: String - **Status**: - Description: Relays the current status of fulfillment created at Juspay end - Value: CREATED - Tags: String - **PreferredMethodList**: - Description: Array passed during order create for preferredMethodList - Value: DUMMY_IMPS - Tags: Array of Strings - **Id**: - Description: Fulfilment ID created by Juspay for fulfillment payload received in order create request - Value: 25cbcf3454a445789309dc0b54e681-f1 - Tags: String - **StatusUpdatedAt**: - Description: Timestamp at which status of fulfillment was updated at Juspay end - Value: 2023-12-26T12:24:08Z - Tags: String - **BeneficiaryDetails**: - Description: Beneficiary details provided in order create by merchant - Tags: Object - **Type**: - Description: Payout type initiated by merchant - Value: BENE_ID | WALLET | BANK_TRANSFER - Tags: String - **AdditionalInfo**: - Description: Additional Information sent by merchant in create order request - Tags: Object - Tags: Array - **CustomerId**: - Description: Customer ID passed during order creation - Value: cth_59Yibs1JauYP6WJP - Tags: String - **Amount**: - Description: Amount passed for the order - Value: 1.0 - Tags: String - **Udf1-5**: - Description: Order level udfs passed in order create request - Tags: String - Tags: Object ### 400: #### error: - Description: Boolean reflecting error in request of create order API - Value: true - Tags: Boolean #### errorCode: - Description: Error code provided by Juspay - Value: E01 - Tags: String #### errorMessage: - Description: Error message provided by Juspay. Share this message with Juspay POC for debugging - Value: Amount0.0 cannot be less than 1.0Amount0.0 cannot be less than 1.0 - Tags: String #### userMessage: - Description: Error message that will be shown on dashboard / analytics - Tags: String ### 401: #### error: - Description: Boolean reflecting error in request of create order API - Value: true - Tags: String #### errorCode: - Description: Error code provided by Juspay - Value: E02 - Tags: String #### errorMessage: - Description: Error message provided by Juspay. Share this message with Juspay POC for debugging - Value: Invalid API key passed in request. - Tags: String #### userMessage: - Description: Error message that will be shown on dashboard / analytics - Value: Invalid API Key - Tags: String, Mandatory