# Get Payout Preview (Phase 2a) Before submitting a sell payout, call this endpoint to discover which beneficiary fields are required for the destination currency and country. The response contains dynamic form field definitions that your frontend should render for the customer to fill in. ## Request ### Headers :::note Public Endpoint This endpoint does not require authentication headers. ::: ### Query Parameters :::caution Prerequisite The crypto deposit for this intent must be in `confirmed` or `matched` status. If the deposit hasn't been confirmed yet, this endpoint returns a `400` error. ::: ## Response ### Success (200 OK) ```json { "success": true, "data": { "selectedTsp": "zenpay_routing", "tspDisplayName": "ZenPays", "requiredFields": [ { "fieldName": "receiverFirstName", "label": "First Name", "type": "text", "required": true, "placeholder": "Enter first name" }, { "fieldName": "receiverLastName", "label": "Last Name", "type": "text", "required": true, "placeholder": "Enter last name" }, { "fieldName": "receiverAccountNumber", "label": "Account Number", "type": "text", "required": true, "placeholder": "Enter account number" }, { "fieldName": "receiverCountry", "label": "Country", "type": "text", "required": true, "placeholder": "ISO country code (e.g. US)" }, { "fieldName": "receiverBankName", "label": "Bank Name", "type": "text", "required": true, "placeholder": "Enter bank name" } ], "optionalFields": [ { "fieldName": "receiverEmail", "label": "Email", "type": "email", "required": false, "placeholder": "Enter email address" }, { "fieldName": "receiverPhone", "label": "Phone", "type": "tel", "required": false, "placeholder": "Enter phone number" } ], "oneOfGroups": [ ["receiverBankCode", "receiverBankName"] ], "fiatAmount": 19.78, "fiatCurrency": "USD", "fees": { "platform": 0.62, "network": 0, "total": 0.62 } }, "message": "Payout preview retrieved" } ``` ### Response Fields ### Field Definition Object ### Fees Object :::tip Dynamic Form Rendering Use the `requiredFields` and `optionalFields` arrays to dynamically build your payout form. Each field includes validation constraints (`pattern`, `minLength`, `maxLength`) so you can validate client-side before submitting. For `oneOfGroups`, at least one field from each group must be provided. For example, `["receiverBankCode", "receiverBankName"]` means you need either the SWIFT/BIC code or the bank name. ::: ### Error Responses ## Examples ```bash curl "https://api.zenpayz.com/payment/api/v1/off-ramp/sell/payout-preview?intentId=ri_1710345678000_a1b2c3d4e5f6g7h8&fiatCurrency=USD&country=US" ``` ```javascript const params = new URLSearchParams({ intentId: 'ri_1710345678000_a1b2c3d4e5f6g7h8', fiatCurrency: 'USD', country: 'US', }); const response = await fetch( `https://api.zenpayz.com/payment/api/v1/off-ramp/sell/payout-preview?${params}` ); const { data } = await response.json(); console.log(`Provider: ${data.tspDisplayName}`); console.log(`Payout: ${data.fiatAmount} ${data.fiatCurrency}`); console.log(`Fees: ${data.fees.total}`); // Dynamically render form fields data.requiredFields.forEach((field) => { const input = document.createElement('input'); input.name = field.fieldName; input.placeholder = field.placeholder; input.type = field.type; input.required = field.required; if (field.pattern) input.pattern = field.pattern; document.getElementById('payout-form').appendChild(input); }); ``` ```python import requests response = requests.get( "https://api.zenpayz.com/payment/api/v1/off-ramp/sell/payout-preview", params={ "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "fiatCurrency": "USD", "country": "US", }, ) data = response.json()["data"] print(f"Provider: {data['tspDisplayName']}") print(f"Payout: {data['fiatAmount']} {data['fiatCurrency']}") print(f"Fees: {data['fees']['total']}") print("\nRequired fields:") for field in data["requiredFields"]: print(f" - {field['label']} ({field['fieldName']}): {field['type']}") ``` ## Next Steps - [Submit Sell Payout](/docs/rest-api/endpoints/ramp/sell-payout) — Submit beneficiary details and trigger payout (Phase 2b) - [Create Sell Deposit](/docs/rest-api/endpoints/ramp/sell-deposit) — Generate deposit address (Phase 1) - [Off-Ramp Flow](/docs/examples/off-ramp-flow) — Complete sell integration guide