PayoutsImplementation Methods

Bank Authentication

Merchants can learn how to use Coinflow's UI for authentication and redirect withdrawers upon successful bank auth.

Overview

The Bank Authentication UI allows users to connect their bank accounts or debit cards for payouts. This prebuilt interface handles the entire authentication flow, including support for Plaid integration and card tokenization.

When to Use This Method

Perfect For

Choose this when you need bank/card linking without building UI

  • Any web framework (React, Vue, Angular, vanilla JS)
  • Teams wanting quick bank authentication (2-3 days)
  • Custom payout UI with Coinflow-managed bank linking
  • Merchant-initiated payouts with user bank accounts
  • Separating bank linking from payout initiation
  • Mobile apps with webview support

Integration time: 2-3 days for iframe embedding

Consider Alternatives If

These scenarios require different implementation methods

Separation of Concerns

This method is ideal when you want to handle bank/card linking separately from payout initiation. After users link their accounts via this UI, you can initiate payouts programmatically using the API Integration endpoints.

Implementation Steps

1

Generate a Session Key

Before embedding the authentication UI, you need to generate a session key for the user.

  • Use the Get Session Key API to create a session key
  • Session keys are valid for 30 minutes and must be refreshed after expiration
  • Each session key is unique to a specific user (identified by their customerId)
2

Embed the Bank Authentication Flow in an Iframe

Embed the Coinflow authentication UI in your application using an iframe. Replace the following parameters with your own values:

  • YOUR_MERCHANT_ID - Your Coinflow merchant identifier
  • sessionKey - The session key generated in Step 1
  • bankAccountLinkRedirect - URL-encoded redirect destination after successful authentication

Sandbox URL Format:

https://sandbox.coinflow.cash/solana/withdraw/YOUR_MERCHANT_ID?sessionKey=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY2hpcG53aW5fdXNlcl8xIiwibWVyY2hhbnRJZCI6InRlc3R0ZXN0IiwiaWF0IjoxNzMxOTY3MTA1LCJleHAiOjE3MzIwNTM1MDV9.q25hymKUAxalqI0mgIQg8AQ7Q_8X5gGzOX60BBNrtW4&bankAccountLinkRedirect=https%3A%2F%2Fwww.google.com
3

Use Production URL for Live Environment

When deploying to production, update the base URL to:

https://coinflow.cash/

Account Linked Message

The iframe emits a message with the method field of accountLinked when authentication is successful. This is useful if you have the iframe embedded in a modal and want to close it programmatically. See this recipe to learn how to listen for the accountLinked message.

Demo


Filtering Account Types

You can control which authentication options are displayed to users by using the allowedWithdrawSpeeds URL parameter. This is useful when you want to limit users to specific payout methods.

Available Options

Parameter ValueAccount Types Shown
standard,same_day,cardBank accounts and debit cards
cardDebit cards only
standardBank accounts only

Examples

Allow Card and Bank Connections:

https://sandbox.coinflow.cash/solana/withdraw/YOUR_MERCHANT_ID?sessionKey=YOUR_SESSION_KEY&bankAccountLinkRedirect=https%3A%2F%2Fwww.google.com&allowedWithdrawSpeeds=standard%2Csame_day%2Ccard

Allow Only Card Account Connections:

https://sandbox.coinflow.cash/solana/withdraw/YOUR_MERCHANT_ID?sessionKey=YOUR_SESSION_KEY&bankAccountLinkRedirect=https%3A%2F%2Fwww.google.com&allowedWithdrawSpeeds=card

Allow Only Bank Connections:

https://sandbox.coinflow.cash/solana/withdraw/YOUR_MERCHANT_ID?sessionKey=YOUR_SESSION_KEY&bankAccountLinkRedirect=https%3A%2F%2Fwww.google.com&allowedWithdrawSpeeds=standard

FAQ / Troubleshooting

  1. Why is the debit card input field not loading?

If you embed the bank auth url in an iframe and the input card number token field fails to load, try passing the origins field. Origins should be a url encoded array containing your url and any ancestors. Example: https://sandbox.coinflow.cash/solana/withdraw/YOUR_MERCHANT_ID?sessionKey=YOUR_SESSION_KEY&origins=%5B%22https%3A%2F%2Fmywebsite.com%22%5D