# 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 %}