Skip to content

Getting Started

Welcome to the ElenPAY documentation. The documentation will provide you with the information needed to integrate a merchant website with our payment system. We'll guide you through the setup and testing procedures, the authentication process, and explain key terminologies associated with ElenPAY. This will help you understand the functionalities available to merchants. If at any point you have any question, please visit the FAQ section or write us at at [email protected]. Now, let's get started with ElenPAY to streamline your payment processes.

Backoffice Portal

Merchants have access to a secure backoffice portal where you can:

  • View all deposits and withdrawals in real time
  • Manage funding and settlements
  • Access transaction history and reports
  • Monitor payment statuses and troubleshoot issues

If you need access to the backoffice, please contact our support team for credentials and onboarding instructions.

Environments

Development Production
Network Bitcoin's Local Regtest Bitcoin's Mainnet
Api Keys and StoreID Provided by ElenPAY Provided by ElenPAY
API Documentation https://api-staging.elenpay.tech/docs https://api.elenpay.tech/docs

ElenPAY operates in two distinct environments: the staging environment and the production environment.

The staging environment serves as a testing ground for your payments and withdrawals. It operates on a testing network, known as 'regtest', utilizing a testing Bitcoin and Lightning network managed by ElenPAY. No real money is involved in this environment.

On the other hand, the production environment operates on the actual Bitcoin network, known as 'mainnet'. This network is also connected to the real Lightning network.

Please note that the staging and production environments maintain separate databases. Therefore, different stores and API Keys must be set up for each environment.

Testing environment (staging)

Merchants can test their platforms using our dedicated testing environment, which allows them to simulate Lightning deposits and withdrawals. To utilize this testing environment, merchants will require the following:

  • An LND Node connected to our RegTest network, complete with channels and funds (supplied by ElenPAY)
  • A Bitcoin wallet (we recommend using Zeus Wallet) to connect to the Lightning node
  • A Testing API Key (supplied by ElenPAY)
  • A Testing StoreID (also provided by ElenPAY)
  • A Webhook secret (provided by ElenPAY) for signature validation
  • A callback url to notify about events in our system (provided by you)

These tools will enable merchants to thoroughly test their platforms before transitioning to the live environment.

Authentication

Merchants will be provided with an API key, which must be included in all HTTP requests as a header. The format for this is as follows:

Authorization: Token ${apiKey}

In this format, ${apiKey} should be replaced with the actual API key provided. This key authorizes and secures the communication between the merchant's platform and our system.

StoreID Registration

To obtain a StoreID, merchants must contact our support team. The StoreID uniquely identifies your store and is required for all API operations.

Terminology and concepts

Throughout this documentation site, certain terms are used interchangeably to refer to similar concepts. Here's a brief explanation of these terms:

  • Invoice/Deposits: These terms are used to describe the process of receiving money, such as for a product, through ElenPAY. This is akin to a deposit of money.

  • Pull Payments/Withdrawals: A pull payment refers to the process where a merchant sends money back to the customer, for instance, a refund. This concept is related to the idea of withdrawals.

  • StoreID: A merchant is identified in the system by a StoreID. This ID is used across APIs and in the transaction reports.

  • Bolt11 invoice: A Bolt11 invoice, A.K.A payment request, is the standard format for payments in the lightning network.

  • Preimage: A secret value revealed when a Lightning payment is completed. The preimage is the only cryptographic proof that a payment was actually made.

  • LNURL: A protocol for simplified Lightning interactions, such as withdrawals or payments, using a single URL or QR code.

  • Checkout Link: A URL provided by the system to redirect users to the payment widget or page.

  • Webhook: An HTTP callback sent by the system to notify merchants of payment events.

  • Payment Request: Another term for a Lightning invoice (Bolt11).

  • Callback URL: The endpoint where the our system sends webhook notifications.

Payment Proof: Why the Preimage Matters

When a Lightning payment is completed, the payer receives a cryptographic value called the preimage. This preimage is the only definitive proof that a payment was successfully made and settled on the Lightning Network.

Important: Screenshots of a wallet or payment attempt are not sufficient proof of payment. Only the preimage can be used to verify that a payment was actually received by the intended recipient.

If a user claims to have paid but the transaction does not appear as completed in our backoffice, you must obtain the preimage (sometimes called the payment secret or proof) from the user. Provide this preimage to our support team. We will use it to cryptographically verify the payment status.

Webhooks

ElenPAY supports webhooks to notify merchants about important events, such as invoice settlement, expiration, or cancellation. To receive webhook notifications, you must provide a publicly accessible webhook URL to our support or integration team. This URL will be used for HTTP POST requests when events occur.

  • Registering your webhook URL: Contact our team to register your webhook endpoint. Ensure your endpoint is accessible from the public internet and can handle POST requests.
  • Webhook secret: You will receive a webhook secret from ElenPAY. Use this secret to verify the authenticity of incoming webhook requests.
  • Event types:
    • InvoiceSettled: Invoice (deposit) has been settled
    • InvoiceExpired: Invoice (deposit) has expired
    • PullPaymentSettled: Pull payment (withdrawal) has been settled
    • PullPaymentCancelled: Pull payment (withdrawal) has been cancelled (e.g. retry time exhausted after multiple errors)
  • Payloads: Each webhook POST contains a JSON payload with event details. See the User Guide for example payloads and field descriptions.
  • Security: Keep your webhook secret secure. Always validate the signature of incoming requests to prevent spoofing. See the examples for signature validation code.

API Rate Limits and Error Handling

ElenPAY may enforce rate limits on API requests to ensure fair usage. If you exceed the allowed rate, you will receive an error response indicating you are being rate-limited. Handle errors gracefully and implement retries with exponential backoff where appropriate.

Refer to the API documentation for details on error codes and recommended handling strategies.