The Blueprint for Global Payments: Deconstructing Crypto & Fiat Flows

As a licensed payments operator, Bluerails builds institutional-grade infrastructure for the global digital economy. Our focus is providing seamless, secure, and reliable rails for both crypto and fiat transactions. This requires a robust and flexible system design.

This post breaks down the "what" of our platform: the core payment and payout flows we enable, and the developer-first API that makes them accessible.

The Core Engine: Pay-ins and Payouts

Our entire system is built to handle the two primary movements of money: pay-ins (receiving funds) and payouts (sending funds). To simplify integration, we use a central Payin object for pay-ins and a Payout object for payouts, providing a consistent structure regardless of the payment rail.

1. Crypto Pay-Ins Our crypto payment flow is a secure, asynchronous "push" payment model.

• When a Payin is created for a crypto payment such as for an invoice payment, our API generates a unique, single-use deposit address.

• The customer sends the specified amount to this address from their wallet.

• Our platform monitors the blockchain for the transaction. After sufficient confirmations, the payment is marked as complete, and we send a webhook notification to the merchant's system.

2. Fiat Pay-Ins (Bank Transfers) For fiat pay-ins, the process is also asynchronous, designed for accurate reconciliation.

• The API generates unique bank account details along with a dedicated reference number for the transaction.

• The customer initiates a standard bank transfer using these details.

• Our system automatically monitors the destination bank account, matching incoming funds to the pending payment using the reference number. Once matched, the status is updated and a webhook is sent.

3. Payouts (Crypto & Fiat) The same infrastructure that powers pay-ins also handles payouts.

• Crypto Payouts: A payout is initiated via an API call specifying the destination address and amount. Our system securely constructs, signs, and broadcasts the transaction to the appropriate blockchain network, monitoring it through to completion.

• Fiat Payouts: We integrate directly with banking partners to process fiat payouts. An API call triggers a transfer to a specified beneficiary bank account, with status updates delivered via webhooks.

The API: Designed for Integration

A well-designed platform requires a clean API. We prioritize developer experience with a focus on clarity and predictability.

• Authentication: Simple and secure Basic Authentication using an Organization ID and an environment-specific API Key.

• Resource Identifiers: All IDs are prefixed for immediate context (e.g., pi_ for a Pay-in, po_ for a Payout, org_ for an Organization). This simplifies logging, debugging, and support.

• Webhooks: Essential for our asynchronous flows. We send cryptographically signed webhooks for all critical events, ensuring your system is always synchronized with ours. Key events include:

  • payment.processing

  • payment.succeeded

  • payment.failed

  • payout.created

  • payout.succeeded

  • payout.failed

This unified approach to handling different asset types is the foundation of our service. In the next post, we will explore the institutional-grade infrastructure that makes these complex flows possible.