Requesting Payouts

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.

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 for instructions on setting this up.
• A payment method. Refer to 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 1: Create a secure redirect URL

Step 2: Obtain payment details

Step 3: Initiate the payout request

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 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 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.

curl --location --request POST https://auth.tilia-inc.com/authorize/user \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

In the request body, specify the account_id for the user as follows:

{
  "account_id": "string"
}

The response JSON returns a redirect URL which forms the basis for calling the payout flow.

{
    "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.

window.Tilia.execute({
  rootId: <your.element.id>,
  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:

{
  source: “tilia”,
  event: “tilia.pm.complete”,
  state: “cancel”,
}

If the user completes the flow:

{
  source: “tilia”,
  event: “tilia.pm.complete”,
  id: <payment.method.id>,
  psp_reference: <psp.reference>,
  pm_state: <payment.method.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. Must be a supported currency.

Requesting payouts requires an API token with the scope write_process_credits.

curl --location --request POST https://invoicing.tilia-inc.com/v2/{account_id}/payout \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Request Body

{
    "source_payment_method_id": "<wallet_payment_method_id>",
    "destination_payment_method_id": "payout_payment_method_id",
    "amount": 500,
    "currency": "USD"
}

Response Sample

{
    "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 Payout Completion webhook documentation for complete details.

For more information about developing and registering webhook handlers, visit Webhooks.