Guides

Payment In

Initiating the payment in flow

Suggest Edits

The Payment In flow allows merchant's end-users to select their digital asset of choice to pay with.

Payment In Sequence Diagram

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

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:

  1. The end user will request to make a deposit 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 make the payment with, and as this is now on our hosted page, the request is sent directly to us.
  4. We generate an blockchain address to match the requested digital asset and network, and auto-update the Hosted Payments Page to display this newly created address.
  5. The end user makes a payment to this address, 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 payment amount.

Payment Lifecycle

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

StatusImmutable?Description
PendingNoThe initial status of your payment. It remains in this state until the payment either expires or a transaction linked to this payment is detected on the blockchain.
ProcessingNoThis status indicates that the customer's payment has been detected on the blockchain. The payment remains in this state until funds are credited to your wallet.
Note: Payments can still expire in this state if the transaction lacks sufficient gas or if the blockchain does not confirm the transaction within the expiry time.
CompleteYesThis status means that the funds have been received and credited to the merchant account in the chosen currency.
UnderpaidYesIndicates that the funds have been received and credited to the merchant account in the chosen currency, but the amount sent by the customer was less than the requested amount.
ExpiredYesThe payment expired before the customer sent the funds.

Initiating the payment in

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

Below are the details required for the create payment request:

ParameterTypeRequiredDescription
merchantIdstringYesIdentifies the Merchant ID, indicating which wallet the payment should settle in. Found on the Merchant Details page.
amountlongYesThe total amount needed to complete the payment.
expiryMinutesintegerNoDefines the time frame for the end-user to complete the payment. Defaults to 1440 minutes if not specified.
currencystringYesThe currency code to present the price in to the end-user.
returnUrlstringNoThe URL for redirecting the user back to the merchant's site from the payment flow.
referencestringYesA unique reference for the payment, visible to both you and your customer.
typestringYesSpecifies the transaction type, using IN for incoming 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": "IN"
}

Example Response

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

{
  "uuid": "fef4e99d-b41d-4efe-89fd-4fdf41f3f33f",
  "merchantDisplayName": "Metallica Inc",
  "merchantId": "00a4af9d-ad4b-42d5-bec4-b7a8c90161fe",
  "dateCreated": 1704807605678,
  "expiryDate": 1704808805678,
  "quoteExpiryDate": 1704808806000,
  "acceptanceExpiryDate": 1704807636000,
  "quoteStatus": "ACCEPTED",
  "reference": "a003cec4-abf5-42aa-baf0-43a1cc815536",
  "type": "IN",
  "subType": "merchantPayIn",
  "status": "PENDING",
  "displayCurrency": {
    "currency": "USD",
    "amount": 100,
    "actual": 0
  },
  "walletCurrency": {
    "currency": "EUR",
    "amount": 100,
    "actual": 0
  },
  "paidCurrency": {
    "currency": null,
    "amount": 0,
    "actual": 0
  },
  "feeCurrency": {
    "currency": "EUR",
    "amount": 1,
    "actual": 0
  },
  "displayRate": null,
  "exchangeRate": null,
  "address": null,
  "returnUrl": "https://yourwebsitename.com",
  "redirectUrl": "https://pay.sandbox.layer1.com/payin?uuid=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

📘

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

Updated about 17 hours ago

What’s Next