# Request crypto payment ## Initiate a payment request ## Request crypto payment > An endpoint for initiating a crypto payment request. Upon success, a unique \`paymentUrl\` is provided in the response which can be served within an iframe.\ > \ > Alternatively, you can redirect to the payment URL and if you have supplied a \`redirectUrl\` in the request, we will navigate the end-user back to your website upon payment completion (when we have received a deposit against this payment request). There is also a button which the end-user can use if they wish to get redirected back sooner. ```json {"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://api.finrax.com","description":"Generated server url"}],"security":[{"ApiKeyAuth":["CREATE_PAYMENT"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"^FRX-API api-key=[^,]+,signature=[^,]+,timestamp=[\\d]+$","name":"Authorization","in":"header"}},"schemas":{"CreatePaymentRequest":{"required":["businessId","clientPaymentId","locale"],"type":"object","properties":{"clientPaymentId":{"type":"string","description":"Payment identifier provided in the request."},"businessId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["ONE_TIME","REUSABLE"]},"displayCurrency":{"type":"string","description":"Fiat currency. You should provide this or `depositCurrency`.","enum":["AED","ARS","AUD","BDT","BGN","BRL","CAD","CHF","CLP","CNY","CZK","DKK","EUR","GBP","HKD","HRK","HUF","IDR","ILS","INR","ISK","JPY","KES","KRW","MXN","MYR","NOK","NZD","PEN","PHP","PLN","QAR","RON","SEK","SGD","THB","TRY","USD","VND","ZAR"]},"displayAmount":{"type":"string","description":"Amount in `displayCurrency` that the user wants to deposit. Required if `displayCurrency` is provided."},"depositCurrency":{"type":"string","description":"Cryptocurrency. You should provide this or `displayCurrency`.","enum":["BCH","BTC","ETH","LINK","LTC","SOL","USDC","XLM","XRP"]},"depositAmount":{"type":"string","description":"Amount in `depositCurrency` that the user wants to deposit. Required if `depositCurrency` is provided."},"network":{"type":"string","description":"Cryptocurrency network. Required if `depositCurrency` is provided.","enum":["BCH","BTC","LTC","XLM","XRP","ETH","BSC","SOL","TRX"]},"rateType":{"type":"string","description":"- `ONE_TIME` payments: `FIXED` or `FLOATING`.\n- `REUSABLE` payments: You can omit this parameter. Reusable payments are set to `FLOATING`.","enum":["FIXED","FLOATING"]},"expirationMinutes":{"minimum":0,"type":"integer","description":"- `ONE_TIME` payments: Indicates the timeframe in which the deposit should happen. A value of 0 will set the payment expiry to 7 days. Defaults to 30 min.\n- `REUSABLE` payments: You can omit this parameter. Reusable payments are set to non-expiry.","format":"int64"},"locale":{"type":"string","description":"IETF BCP 47 language tag, e.g. 'en-US', 'fr-FR'.\nAlternatively, the locale string can be submitted with an '_' instead of '-', e.g. 'en_US' or 'fr_FR' or as an ISO 639-1 language code, e.g. 'en' or 'fr'.\nSupported languages:\n- Arabic (ar)\n- Bulgarian (bg)\n- Chinese (zh)\n- English (en)\n- French (fr)\n- German (de)\n- Japanese (ja)\n- Lithuanian (lt)\n- Portuguese (pt)\n- Russian (ru)\n- Spanish (es)\n- Turkish (tr)"},"redirectUrl":{"type":"string","description":"Custom URL where the user will be redirected after payment completion."},"redirectMode":{"type":"string","description":"Specifies how to open the redirect URL\n- `PARENT` (default): Opens the redirect URL in the parent browsing context. Refers to HTML anchor target attribute value `_top`.\n- `SELF`: Opens the redirect URL in the current browsing context. Refers to HTML anchor target attribute value `_self`.","enum":["PARENT","SELF"]}}},"CreatedPaymentResponse":{"type":"object","properties":{"paymentInfo":{"$ref":"#/components/schemas/DetailedPaymentResponse"},"paymentUrl":{"type":"string","format":"url"}}},"DetailedPaymentResponse":{"required":["actualDepositAmount","actualDepositDistributedUserServiceFee","actualDisplayAmount","actualDisplayDistributedUserServiceFee","actualUniformAmount","businessId","clientPaymentId","deposits","expirationMinutes","locale","paymentId","paymentInitiatedAt","processorType","rateType","status","type","url","userServiceFeeDistributionPercentage"],"type":"object","properties":{"paymentId":{"type":"string","format":"uuid"},"clientPaymentId":{"type":"string","description":"Payment identifier provided by the merchant on payment creation."},"businessId":{"type":"string","format":"uuid"},"locale":{"type":"string","description":"Locale code."},"status":{"type":"string","enum":["NEW","PENDING","AWAITING","DEPOSITED","EXPIRED","BLOCKED","OVERPAID","UNPROCESSABLE","FAILED"]},"rateType":{"type":"string","enum":["FIXED","FLOATING"]},"type":{"type":"string","enum":["ONE_TIME","REUSABLE"]},"url":{"type":"string","description":"Checkout link.","format":"url"},"overpaymentPolicy":{"type":"string","enum":["PROCESS","EXCESS_REFUND"]},"refundFollowUpDepositsForOneTimePayments":{"type":"boolean"},"processorType":{"type":"string","deprecated":true,"enum":["BLOCKCHAIN"]},"walletAddress":{"type":"string","description":"Wallet address where the cryptocurrency amount should be deposited."},"destinationTag":{"type":"string","description":"XLM/XRP destination tag."},"displayCurrency":{"type":"string","description":"Fiat currency.","enum":["AED","ARS","AUD","BDT","BGN","BRL","CAD","CHF","CLP","CNY","CZK","DKK","EUR","GBP","HKD","HRK","HUF","IDR","ILS","INR","ISK","JPY","KES","KRW","MXN","MYR","NOK","NZD","PEN","PHP","PLN","QAR","RON","SEK","SGD","THB","TRY","USD","VND","ZAR"]},"expectedDisplayAmount":{"type":"string","description":"Amount in `displayCurrency` requested for this payment."},"expectedDisplayDistributedUserServiceFee":{"type":"string","description":"Distributed service fee amount in `displayCurrency` requested for this payment."},"actualDisplayAmount":{"type":"string","description":"Actual amount deposited in `displayCurrency`."},"actualDisplayDistributedUserServiceFee":{"type":"string","description":"Actual distributed service fee amount in `displayCurrency`."},"depositCurrency":{"type":"string","description":"The selected cryptocurrency.","enum":["BCH","BTC","ETH","LINK","LTC","SOL","USDC","XLM","XRP"]},"expectedNetwork":{"type":"string","description":"The selected network.","enum":["BCH","BTC","LTC","XLM","XRP","ETH","BSC","SOL","TRX"]},"expectedDepositAmount":{"type":"string","description":"Amount in `depositCurrency` to be deposited to fulfill the required amount in `displayCurrency`."},"expectedDepositDistributedUserServiceFee":{"type":"string","description":"Distributed service fee amount in `depositCurrency` requested for this payment."},"actualDepositAmount":{"type":"string","description":"Deprecated. Actual amount deposited by the end user. The actual currency may be different than `depositCurrency`. For actual amount and currency use the nested `deposits`.","deprecated":true},"actualDepositDistributedUserServiceFee":{"type":"string","description":"Actual distributed service fee amount in `depositCurrency`."},"expectedUniformAmount":{"type":"string","description":"Expected deposit amount in EUR."},"actualUniformAmount":{"type":"string","description":"Actual amount deposited in EUR."},"userServiceFeeDistributionPercentage":{"type":"string","description":"Percentage of the service fee covered by the user."},"redirectUrl":{"type":"string","description":"Custom URL where the user will be redirected after payment completion.","format":"url"},"redirectMode":{"type":"string","description":"Specifies how to open the redirect URL","enum":["PARENT","SELF"]},"expirationMinutes":{"minimum":0,"type":"integer","description":"Timeframe in which the deposit should succeed.","format":"int64"},"initiatedBy":{"type":"string","description":"The initiator of this payment."},"paymentInitiatedAt":{"type":"integer","description":"UNIX seconds at which the payment was initiated.","format":"int64"},"paymentRequestedAt":{"type":"integer","description":"UNIX seconds at which the payment was requested.","format":"int64"},"deposits":{"type":"array","items":{"$ref":"#/components/schemas/DetailedDepositResponse"}}}},"DetailedDepositResponse":{"required":["depositCurrency","depositReceivedAt","displayCurrency","fromAddress","id","network","onChainFee","status","toAddress","transactionId","uniformCurrency","userServiceFeeDistributionPercentage"],"type":"object","properties":{"id":{"type":"string","description":"Deposit UUID.","format":"uuid"},"transactionId":{"type":"string","description":"Blockchain transaction hash for the deposit."},"status":{"type":"string","description":"Status for this deposit only (not to be confused with the status for the entire payment).","enum":["COMPLIANCE_REVIEW","UNCONFIRMED","CONFIRMED","BLOCKED","UNPROCESSABLE","FAILED"]},"fromAddress":{"type":"string","description":"Sending address of the transaction."},"toAddress":{"type":"string","description":"Receiving address of the transaction."},"riskScore":{"type":"string","description":"AML risk score."},"addressRiskAssessment":{"$ref":"#/components/schemas/AddressRiskAssessmentView"},"depositCurrency":{"type":"string","description":"Cryptocurrency that has been deposited.","enum":["BCH","BTC","ETH","LINK","LTC","SOL","USDC","XLM","XRP"]},"network":{"type":"string","description":"Network on which the deposit was made.","enum":["BCH","BTC","LTC","XLM","XRP","ETH","BSC","SOL","TRX"]},"depositAmount":{"type":"string","description":"Amount deposited in `depositCurrency`."},"depositDistributedUserServiceFee":{"type":"string","description":"Actual distributed service fee amount in `depositCurrency`."},"onChainFee":{"type":"string","description":"Blockchain fee in `depositCurrency`, paid by the end user."},"displayCurrency":{"type":"string","description":"Fiat currency.","enum":["AED","ARS","AUD","BDT","BGN","BRL","CAD","CHF","CLP","CNY","CZK","DKK","EUR","GBP","HKD","HRK","HUF","IDR","ILS","INR","ISK","JPY","KES","KRW","MXN","MYR","NOK","NZD","PEN","PHP","PLN","QAR","RON","SEK","SGD","THB","TRY","USD","VND","ZAR"]},"displayAmount":{"type":"string","description":"Amount deposited in `displayCurrency`."},"displayPayableAmount":{"type":"string","description":"Credited amount in `displayCurrency`."},"displayServiceFee":{"type":"string","description":"Service fee amount in `displayCurrency`."},"displayDistributedUserServiceFee":{"type":"string","description":"Distributed service fee in `displayCurrency`."},"settlementCurrency":{"type":"string","description":"Currency in which the deposit is credited.","enum":["BTC","USDC","EUR","GBP","USD"]},"settlementPayableAmount":{"type":"string","description":"Credited amount in `settlementCurrency`."},"settlementServiceFee":{"type":"string","description":"Service fee in `settlementCurrency`."},"settlementDistributedUserServiceFee":{"type":"string","description":"Distributed service fee in `settlementCurrency`."},"uniformCurrency":{"type":"string","description":"Always EUR."},"uniformPayableAmount":{"type":"string","description":"Credited amount in EUR."},"uniformServiceFee":{"type":"string","description":"Service fee in EUR."},"uniformDistributedUserServiceFee":{"type":"string","description":"Distributed service fee in EUR."},"userServiceFeeDistributionPercentage":{"type":"string","description":"Percentage of the service fee covered by the user."},"depositReceivedAt":{"type":"integer","description":"UNIX seconds at which the deposit was received.","format":"int64"},"displayRateDepegLossAmount":{"type":"string","description":"Loss incurred from the pegging of deposit and display currencies market rate expressed in `displayCurrency`."},"settlementRateDepegLossAmount":{"type":"string","description":"Loss incurred from the pegging of deposit and display currencies market rate expressed in `settlementCurrency`."},"uniformRateDepegLossAmount":{"type":"string","description":"Loss incurred from the pegging of deposit and display currencies market rate expressed in `uniformCurrency`."},"refund":{"$ref":"#/components/schemas/RefundResponse"}}},"AddressRiskAssessmentView":{"type":"object","properties":{"addressOwner":{"$ref":"#/components/schemas/LegalEntityResponse"},"sourceRiskEntities":{"uniqueItems":true,"type":"array","description":"Illicit sources from which the `recipientAddress` has received transactions.","items":{"$ref":"#/components/schemas/LegalEntityResponse"}},"destinationRiskEntities":{"uniqueItems":true,"type":"array","description":"Illicit destinations to which the `recipientAddress` has sent transactions.","items":{"$ref":"#/components/schemas/LegalEntityResponse"}}},"description":"AML risk assessment for the depositing address."},"LegalEntityResponse":{"type":"object","properties":{"name":{"type":"string","description":"Address owning entity name."},"category":{"type":"string","description":"Illicit source category."}},"description":"Legal entity."},"RefundResponse":{"required":["amount","depositCurrency","displayAmount","displayCurrency","network","reason","status","type"],"type":"object","properties":{"type":{"type":"string","enum":["PARTIAL","FULL"]},"status":{"type":"string","enum":["PENDING","CONFIRMED","NON_REFUNDABLE"]},"reason":{"type":"string","enum":["OVERPAYMENT","CURRENCY_MISMATCH","FOLLOW_UP_DEPOSIT","RESTRICTED_CURRENCY","ILLICIT_DEPOSIT"]},"depositCurrency":{"type":"string","description":"Deposit cryptocurrency.","enum":["BCH","BTC","ETH","LINK","LTC","SOL","USDC","XLM","XRP"]},"network":{"type":"string","description":"Deposit network.","enum":["BCH","BTC","LTC","XLM","XRP","ETH","BSC","SOL","TRX"]},"amount":{"type":"string","description":"Refund amount in `depositCurrency`."},"fee":{"type":"string","description":"Blockchain fee in `depositCurrency`."},"displayCurrency":{"type":"string","description":"Fiat currency.","enum":["AED","ARS","AUD","BDT","BGN","BRL","CAD","CHF","CLP","CNY","CZK","DKK","EUR","GBP","HKD","HRK","HUF","IDR","ILS","INR","ISK","JPY","KES","KRW","MXN","MYR","NOK","NZD","PEN","PHP","PLN","QAR","RON","SEK","SGD","THB","TRY","USD","VND","ZAR"]},"displayAmount":{"type":"string","description":"Refund amount in `displayCurrency`."},"displayFee":{"type":"string","description":"Blockchain fee in `displayCurrency`."},"transactionId":{"type":"string","description":"Transaction hash of the refund."},"confirmedAt":{"type":"integer","description":"UNIX seconds at which the refund transaction was confirmed.","format":"int64"}}}}},"paths":{"/v1/payments":{"post":{"summary":"Request crypto payment","description":"An endpoint for initiating a crypto payment request. Upon success, a unique `paymentUrl` is provided in the response which can be served within an iframe.\n\nAlternatively, you can redirect to the payment URL and if you have supplied a `redirectUrl` in the request, we will navigate the end-user back to your website upon payment completion (when we have received a deposit against this payment request). There is also a button which the end-user can use if they wish to get redirected back sooner.","operationId":"request-crypto-payment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}},"required":true},"responses":{"200":{"description":"Returns the created payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedPaymentResponse"}}}}}}}}} ``` {% hint style="info" %} More information regarding FIXED/FLOATING rate types [here](https://blog.finrax.com/guides/fixed-rates) {% endhint %} {% hint style="info" %} More information on ONE\_TIME/REUSABLE payment links [here](https://blog.finrax.com/guides/one-time-payments-vs.-recurring-payments) {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.finrax.com/references/crypto-payments/initiate-a-crypto-payment-request.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.