🔐 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:

How It Works

Implementation Options

Zero Authorization can be implemented in two ways:

1. SDK Integration - Using Coinflow’s prebuilt UI with zeroAuthorization=true
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. Pass zeroAuthorization=true to the purchase component to perform a zero authorization instead of a regular purchase.

1
import {CoinflowPurchase} from '@coinflow/react';
2
3
function ZeroAuthCheckout({wallet, connection, onSuccess}) {
4
  return (
5
    <CoinflowPurchase
6
      wallet={wallet}
7
      connection={connection}
8
      merchantId="your-merchant-id"
9
      env="sandbox"
10
      zeroAuthorization={true}
11
      onSuccess={({paymentId}) => {
12
        // Save paymentId for future COF/MIT transactions
13
        console.log('Zero auth successful, paymentId:', paymentId);
14
        onSuccess(paymentId);
15
      }}
16
    />
17
  );
18
}

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:

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

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"
>
  }'

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": "USDC"
>
  }'

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"
>
    }
>
  }'

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"
>
  }'

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": "USDC"
>
  }'

Error Handling

Zero Authorization not enabled. Please contact your integrations representative.

Invalid card data provided

3DS Challenge required

Best Practices

Frequently Asked Questions

Next Steps