Payout

The Payout flow allows merchant's end-users to select their digital asset of choice to receive.

Payout Sequence Diagram

The general happy path will be discussed, with exception scenarios discussed later on in the guide:

1. The end user will request to make a payout on your system, which will then be forward onto us in the form of a Create Payment request.
2. The Create Payment endpoint will return a redirectUrl, along with other useful data in the API response. End user can then be directed to this URL which hosts our payments page
3. The end user will select the digital asset and network in the dropdown that they want to receive, and as this is now on our hosted page, the request is sent directly to us.
4. The end-user inputs the receiving blockchain address to match the selected digital asset and network, the address is auto-validate to ensure its the correct format.
5. The end user initiates the payout, which will then cause multiple related webhooks to be sent to your webhook listener as the payment goes through its lifecycle.
6. Once you receive the final COMPLETEwebhook you can poll the Get Payment endpoint to confirm the status and final paid amount, or take the information from the webhook.
7. Update the end users account accordingly with the confirmed paid amount.

Payment Lifecycle

A payment undergoes several status changes throughout its lifecycle, detailed as follows:

Status	Immutable?	Description
Pending	No	This state indicated that the payout has been created, but that no wallet details have yet been entered.
Processing	No	This status indicates that the customer's payment has been submitted to the blockchain. The payment remains in this state until funds are credited to their wallet.
Complete	Yes	This status means that the funds have been received and credited to the users account in the chosen currency.

Initiating the payout

To initiate a payment process, utilize the Create Payment endpoint.

Below are the details required for the create payment request. Set type to OUT, and use the Merchant ID from the Merchant Details page as merchantId. If you omit expiryMinutes, the payment expires after 1440 minutes.

Example Request

Here is how an example request might look:

Example Request

{
  "merchantId": "00a4af9d-ad4b-42d5-bec4-b7a8c90161fe",
  "amount": 100,
  "expiryMinutes": 60,
  "currency": "USD",
  "returnUrl": "https://yourwebsitename.com",
  "reference": "6a4013c2-5fa9-4e2f-bef7-88c5570b6501",
  "type": "OUT"
}

Example Response

Upon successfully submitting the request, you'll receive a response like the following:

Response

Example Response

{
    "metadata": {},
    "uuid": "63e3fece-1e91-4d57-9bd9-35d785183486",
    "merchantDisplayName": "USDT wallet",
    "merchantId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358",
    "dateCreated": 1750171431459,
    "expiryDate": 1750172631459,
    "quoteExpiryDate": null,
    "acceptanceExpiryDate": null,
    "quoteStatus": "TEMPLATE",
    "reference": "b91f3d03-7a6e-4502-b865-784cb5fa21c4",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PENDING",
    "displayCurrency": {
        "currency": "EUR",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "USDT",
        "amount": 11.57236634640142803,
        "actual": 0
    },
    "paidCurrency": {
        "currency": null,
        "amount": 0,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "USDT",
        "amount": 0,
        "actual": 0
    },
    "displayRate": null,
    "exchangeRate": null,
    "address": null,
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.layer1.com/payout/fef4e99d-b41d-4efe-89fd-4fdf41f3f33f",
    "transactions": [],
    "refund": null,
    "refunds": []
}

At this juncture, it's crucial to note the uuid and redirectUrl. The uuid is used for querying the payment status, and the redirectUrl directs the end-user to the Hosted Payments Page for digital asset selection.

Note that as the payment currency is not known at this stage, exchange rates and paid currency values are null

note

If you already know the digital asset and address of the end-user will pay with, refer to the next guide for creating a tailored payment request.