🔐 Zero Authorization

What is Zero Authorization?

A Zero Authorization is a $0.00 authorization transaction that validates a customer’s card and securely stores the credentials for future use—without actually charging them. This enables you to verify card validity, store credentials, and establish authorization for subsequent transactions.

📘 Card Validation Without Charging

Zero Authorization confirms that a card is valid and can be charged, while creating a secure reference for future Card on File (COF) or Merchant Initiated Transactions (MIT).

Key Characteristics

• No Charge: Authorizes the card for $0.00, so the customer is not charged
• Card Validation: Confirms the card is valid and in good standing
• Secure Storage: Credentials are tokenized and stored in Coinflow’s PCI-compliant vault
• Future Authorization: Creates a paymentId reference for subsequent COF/MIT transactions
• CVV Verification: Requires the customer’s CVV for proper authorization

Why Use Zero Authorization?

Zero Authorization is essential for business models where you need to store a customer’s payment method before charging them:

Usage-Based Billing

Store customer cards when they sign up, then charge based on actual usage later

Account Top-Ups

Save payment credentials for automatic balance replenishment when thresholds are met

Free Trials

Validate payment methods for free trial signups without charging until trial ends

Pre-Authorization

Verify payment capability before providing services or access

How It Works

Customer Provides Card Details

Customer enters their card information (including CVV) through your checkout flow.

Zero Authorization is Processed

Coinflow sends a $0.00 authorization to validate the card with the card network.

Credentials are Stored

On success, the card is tokenized and securely stored in Coinflow’s PCI-compliant vault.

You Receive a Payment ID

The response includes a paymentId that you may use as the originalPaymentId for future card on file or merchant initiated transactions.

Card Payment Authorized Webhook

You receive Card Payment Authorized webhook event if subscribed

Implementation Options

Zero Authorization can be implemented in two ways:

1. SDK Integration - Using Coinflow’s prebuilt UI with zeroAuthorizationConfig
2. API Integration - Direct API call to the Zero Authorization endpoint

Option 1: SDK Integration

The simplest way to implement Zero Authorization is using Coinflow’s SDK. You can configure the behavior using zeroAuthorizationConfig

Configuration Options

The zeroAuthorizationConfig prop gives you fine-grained control over the zero authorization UI:

The cardToken value shown above is an example. You must use the actual card token from your customer’s saved payment methods. Card tokens are returned when a customer saves a card through the Coinflow checkout flow.

Basic Example

React

import {CoinflowPurchase} from '@coinflow/react';

function ZeroAuthCheckout({wallet, connection, onSuccess}) {
  return (
    <CoinflowPurchase
      wallet={wallet}
      connection={connection}
      merchantId="your-merchant-id"
      env="sandbox"
      zeroAuthorizationConfig={{ disableSavedPaymentMethods: true }}
      onSuccess={({paymentId}) => {
        // Save paymentId for future COF/MIT transactions
        console.log('Zero auth successful, paymentId:', paymentId);
        onSuccess(paymentId);
      }}
    />
  );
}

React Native

import {CoinflowPurchase} from '@coinflow/react-native';

function ZeroAuthCheckout({wallet, onSuccess}) {
  return (
    <CoinflowPurchase
      wallet={wallet}
      merchantId="your-merchant-id"
      env="sandbox"
      zeroAuthorizationConfig={{ disableSavedPaymentMethods: true }}
      onSuccess={({paymentId}) => {
        // Save paymentId for future COF/MIT transactions
        onSuccess(paymentId);
      }}
    />
  );
}

Vue

<template>
  <CoinflowPurchase
    :wallet="wallet"
    :connection="connection"
    merchantId="your-merchant-id"
    env="sandbox"
    :zeroAuthorizationConfig="{ disableSavedPaymentMethods: true }"
    @success="handleSuccess"
  />
</template>

<script>
export default {
  methods: {
    handleSuccess({paymentId}) {
      // Save paymentId for future COF/MIT transactions
      this.savedPaymentId = paymentId;
    },
  },
};
</script>

Verify Existing Card Example

If you want to re-verify a specific saved card (for example, to update stored credentials), use the cardToken configuration:

React

import {CoinflowPurchase} from '@coinflow/react';

function VerifyCardCheckout({wallet, connection, cardToken, onSuccess}) {
  return (
    <CoinflowPurchase
      wallet={wallet}
      connection={connection}
      merchantId="your-merchant-id"
      env="sandbox"
      zeroAuthorizationConfig={{ cardToken }}
      onSuccess={({paymentId}) => {
        console.log('Card verified, paymentId:', paymentId);
        onSuccess(paymentId);
      }}
    />
  );
}

React Native

import {CoinflowPurchase} from '@coinflow/react-native';

function VerifyCardCheckout({wallet, cardToken, onSuccess}) {
  return (
    <CoinflowPurchase
      wallet={wallet}
      merchantId="your-merchant-id"
      env="sandbox"
      zeroAuthorizationConfig={{ cardToken }}
      onSuccess={({paymentId}) => {
        onSuccess(paymentId);
      }}
    />
  );
}

