How To: Migrate to the Coinflow Fraud SDK

Overview

The Coinflow Fraud SDK replaces the device-signal setup your mobile app does today for chargeback protection. Instead of installing and initializing a device module with credentials, reading a device ID, and attaching several protection headers, your app:

1. Initializes the Coinflow Fraud SDK once with your merchantId.
2. Asks it for headers at checkout time.
3. Sends the single x-device-id header it returns on your Coinflow API request.

The SDK collects every device, session and purchase signal Coinflow uses to score a payment and packs them into that one header. You don’t configure individual signal sources, and you don’t need credentials from Coinflow to initialize it.

What changes for your integration

Who should migrate

This guide is for iOS, Android and React Native apps that call Coinflow’s APIs directly, either from the app or through your own backend.

Backward compatibility

Your current integration keeps working, and there is no cutoff date. Coinflow’s API accepts both the existing headers and the Coinflow Fraud SDK’s header on the same endpoints, so:

• You can migrate one app at a time, in a normal app release.
• Customers still on an older version of your app keep being protected after you ship the migrated version.
• No API, endpoint or request-body changes are required; only your protection headers change.

Prerequisites

• Chargeback protection enabled for your merchant account. Contact Coinflow’s integrations team if it isn’t.
• Your Coinflow merchantId.
• iOS: iOS 15 or later, built with Xcode 26 or later, and CocoaPods.
• Android: minSdk 24 or later, built with Gradle on JDK 17 or later.
• React Native: a development build or bare React Native app, targeting iOS 15.1 or later. The SDK includes a native module, so it doesn’t run in Expo Go.

Migrate your app

platform :ios, '15.0'
target 'YourApp' do
  use_frameworks!
  pod 'CoinflowFraud', :git => 'https://github.com/coinflow-labs-us/coinflow-swift-fraud.git', :tag => 'v0.2.0'
end

pluginManagement {
  repositories {
    google()
    mavenCentral()
    gradlePluginPortal()
  }
}
plugins {
  id("cash.coinflow.fraud.repositories") version "0.1.1"
}

dependencies {
  implementation("cash.coinflow:coinflow-fraud:0.1.1")
}

npm install @coinflowlabs/react-native-fraud

import CoinflowFraud
Task {
  await CoinflowFraud.shared.initialize(merchantId: "your-merchant-id", env: .sandbox)
}

import cash.coinflow.fraud.CoinflowFraud
import cash.coinflow.fraud.CoinflowFraudEnv
class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      CoinflowFraud.initialize(this@MainActivity, "your-merchant-id", CoinflowFraudEnv.SANDBOX)
    }
  }
}

import {CoinflowProtectionProvider} from '@coinflowlabs/react-native-fraud';
export default function App() {
  return (
    <CoinflowProtectionProvider merchantId="your-merchant-id" env="sandbox">
      <RootNavigator />
    </CoinflowProtectionProvider>
  );
}

let fraudHeaders = await CoinflowFraud.shared.purchaseHeaders()
// ["x-device-id": "<opaque value>"]
for (name, value) in fraudHeaders {
  request.setValue(value, forHTTPHeaderField: name)
}

val fraudHeaders = CoinflowFraud.purchaseHeaders()
// mapOf("x-device-id" to "<opaque value>")
val request = Request.Builder()
  .url(checkoutUrl)
  .apply { fraudHeaders.forEach { (name, value) -> header(name, value) } }
  .post(checkoutBody)
  .build()

import {useCoinflowFraudHeaders} from '@coinflowlabs/react-native-fraud';
function Checkout() {
  const getFraudHeaders = useCoinflowFraudHeaders();
  async function pay() {
    const response = await fetch(checkoutUrl, {
      method: 'POST',
      headers: {
        ...(await getFraudHeaders()), // {'x-device-id': '<opaque value>'}
        'content-type': 'application/json',
      },
      body: JSON.stringify(checkoutBody),
    });
  }
}

// Your backend, forwarding the value your app sent
await fetch(`https://api-sandbox.coinflow.cash/api/checkout/card/${merchantId}`, {
  method: 'POST',
  headers: {
    'x-device-id': deviceHeaderFromApp,
    'x-coinflow-client-ip': customerIp, // the customer's IP, not your server's
    'x-coinflow-auth-session-key': sessionKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify(checkoutBody),
});

Test your migration

1. Initialize the SDK with env: sandbox and point your app at https://api-sandbox.coinflow.cash.
2. Run a sandbox checkout and confirm the request to Coinflow includes a non-empty x-device-id header.
3. Confirm the checkout response matches what you saw before migrating.
4. Before releasing, switch to env: prod together with your production API base URL.

Troubleshooting