--- title: "Confirm Payout with FX" source_url: https://docs.rapyd.net/en/confirm-payout-with-fx.html lang: en --- # Confirm Payout with FX Confirm the exchange rate of a payout that involves foreign exchange. Relevant when the payout was created with `confirm_automatically` set to **false** (default). To confirm creation of the payout with the FX rate included in the response to [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout"), you must run this method within a short time. The exact amount of time varies from payout method to payout method. This method triggers the [Payout Created Webhook](https://docs.rapyd.net/en/payout-created-webhook.md "Payout Created Webhook"). This webhook contains the same information as the response. > **Note:** > > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Payout Errors](https://docs.rapyd.net/en/payout-errors.md "Payout Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - payout - ID of the payout. String starting with **payout_**. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - amount - Amount of the payout, in units defined by `payout_currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Same as `payout_amount`. - - batch_file - Batch file ID. Relevant to batch payouts that were created via the Client Portal. - - beneficiary - Object describing the beneficiary. - - beneficiary_country - Beneficiary bank country. The country to which funds are sent. Two-letter ISO 3166-1 ALPHA-2 code. - - bin_details - Bank identification details. Relevant to cards. - - bin_number - [Bank identification number](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_bin "Bank Identification Number") of the issuing bank. - - brand - The brand of the card. - - country - The country where the card was issued. - - issuer - Name of the bank that issued the card. - - level - The level of the card. - - type - The type of card. - - created_at - Time of creation of the `payout` object, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - crypto_payout_hash - A unique identifier that is proof that a payout was validated and added to the blockchain. Relevant to stablecoin cryptocurrency payouts via the `xx_stablecoin_ewallet` payout method. Value is **null** when payout has not been completed or when not relevant. - - error - Indicates the error code of the last unsuccessful operation on the `payout` object. - - estimated_time_of_arrival - The estimated time period in which the beneficiary will receive the funds. > **Note:** > > Rapyd will try to complete the payout within the estimated time. However, completion of a payout can be delayed for legal or other reasons. - - ewallets - An array of one object, which contains the following fields: - - ewallet_id - The ID of the wallet that the money is transferred from, a string starting with **ewallet_**. - - amount - Amount of the transaction in currency units defined in `currency`. - - percent - A decimal number representing a percentage of the total payout. - - expiration - Determines the day the payout expires, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). The payout must be completed before the start of this day. Relevant to cash payout methods where the `is_expirable` field is **true** in the response to [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types"). - - fx_rate - Currency conversion rate for the payout. Decimal. - - gc_error_code - Reserved. - - id - ID of the payout. String starting with **payout_**. - - identifier_type - Reserved. - - identifier_value - Reserved. - - instructions - Describes how the customer collects the payout. Contains the following fields: - - name - Description of the payment method. - - steps - An array containing a list of steps for the customer to take. Each step is named **step*N***, where ***N*** is an integer. - - merchant_ewallet - ID of the client wallet of the sub-merchant. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - paid_amount - Cumulative amount received by the beneficiary, in units defined by `payout_currency`. - - paid_at - Time of the payout, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - payout_currency - Currency received by the beneficiary. Three-letter ISO 4217 code. > **Note:** > > Four-letter codes are supported for stablecoin payouts. - - payout_fees - Object that defines transaction fees and foreign exchange fees that the client can define for payout transactions. - - transaction_fee - Describes the fee for processing the transaction. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - fee_type - One of the following: - **percentage** - A percentage of the transaction amount. For example, 5 percent is represented by **value=5**. - **absolute** - A fixed amount. - - value - The amount of the fee. - - fx_fee - Describes the fees for processing the currency exchange. Relevant to payments with FX. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - value - The amount of the fee. Percentage. - - fee_currency - The currency in which fees are deducted. Required when  `payout_currency` is stablecoin and `calc_type` is not **gross**. After the fees are calculated, they are converted to the `fee_currency`. One of the following: - **USD** - **EUR** - **GBP** - **SGD** - **HKD** - **AUD** - - gross_fees - The total gross fees for the transaction, in units defined by `currency_code`. - - net_fees - The total net fees for the transaction, in units defined by `merchant_requested_currency`. - - total_merchant_fees - The amount of the fee. - - payout_method_type - The type of payout method. The two-letter prefix must match the country code of the beneficiary. - - payout_type - The type of the payout method. One of the following values: - **bank** - Payout to bank account. - **card** - Payout to card. - **cash** - Payout to cash. - **ewallet** - Payout to local eWallet. - - sender - Object describing the sender. - - company_name - Name of the sender company. Relevant when `entity_type` is **company**. - - country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. - - currency - Currency that the sender is paying with. Three-letter ISO 4217 code. - - entity_type - Type of entity. One of the following values: - **company** - **individual** - - first_name - First name of the sender. Relevant when `entity_type` is **individual**. - - identification_type - Type of identification document for the sender. When `entity_type` is **company**, this field must be **company_registered_number**. When `entity_type` is **individual**, one of the following values: - **drivers_license** - **identification_id** - **international_passport** - **residence_permit** - **social_security** - **work_permit** - - identification_value - Identification number on the document mentioned in `identification_type`. - - last_name - Last name of the sender. Relevant when `entity_type` is **individual**. - - sender_amount - Amount that the sender is paying in units of the currency defined in `sender_currency`. This amount remains the same regardless of FX fees. Decimal. - - sender_country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. - - sender_currency - Currency that the sender is paying with. Three-letter ISO 4217 code. - - statement_descriptor - A statement that includes the reason for the payout. Limited to 35 characters. - - status - Indicates the status of the payout. One of the following: - **Canceled** - The payout was canceled. - **Completed** - The beneficiary received some or all payout funds. - **Confirmation** - The payout is waiting for the beneficiary to confirm the FX rate. - **Created** - The payout was created successfully. - **Declined** - The payout failed to pass inspection. - **Error** - The payout was not created or failed after creation. - **Expired** - The payout has expired. - **Hold** - A bank payout is being reviewed manually by Rapyd Protect. A [Quarantine Under Review Webhook](https://docs.rapyd.net/en/quarantine-under-review-webhook.md "Quarantine Under Review Webhook") is also triggered. - **Pending** - The payout is waiting for the beneficiary to confirm acceptance of the funds. - **Returned** - Funds were returned to after the payout was completed. - - uetr - Unique End-to-End Transaction Reference. A 36-character alphanumeric code that uniquely identifies a specific international payout. When not relevant, the parameter does not appear in the response. - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string payout = "payout_a8f528fc070c62ae6ea2025d3fb6d041"; string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/payouts/confirm/{payout}"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = {}; const result = await makeRequest( 'POST', '/v1/payouts/confirm/payout_a8f528fc070c62ae6ea2025d3fb6d041', body ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('post', '/v1/payouts/confirm/payout_a8f528fc070c62ae6ea2025d3fb6d041'); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request payout = 'payout_a8f528fc070c62ae6ea2025d3fb6d041' results = make_request(method='post', path=f'/v1/payouts/confirm/{payout}') pprint(results) ``` - /v1/payouts/confirm/:payout - Confirm Payout with FX - ```bash curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/confirm/payout_b5f468ba37f451d846eddcdc9b2d5bcb' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "5288ce10-b4c5-4bc1-8663-0c3ac44d6865" }, "data": { "id": "payout_b5f468ba37f451d846eddcdc9b2d5bcb", "payout_type": "bank", "payout_method_type": "mx_abc_capital_bank", "amount": 2000, "payout_currency": "MXN", "sender_amount": 100.87, "sender_currency": "USD", "status": "Created", "sender_country": "MX", "sender": { "id": "sender_b69a49623d68889313b5b622ad9ff7a2", "country": "MX", "entity_type": "company", "name": "SenderCompanyName", "company_name": "SenderCompanyName", "currency": "USD" }, "beneficiary_country": "MX", "beneficiary": { "id": "beneficiary_602c827876721a485cdf4a7105b05cdc", "last_name": "Doe", "first_name": "John", "country": "MX", "entity_type": "individual", "name": "John Doe", "account_number": "321654987", "currency": "MXN", "bank_account_type": "clabe" }, "fx_rate": "19.8280173500", "instructions": [ { "name": "instructions", "steps": [ { "step1": "The funds will be transferred to the provided account details of the beneficiary ." } ] } ], "ewallets": [ { "ewallet_id": "ewallet_4f1757749b8858160274e6db49f78ff3", "amount": 100.87, "percent": 100 } ], "metadata": {}, "description": "FX with confirmation", "created_at": 1755758255, "payout_fees": null, "expiration": null, "merchant_reference_id": "", "paid_at": null, "identifier_type": null, "identifier_value": null, "error": null, "paid_amount": 0, "statement_descriptor": "RIDE MX payout monthly", "gc_error_code": null, "batch_file": null, "estimated_time_of_arrival": "An estimated receipt time is not yet available for this payout method.", "crypto_payout_hash": null } } ``` - Bad Request - Payout Rate Expired - ```bash curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/confirm/payout_b5f468ba37f451d846eddcdc9b2d5bcb' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "ERROR_PAYOUT_RATE_EXPIRED", "status": "ERROR", "message": "Please contact Rapyd Client Support.", "response_code": "ERROR_PAYOUT_RATE_EXPIRED", "operation_id": "6fbd8494-0fdb-4cfe-83ff-60f4f31f01fe" } } ``` - Bad Request - Foreign Exchange Not Relevant - ```bash curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/confirm/payout_5bc5d5cd23a46874672108457e1d0a28' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "ERROR_CONFIRM_PAYOUT", "status": "ERROR", "message": "The request tried to confirm a payout with foreign exchange, but the payout was already completed or did not involve foreign exchange. The request was rejected. Corrective action: None. Determine why an attempt was made to confirm the foreign exchange rate in a payout that does not involve foreign exchange.", "response_code": "ERROR_CONFIRM_PAYOUT", "operation_id": "92107fe7-3cc4-44ab-a64f-f112058e9f84" } } ```