Payout

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

Payout Sequence Diagram

The sequence diagram for a crypto payment in followed in this guide.

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

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

Parameter	Type	Required	Description
`merchantId`	string	Yes	Identifies the Merchant ID, indicating which wallet the payment should settle in. Found on the Merchant Details page.
`amount`	long	Yes	The total amount needed to complete the payment.
`expiryMinutes`	integer	No	Defines the time frame for the end-user to complete the payment. Defaults to 1440 minutes if not specified.
`currency`	string	Yes	The currency code to present the price in to the end-user.
`returnUrl`	string	No	The URL for redirecting the user back to the merchant's site from the payment flow.
`reference`	string	Yes	A unique reference for the payment, visible to both you and your customer.
`type`	string	Yes	Specifies the transaction type, using `OUT` for outgoing payments.

Example Request

Here is how an example request might look:

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

{
    "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
    },
    "networkFeeCurrency": null,
    "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": [],
    "currencyOptions": [],
    "flow": "DEFAULT",
    "twoStep": false,
    "pegged": false,
    "customerId": null,
    "walletId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358"
}

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

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