Integrating 1st/3rd-Party Payments

1. What is the definition of first-party payment and third-party payment in Harbor?

OwlPay Harbor supports both first-party and third-party payment models to meet the needs of various integration scenarios:

• First-Party Payment Model:
  In this model, the platform or service provider handles the collection of fiat or crypto payments on its own. After collecting funds, it uses OwlPay Harbor's API to instruct the system where to send the funds (e.g., to a merchant or a user). OwlPay Harbor does not participate in the collection process, and KYB is required only for the platform itself.

• Third-Party Payment Model:
  In this model, the platform acts as a facilitator, onboarding its end-users directly into OwlPay Harbor using the Customer API. Each user goes through KYC/KYB, receives a unique deposit address and access to on/off-ramp services. This model allows platforms to set transaction-level fees while offloading custody and settlement logic to Harbor.

2. OwlPay Harbor Architecture

OwlPay Harbor is a modular on-chain fund flow platform, offering the following components:

• Customer Management Module: Registers merchants and users, links external IDs, and performs KYC/KYB during onboarding.
• Bank Account Management Module: Manages users' fiat bank account information for withdrawal.
• Crypto Address Management Module: Binds crypto addresses to a Customer.
• Transfer Module: Handles on-ramp, off-ramp, cross-chain transfers.
• Webhook Notification Module: Pushes real-time status updates for transactions and deposits.

3. How to Use OwlPay Harbor for First-Party Payments

1. The application collects fiat or crypto funds independently.
2. Onboard yourself as a Customer, and select business as type.
3. When payment is ready, it calls the POST /transfers API and sets the on_behalf_of field to the customer.uuid that you just onboarded yourself.
4. Harbor processes the payment based on the given parameters and returns a result.

In this model, the application controls the incoming funds while OwlPay Harbor handles execution of on-chain transactions.

4. How to Use OwlPay Harbor for Third-Party Payments

1. The platform calls POST /customers to register its end users into Harbor.
2. Harbor performs KYC(individual)/KYB(business) on each end user.
3. Users access on/off-ramp services:
   • On-Ramp: Users convert fiat to USDC into their linked on-chain address.
   • Off-Ramp: Users send USDC to Harbor and receive fiat in their bank accounts.
4. The platform tracks status via webhooks and may define per-transaction commission rules.

5. Use Case: PSP Integration Example (Third-Party Payment Model)

Let’s say a Payment Service Provider (PSP) wants to integrate OwlPay Harbor to handle on-chain settlement:

• The PSP gets API credentials from Harbor team.
• Its merchants or creators sign up through the PSP’s interface.
• The PSP registers each user via Harbor’s Customer API.
• Harbor performs KYC/KYB for each user.
• Each user receives a unique crypto address and bank account.
• The PSP can track deposits via webhooks, and use Transfer API to enable payout, profit sharing, or cross-chain settlement.
• The PSP can also configure a commission fee structure per transaction to automate revenue collection.

6. Best Practices and Considerations

• Assign a unique Customer UUID per user for better traceability and ledger clarity.
• Use crypto address binding to reduce complexity when calling Transfer API.
• Ensure KYC/KYB checks are complete before enabling payment features.
• Enable webhook notifications to receive real-time transaction status.
• Set up business logic controls such as whitelisted destinations, withdrawal limits, or transfer rules.

7. Conclusion

OwlPay Harbor offers a modular, API-first infrastructure for managing blockchain-based fund flows. Whether you're implementing a first-party model (direct control over funds) or enabling your users through a third-party integration, Harbor provides the compliance, transparency, and flexibility required to scale.

From KYC/KYB, to on-chain transfers and fiat settlement, OwlPay Harbor is the backbone for PSPs and platforms entering the Web3 finance landscape.