DOCSEARCHbyAlgolia
Submit Docs

Paycoinly Documentation

website·Indexed 31 days ago

https://www.paycoinly.xyz/docs/intro/

Documentation for integrating Paycoinly payment and withdrawal services. Includes guides on manual setup, payment and withdrawal flows, webhook configuration, and API endpoints for making withdrawal requests and generating withdrawal tokens.

Tokens
5.5K
Snippets
23
Records
36
Agent score
58%

What's inside Paycoinly

  1. Overview of Paycoinly crypto payment infrastructure

    Paycoinly is a multi-chain crypto payment gateway that acts as a bridge between blockchain assets and real-world business cash flow. It allows businesses to accept payments in stablecoins (USDT/USDC), native chain tokens (ETH, BNB), memecoins, and tokenized real-world assets. The platform supports online flows (checkouts, subscriptions, donations, tipping) and offline commerce (POS), providing multi-currency support where merchants can price in a base currency while customers see prices in their local currency.

  2. Set up Paycoinly for simple donations

    To integrate Paycoinly for accepting donations or 'Buy Me a Coffee' contributions without recording payer information in your own system, follow these steps:

    1. Disable Payer Tracking: Go to Payments > Settings > Basic and enable the option 'Okay Not To Have Payer Information'.
    2. Set Pricing: Go to Payments > Integration and configure the Price, Currency, and Local Currency.
    3. Frontend Integration: Go to the Project tab, copy the provided HTML snippet, and paste it into your frontend code.

  3. Listen for Paycoinly payment success events on the frontend

    When Paycoinly processes a payment successfully, it triggers a message event to the frontend. The event payload contains transaction details including price, currency, and metadata that were passed during the payment token generation. This allows the UI to update immediately without polling the backend.
    window.addEventListener('message', (event) => {
  // Security check: Ensure the message comes from Paycoinly
  if (event.origin !== 'https://app.paycoinly.xyz') {
    return;
  }
  
  if (event.data.type === 'PAYCOINLY_PAYMENT_COMPLETE') {
    // event.data.payload contains price, currency and metadata
    console.log(event.data.payload);
  }
});

  4. Prerequisites for Paycoinly Manual Integration

    Before starting a manual integration, the following settings must be configured in the Paycoinly dashboard:

    1. Customer Information: In Payments > Settings > Basic, the option "How would you like to receive customer information?" must be set to either "I Want To Know Who Paid" or "My Customers Can Claim Their Money Back".
    2. Platform: In Payments > Settings > Integration, the option "On which platform is your service running?" must be set to "None".

  5. Integrate Paycoinly with WooCommerce or WordPress

    For WooCommerce and WordPress users, the official Paycoinly plugin automates the integration, removing the need for manual webhook or UI setup.

    Setup Steps:

    1. Dashboard Config: Go to Payments > Settings > Integration, select 'WordPress or WooCommerce', and enter your store's domain.
    2. Plugin Installation: Install the Paycoinly plugin from the WordPress admin dashboard.
    3. Plugin Configuration:
      • Navigate to the Paycoinly section in WooCommerce Payments.
      • Enable 'Activate Paycoinly Gateway in Woocommerce'.
      • Enter your API Key.
      • Select the desired payment routing in the Payments section.
      • Save changes.

  6. Implement a secure withdrawal flow integration

    To avoid complex backend logic and ensure security, use a streamlined approach to trigger the Paycoinly withdrawal UI. Instead of calling the API directly from the frontend, create a backend proxy endpoint.
    <!-- Frontend: Button that triggers the backend process -->
<button onclick="window.open('https://your-system-domain/withdrawal-endpoint', 'Withdraw with PayCoinly', 'width=800,height=550,left=200,top=100');">
  Withdraw