When using cardToken, if the specified token doesn’t belong to the current user’s saved cards, the UI will automatically fall back to showing the “Add New Card” form.

SDK Benefits

Using the SDK for Zero Authorization automatically handles:

• PCI-compliant card entry UI
• 3DS challenges if required
• Customer consent and compliance messaging
• Error handling and validation

Option 2: API Integration

For headless implementations or custom UI flows, use the Zero Authorization API endpoint directly.

POST /api/checkout/zero-authorization/{merchantId}

View Zero Authorization API Reference

Request Parameters

*Either card or token is required, but not both.

Using a New Card

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/zero-authorization/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123"
    }
  }'

Using a Saved Token

If the customer has a previously tokenized card, you can use the token instead:

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/zero-authorization/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "token": "4111114324324111_bt"
  }'

Response

A successful Zero Authorization returns the payment ID:

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

Save the Payment ID

Store this paymentId securely. You’ll use it as the originalPaymentId when processing future Card on File or Merchant Initiated Transactions.

Using Zero Authorization for Card on File

After completing a Zero Authorization, use the paymentId as the originalPaymentId for Card on File transactions:

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/card-on-file \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 2500,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Customer Must Be Present

Card on File transactions require the customer to actively participate in the transaction. For charges without customer involvement, use Merchant Initiated Transactions.

Learn More About Card on File →

Using Zero Authorization for Merchant Initiated Transactions

For charges where the merchant initiates payment without customer involvement (usage-based billing, account top-ups, etc.), use the paymentId as the originalPaymentId for MIT:

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/merchant-initiated-transaction \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 5000,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
    "settlementType": "Bank"
  }'

MIT Amount Limits with Zero Authorization

When using Zero Authorization as the original payment for MIT, the maximum charge amount is determined by your merchant’s maxZeroAuthAmount setting multiplied by the maxMultiple. Contact your Coinflow integration representative to configure these limits.

Learn More About Merchant Initiated Transactions →

Complete Example Flow

Here’s a complete example showing Zero Authorization followed by both COF and MIT transactions:

Step 1: Perform Zero Authorization

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/zero-authorization/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123"
    }
  }'

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

Step 2a: Card on File Transaction (Customer Present)

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/card-on-file \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 1500,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "paymentId": "650e8400-e29b-41d4-a716-446655440001"
}

Step 2b: Merchant Initiated Transaction (No Customer Involvement)

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/merchant-initiated-transaction \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 3500,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
    "settlementType": "Bank"
  }'

{
  "paymentId": "750e8400-e29b-41d4-a716-446655440002"
}

Error Handling

403 Forbidden - Zero Authorization Not Enabled

Error Message:

Zero Authorization not enabled. Please contact your integrations representative.

Cause: Zero Authorization requires Card on File or MIT to be enabled on your merchant account.

Resolution:

• Contact your Coinflow integration representative to enable Card on File and/or MIT
• Once enabled, Zero Authorization will be available

400 Bad Request - Invalid Card Data

Error Message:

Invalid card data provided

Cause: The card details provided are invalid or incomplete.

Resolution:

• Verify all required card fields are provided (number, expiryMonth, expiryYear, cvv)
• Ensure the card number passes basic validation (Luhn check)
• Confirm expiration date is in the future

412 Precondition Failed - 3DS Challenge Required

Error Message:

3DS Challenge required

Cause: The card issuer requires 3D Secure authentication.

Resolution:

• Handle the 3DS challenge flow by presenting the challenge URL to the customer
• After customer completes verification, retry with the authentication3DS data

Learn More About 3DS →

Best Practices

Always Explain Why You’re Storing Credentials

When performing a Zero Authorization, clearly communicate to the customer why you’re storing their card and how it will be used (e.g., “We’ll save your card for automatic billing based on your usage”).

Handle 3DS Challenges Gracefully

Some card issuers require 3DS authentication even for Zero Authorization. Implement proper 3DS handling to ensure successful card storage.

Store Payment IDs Securely

The paymentId returned is your reference for future transactions. Store it securely and associate it with the customer in your database.

Frequently Asked Questions

Does Zero Authorization charge the customer?

No. Zero Authorization creates a $0.00 authorization that validates the card without charging the customer.

Can I use Zero Authorization with Apple Pay or Google Pay?

No. Mobile wallet payments (Apple Pay, Google Pay) cannot be used with Zero Authorization yet.

What’s the difference between Zero Authorization and tokenization?

Tokenization converts card details into a secure token for storage. Zero Authorization performs tokenization AND validates the card with a $0 authorization, establishing it as a reference for future COF/MIT transactions.

Next Steps

Card on File Transactions

Learn how to process payments with stored credentials when the customer is present

Merchant Initiated Transactions

Process charges without customer involvement using stored credentials

Testing Guide

Test your Zero Authorization implementation

3DS Authentication

Handle 3DS challenges for Zero Authorization