# Requesting Payouts Another version of this information is available If you're new to Tilia services, a newer version of this information is available in the [Transaction Tutorials](/tutorials/transactions) section of these docs, which might be an easier place to start. Tilia enables you to transfer funds from an account's wallet to a supported payment method. The account must have valid KYC data on file in order to receive payout funds. Payout requests are subject to review by Tilia's Compliance team prior to funds being released. This example walks you through the process of gathering the necessary account details and initiating a payout request. Currently, funds may only be transferred to PayPal accounts. Users must have a PayPal account that can receive funds in order to receive payouts. ## Prerequisites To complete this example, you'll need the following: - An Access Token with the requisite scopes: `write_user_tokens` and `write_process_credits`. - The account ID for the payout requestor. The account must have a wallet balance. - A web page containing the Tilia widget script. Refer to [Widget Integration](/web-uis/widget-overview) for instructions on setting this up. - A payment method. Refer to [Test Payments](/guides/test-payments) for payment methods you can use in testing. The process of requesting a payout involves the following steps: [Step 0: Fetch wallet details](#step-0-fetch-wallet-details) [Step 1: Create a secure redirect URL](#step-1-create-a-secure-redirect-url) [Step 2: Obtain payment details](#step-2-obtain-payment-details) [Step 3: Initiate the payout request](#step-3-initiate-the-payout-request) [Step 4: Handle the completion event](#step-4-handle-the-completion-event) ## Step 0: Fetch wallet details In order to process transactions, you need the user's `account_id`. For payout requests, you will also need the Tilia wallet `id` from which the funds are to be transferred. Refer to [Get Wallet Balance](/guides/get-wallet-balance) for information on retrieving wallet information. In order to process transactions, you need the user's `account_id`. For payout requests, you will also need the Tilia wallet `id` from which the funds are to be transferred. Refer to [Get Wallet Balance](/guides/get-wallet-balance) for information on retrieving wallet information. ## Step 1: Create a secure redirect URL To start, you will use the `account_id` to create a redirect URL for the payout flow. The payout flow guides the user through the process of submitting KYC data (if necessary), and choosing a destination payment method for the payout. Creating a redirect URL requires an API token with the scope `write_user_tokens`. ```bash curl --location --request POST https://auth.tilia-inc.com/authorize/user \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` In the request body, specify the account_id for the user as follows: ```json { "account_id": "string" } ``` The response JSON returns a redirect URL which forms the basis for calling the payout flow. ```json { "status": "Success", "message": [], "codes": [], "payload": { "redirect": "https://web.tilia-inc.com/ui/appauth/ed8ff1e9-9256-4205-918a-b9ca23ec00ec" } } ``` ## Step 2: Obtain payment details The Tilia payout flow allows the user to choose a payment method for the payout. If the user does not have a payment method on file, they will be able to add one. The payout flow also does the following: - Verifies the account has a signed copy of the most recent Tilia Terms of Service (TOS) on file and, if necessary, routes the user to the TOS flow. - Checks the account's KYC status. If KYC status is anything other than `ACCEPT` or `MANUAL_REVIEW`, the user is routed to the KYC flow. If KYC status is `MANUAL_REVIEW`, the supplied KYC data is being reviewed by the Tilia Compliance team. The user will not be able to receive funds until this review is complete. ```javascript window.Tilia.execute({ rootId: , flow: payout, redirect: https://web.tilia-inc.com/ui/appauth/ed8ff1e9-9256-4205-918a-b9ca23ec00ec, onComplete: handleComplete, }); ``` The widget invokes the `handleComplete` callback with the result of the flow. #### If the user cancels anywhere in the flow: ```json { source: “tilia”, event: “tilia.pm.complete”, state: “cancel”, } ``` #### If the user completes the flow: ```json { source: “tilia”, event: “tilia.pm.complete”, id: , psp_reference: , pm_state: } ``` The value for `id` is the payment method ID used in the next step. ## Step 3: Initiate the payout request Once you have the user's payment method ID, you can start the payout request. The following information is required: `source_payment_method_id`: The `id` for the user's wallet from which the funds are to be transferred (e.g., the USD wallet). `destination_payment_method_id`: The `id` returned from the payout flow. This payment method must be associated with a PayPal account. `amount`: The total amount to be paid out. `currency`: The currency for the payout. Must be an [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). Must be a supported currency. This example is in USD. Therefore, all amounts are in cents. Refer to [Working with Currencies](/core-concepts/working-with-currencies) for information on how currencies are used. Requesting payouts requires an API token with the scope `write_process_credits`. ```bash curl --location --request POST https://invoicing.tilia-inc.com/v2/{account_id}/payout \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ ``` #### Request Body ```json { "source_payment_method_id": "", "destination_payment_method_id": "payout_payment_method_id", "amount": 500, "currency": "USD" } ``` #### Response Sample ```json { "status": "Success", "message": [], "codes": [], "payload": { "payout_status_id": "f12350fa-4110-45d1-9868-8dae80000000", "credit_id": "b44dca90-b1f7-49bc-8a8f-87739a555555", "account_id": "682c8d3e-75ad-4d10-8b1a-1e1576888888", "status": "ESCROW-TRANSFER-INITIATED", "created": "2020-09-16 15:38:42.277077", "updated": "2020-09-16 15:38:42.551941", "credit": { "destination_payment_method_id": "adaeca29-eda4-4bc0-87cc-1b7956444444", "amount": 500, "currency": "USD", "status": "CREATED" } } } ``` Payout requests are processed asynchronously. The value for `status` will be `ESCROW-TRANSFER-INITIATED` until the payout is processed, at which time the status will update to either: - `USER-CANCELED`: The payout request was canceled by the user. - `SUCCESS`: The payout request has successfully been paid. - `SUPPORT-REJECTED`: The payout request was rejected by Tilia support. You can check the status of a payout by calling `GET https://invoicing.tilia-inc.com/v2/{account_id}/payout/{payout_status_id}`. ## Step 4: Handle the completion event Although this step is optional, we recommend implementing a webhook to notify you about changes to the payout request status. See the documentation for complete details. For more information about developing and registering webhook handlers, visit [Webhooks](/webhooks/).