</button>

    <!-- Backend Logic for /withdrawal-endpoint (GET):

    1. Call the Withdrawal Token Generation API to get a token.
    2. Redirect the user to the Paycoinly claim URL: https://app.paycoinly.xyz/claim?token={token} -->

  7. Configure Paycoinly for Point-of-Sale (POS) and local businesses

    For physical retail locations (e.g., coffee shops, gyms) that do not require detailed payer information, follow these steps:

    1. Disable Payer Info: Go to Payments > Settings > Basic and select "Okay Not To Have Payer Information".
    2. Set Pricing: Go to Payments > Integration and enter the Price, Currency, and Local Currency.
    3. Display QR: Navigate to the Point of Sale tab and click the Show button to present the payment QR code to the customer.

  8. Implement the core Paycoinly payment flow

    The Paycoinly payment process follows a specific sequence involving the user's frontend, the merchant's backend, and the Paycoinly system. The flow is as follows:

    1. Initiation: The user clicks the 'Pay' button on the frontend, which sends the order id to the merchant's backend.
    2. Price Determination: The merchant backend determines the price based on the provided order id.
    3. Token Generation: The merchant backend calls the Paycoinly Payment Token Generation API, sending the price and order id to receive a payment token.
    4. Redirection: The merchant backend determines the Paycoinly payment UI URL using the token and redirects the user to that URL.
    5. Payment Execution: The user completes the payment within the Paycoinly UI, which submits and processes the payment via Paycoinly's systems.
    6. Notification (Backend): Paycoinly triggers a callback (webhook) to the merchant's backend with the order id to notify them of the payment status, allowing the merchant to record the payment.
    7. Notification (Frontend): Paycoinly notifies the payment UI of success, which then notifies the merchant's frontend.
    sequenceDiagram
  autonumber
  actor user as User
  participant yourFrontend as Your Frontend
  participant paycoinlyUI as Paycoinly Payment UI
  participant backend as Your System
  participant paycoinly as Paycoinly
  
  user->>yourFrontend: Click Pay button
  yourFrontend->>backend: order id
  backend->>backend: Determine price using order id
  backend->>paycoinly: price, order id
  paycoinly->>backend: payment token
  backend->>backend: Determine Paycoinly payment UI url using payment token
  backend->>paycoinlyUI: Redirect to Paycoinly payment UI url
  user->>paycoinlyUI: Make the payment
  paycoinlyUI->>paycoinly: Submit the payment
  paycoinly->>paycoinly: Process the payment
  paycoinly->>backend: Trigger callback URL with order id
  backend->>backend: Record the payment
  paycoinly->>paycoinlyUI: Notify success
  paycoinlyUI->>yourFrontend: Notify success

  9. Generate a withdrawal token for users

    To launch the Paycoinly Withdrawal UI, your backend must generate a unique withdrawal token.

    Process:

    1. Call the 'Getting Customer Balances API' to retrieve the list of coins, their balances, and required metadata (chainId and symbol).
    2. Call the 'Withdrawal Token Generation API' using the user's ID and the balance information stored in your system. Use the chainId and symbol retrieved in the previous step.

    Critical Note: Paycoinly only maintains the aggregate balance of all users. Your system is responsible for tracking and providing the individual user's available balance when calling the Token Generation API.

  10. Install and setup the Paycoinly WordPress plugin

    After configuring the dashboard options, install the Paycoinly plugin via the WordPress admin dashboard. Navigate to the Paycoinly section in the admin dashboard and provide the following:

    • API Key: Your unique API key from the Paycoinly dashboard.
    • Payment Selection: Select the specific payment route that all customer payments from your site should be directed to. Ensure the selected payment is eligible based on your WordPress options configuration.

  11. Implement a backend endpoint to process withdrawal requests

    You must create a POST endpoint on your backend to handle the withdrawal logic and trigger the final request to Paycoinly. This endpoint is called by your frontend when the Paycoinly UI sends a PAYCOINLY_REQUEST_WITHDRAW message.

    Implementation Logic:

    1. Validate that the withdrawal amount/value in the request body does not exceed the user's balance in your system.
    2. If valid, call the Paycoinly 'Making Withdrawal Request API'.
    3. If the API returns a 200 success response, deduct the specified amount from the user's balance in your local database.
    // Expected Request Body
{
  chainId: string,  // Chain ID of the token
  symbol: string,   // Symbol of the token
  amount: string,   // Token amount in wei (or smallest unit)
  value: number,     // Token amount value in currency
  currency: string,  // Currency of value (Fixed to 'USD')
  wallet: string     // Wallet address the user will withdraw to
}

  12. Handle withdrawal requests from the Paycoinly UI via JavaScript

    The Paycoinly Withdrawal UI communicates with your frontend using the window.postMessage API. You must add an event listener to capture the PAYCOINLY_REQUEST_WITHDRAW event and forward the payload to your backend processing endpoint.
    window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.paycoinly.xyz') {
    return;
  }
  if (event.data.type === 'PAYCOINLY_REQUEST_WITHDRAW') {
    console.log(event.data.payload);

    // Send the payload to your backend endpoint
    fetch('/process/withdrawal-request', {
      method: 'post',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event.data.payload)
    })
      .then(() => {
        console.log('Withdrawal request processed successfully');
      });
  }
});