{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-documentation/get_started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Conversions","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"conversions","__idx":0},"children":["Conversions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ryft allows you to convert funds between currencies using foreign exchange (FX). For more background, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/conversions"},"children":["Conversions"]}," in Core Concepts."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checking-the-estimated-rate","__idx":2},"children":["Checking the Estimated Rate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before creating a conversion, you can use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#operation/conversionsGetRate"},"children":["conversionsGetRate"]}," endpoint to retrieve an indicative gross exchange rate and buy amount, along with the fees that will be charged."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rate returned is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["indicative only"]}," and is not held — the rate applied when you create a conversion may differ. Request a rate only when needed rather than polling; this endpoint is rate-limited and will return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]}," response if exceeded."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rates are briefly unavailable during a short daily window (~90 seconds) while FX trading closes. During this window the endpoint returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," response with a message indicating that rates are temporarily unavailable — retry shortly. Creating a conversion is unaffected, as pricing is applied asynchronously."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-conversion","__idx":3},"children":["Creating a Conversion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#operation/conversionCreate"},"children":["conversionCreate"]}," endpoint to create a conversion. Specify the sell currency and amount and the buy currency."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]}," must be within the minimum and maximum conversion limits for the sell currency; requests outside the range are rejected with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/currencies#minimum-and-maximum-conversion-amounts"},"children":["conversion amount limits"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before creating a conversion, you must obtain agreement from the account holder to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dash.ryftpay.com/about/conversion-terms"},"children":["Ryft's conversion terms"]},". Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["termAgreement: true"]}," in the request body to confirm this — the request is rejected if it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Payload","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"conversionCreate - Payload Example","header":{"title":"conversionCreate - Payload Example","controls":{"copy":{}}},"source":"{\n    \"sell\": {\n        \"currency\": \"EUR\",\n        \"amount\": 100000\n    },\n    \"buy\": {\n        \"currency\": \"GBP\"\n    },\n    \"reason\": \"Monthly EUR settlement\",\n    \"termAgreement\": true\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Headers","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"conversionCreate - Headers Example","header":{"title":"conversionCreate - Headers Example","controls":{"copy":{}}},"source":"{\n    \"Authorization\": \"<secret_key>\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This creates a conversion on your own account. If creating a conversion for a specific Sub-Account, make sure to include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Account"]}," header in your API request with the Sub-Account ID as its value."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API responds with the new conversion in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: InProgress"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.fees"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.fees"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedSettlementDate"]}," are not present — pricing is applied asynchronously."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"conversionCreate - Response Example","header":{"title":"conversionCreate - Response Example","controls":{"copy":{}}},"source":"{\n    \"id\": \"cv_XXXXXXXX\",\n    \"sell\": {\"amount\": 100000, \"currency\": \"EUR\"},\n    \"buy\": {\"currency\": \"GBP\"},\n    \"status\": \"InProgress\",\n    \"reason\": \"Monthly EUR settlement\",\n    \"createdTimestamp\": 1750000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next, subscribe to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," webhook event to track the conversion through the rest of its lifecycle: the first event carries the pricing (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.fees"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.fees"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedSettlementDate"]},"), and a later one moves ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Settled"]}," once the bought funds are credited to the account's balance. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/webhooks/conversions"},"children":["Conversions Webhooks"]}," for the full payload examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"settlement-times","__idx":4},"children":["Settlement times"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conversions are booked for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same-day settlement if created before the cut-off time"]}," for the currencies involved, provided the relevant FX markets are open. Otherwise, they settle on the next available business day. Cut-off times vary by currency, and FX markets are closed on weekends and public holidays. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/conversions#settlement-times"},"children":["Settlement times"]}," for specific currency cut-offs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the deadline depends on both currencies and the calendar, don't assume a fixed offset. Instead, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedSettlementDate"]}," (ISO date) returned by Ryft:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#operation/conversionsGetRate"},"children":["conversionsGetRate"]}]}," — returned alongside the indicative rate, so you can show an expected settlement date before creating a conversion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The conversion object"]}," — populated once pricing has been applied, from the first ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," event onward. It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," present on the create response or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.created"]}," event."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedSettlementDate"]}," is an estimate and may not exactly match the final settlement date. A conversion is settled once a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," event with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: Settled"]}," is emitted and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settledTimestamp"]}," is set — at that point the bought funds are credited to the account's balance."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payouts","__idx":5},"children":["Payouts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon settlement, the converted funds will reflect in the account's available balance."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatic payouts"]},": Ryft will trigger a payout within 24 hours of the conversion settling. No action is required."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manual payouts"]},": For NonHosted accounts we recommend triggering a payout after receiving the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," event where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Settled"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/payouts"},"children":["Payouts"]}," for more on payout configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fees-and-fx-margin","__idx":6},"children":["Fees and FX margin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ryft applies an FX fee to every conversion. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]}," and all amounts are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["gross"]}," values (before fees)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The fee is charged on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exactly one side"]}," of the conversion, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.fees"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.fees"]}," are mutually exclusive — read whichever one is present. Which side it falls on determines the net amount credited to the account balance:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Buy side"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.fees"]},") — the whole ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]}," is converted at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]}," to give ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]},", and the fee is deducted from it afterwards: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Net Credit = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}," − Fee"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sell side"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.fees"]},") — the fee is deducted from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," the conversion, so only the remainder is converted: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Net Credit = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}]}," in full."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fee amounts are in minor units of the currency of the side they are charged on."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once calculated, the fee breakdown on that side contains either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ryft"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform"]},", depending on the account type:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/ryft_entities"},"children":["Main Accounts"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ryft"]}," shows Ryft's fee, which is deducted in full."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/ryft_entities#sub-accounts"},"children":["Sub-Accounts"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform"]}," shows the total gross platform fee deducted. Ryft's fee (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.ryftFee"]},") is taken out of this amount — it is not an additional deduction. The platform retains the difference (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.amount"]}," − ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.ryftFee.amount"]},")."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"fees — Main Account","header":{"title":"fees — Main Account","controls":{"copy":{}}},"source":"{\n    \"ryft\": {\"amount\": 700}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Total fee deducted: 700 (all retained by Ryft)."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"fees — Sub-Account","header":{"title":"fees — Sub-Account","controls":{"copy":{}}},"source":"{\n    \"platform\": {\n        \"amount\": 1000,\n        \"ryftFee\": {\"amount\": 700}\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Total fee deducted: 1000 (700 goes to Ryft, 300 retained by the platform)."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The platform fee is a single rate across all Sub-Accounts, including conversions Sub-Accounts create directly via the Ryft Portal. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/support"},"children":["Contact us"]}," to configure it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Sub-Account conversions, the platform fee is settled against the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Main Account's"]}," balance via a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConversionPlatformFee"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#operation/balanceTransactionsList"},"children":["balance transaction"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["With a configured platform fee"]}," — the transaction's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["net"]}," value represents the platform's retained earnings (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.amount"]}," − ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.ryftFee.amount"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Without a platform fee"]}," — a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConversionPlatformFee"]}," transaction is still created to cover Ryft's FX fee, resulting in a negative ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["net"]}," value (a debit) on the Main Account."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"calculating-the-net-amount-and-effective-rate","__idx":7},"children":["Calculating the net amount and effective rate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Take the single populated fee — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ryft.amount"]}," for a Main Account, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform.amount"]}," for a Sub-Account — from whichever side carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fees"]},", then apply the net credit above. The effective rate you received is the net amount credited ÷ ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a buy-side fee (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]}," 100000, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}," 86000, Ryft fee 700):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"net amount     = 86000 − 700     = 85300\neffective rate = 85300 ÷ 100000  = 0.853\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a sell-side fee (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell.amount"]}," 100000, Ryft fee 700, so 99300 converted at 0.86 to give ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}," 85398):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"net amount     = 85398\neffective rate = 85398 ÷ 100000  = 0.85398\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, once the conversion settles the credited funds appear as a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#operation/balanceTransactionsList"},"children":["balance transaction"]}," of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConversionBuy"]},", whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["net"]}," field is the net amount credited — so you can read it directly instead of computing it. The sold funds are debited from the sell-currency balance as a matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ConversionSell"]}," transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":8},"children":["Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following walks through the full lifecycle of a conversion. In this scenario, a merchant collects payments in EUR but only holds a GBP bank account. They convert €1,000.00 of their EUR balance to GBP so it can be paid out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-create-the-conversion","__idx":9},"children":["1. Create the conversion"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v1/conversions — Request","header":{"title":"POST /v1/conversions — Request","controls":{"copy":{}}},"source":"{\n    \"sell\": {\"currency\": \"EUR\", \"amount\": 100000},\n    \"buy\": {\"currency\": \"GBP\"},\n    \"reason\": \"Monthly EUR settlement\",\n    \"termAgreement\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains the new conversion. The rate and buy amount are not yet known:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v1/conversions — Response","header":{"title":"POST /v1/conversions — Response","controls":{"copy":{}}},"source":"{\n    \"id\": \"cv_XXXXXXXX\",\n    \"sell\": {\"amount\": 100000, \"currency\": \"EUR\"},\n    \"buy\": {\"currency\": \"GBP\"},\n    \"status\": \"InProgress\",\n    \"reason\": \"Monthly EUR settlement\",\n    \"createdTimestamp\": 1750000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-conversioncreated","__idx":10},"children":["2. Conversion.created"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.created"]}," webhook is dispatched immediately, carrying the same unpriced object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-conversionupdated--pricing-applied","__idx":11},"children":["3. Conversion.updated — pricing applied"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the rate is determined, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," event is emitted. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}," (gross, before fees), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fees"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedSettlementDate"]}," are now populated. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#calculating-the-net-amount-and-effective-rate"},"children":["Calculating the net amount and effective rate"]}," to derive what is credited to the balance:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Conversion object — pricing applied","header":{"title":"Conversion object — pricing applied","controls":{"copy":{}}},"source":"{\n    \"id\": \"cv_XXXXXXXX\",\n    \"sell\": {\"amount\": 100000, \"currency\": \"EUR\"},\n    \"buy\": {\n        \"amount\": 86000,\n        \"currency\": \"GBP\",\n        \"fees\": {\n            \"ryft\": {\"amount\": 700}\n        }\n    },\n    \"rate\": 0.86,\n    \"status\": \"InProgress\",\n    \"reason\": \"Monthly EUR settlement\",\n    \"estimatedSettlementDate\": \"2026-06-20\",\n    \"createdTimestamp\": 1750000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where the fee is charged on the sell side instead, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fees"]}," sits on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sell"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy"]}," carries none — the fee came off the 100000 EUR before conversion, so 99300 was converted at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]}," and the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buy.amount"]}," is credited:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Conversion object — sell-side fee","header":{"title":"Conversion object — sell-side fee","controls":{"copy":{}}},"source":"{\n    \"id\": \"cv_XXXXXXXX\",\n    \"sell\": {\n        \"amount\": 100000,\n        \"currency\": \"EUR\",\n        \"fees\": {\n            \"ryft\": {\"amount\": 700}\n        }\n    },\n    \"buy\": {\"amount\": 85398, \"currency\": \"GBP\"},\n    \"rate\": 0.86,\n    \"status\": \"InProgress\",\n    \"reason\": \"Monthly EUR settlement\",\n    \"estimatedSettlementDate\": \"2026-06-20\",\n    \"createdTimestamp\": 1750000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-conversionupdated--settled","__idx":12},"children":["4. Conversion.updated — settled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the conversion settles, a further ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Conversion.updated"]}," is emitted. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," is now ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Settled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settledTimestamp"]}," is set, and the GBP funds are available in the account's balance:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Conversion object — settled","header":{"title":"Conversion object — settled","controls":{"copy":{}}},"source":"{\n    \"id\": \"cv_XXXXXXXX\",\n    \"sell\": {\"amount\": 100000, \"currency\": \"EUR\"},\n    \"buy\": {\n        \"amount\": 86000,\n        \"currency\": \"GBP\",\n        \"fees\": {\n            \"ryft\": {\"amount\": 700}\n        }\n    },\n    \"rate\": 0.86,\n    \"status\": \"Settled\",\n    \"reason\": \"Monthly EUR settlement\",\n    \"estimatedSettlementDate\": \"2026-06-20\",\n    \"settledTimestamp\": 1750086400,\n    \"createdTimestamp\": 1750000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-payout","__idx":13},"children":["5. Payout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The GBP funds are now available in the account's balance. If the account is on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["automatic payouts"]},", Ryft will trigger a payout within 24 hours — no action needed. If on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["manual payouts"]},", trigger one after receiving the settled event above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":14},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/api/reference/openapi#tag/Conversions"},"children":["API reference"]}," — full endpoint documentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/webhooks/conversions"},"children":["Conversions Webhooks"]}," — event payload reference"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/overview/core_concepts/payouts"},"children":["Payouts"]}," — payout configuration"]}]}]},"headings":[{"value":"Conversions","id":"conversions","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Checking the Estimated Rate","id":"checking-the-estimated-rate","depth":2},{"value":"Creating a Conversion","id":"creating-a-conversion","depth":2},{"value":"Settlement times","id":"settlement-times","depth":2},{"value":"Payouts","id":"payouts","depth":2},{"value":"Fees and FX margin","id":"fees-and-fx-margin","depth":2},{"value":"Calculating the net amount and effective rate","id":"calculating-the-net-amount-and-effective-rate","depth":3},{"value":"Example","id":"example","depth":2},{"value":"1. Create the conversion","id":"1-create-the-conversion","depth":3},{"value":"2. Conversion.created","id":"2-conversioncreated","depth":3},{"value":"3. Conversion.updated — pricing applied","id":"3-conversionupdated--pricing-applied","depth":3},{"value":"4. Conversion.updated — settled","id":"4-conversionupdated--settled","depth":3},{"value":"5. Payout","id":"5-payout","depth":3},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Conversions"}},"lastModified":"2026-08-13T09:06:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/documentation/get_started/conversions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}