BlueSnap - ACH Direct Debit

BlueSnap is a global payment platform that provides payment processing solutions for merchants worldwide. The ACH Direct Debit integration enables US merchants to accept bank account payments directly. Buyers enter their bank account and routing numbers in a BlueSnap-hosted form embedded as a popup, and funds are debited via the ACH network. ACH payments are asynchronous — the transaction enters a pending state immediately after the buyer submits their details, and settlement typically takes 1–3 business days.

Setup

BlueSnap provides a self-service sign-up for a sandbox account. To sign up, visit the BlueSnap sign-up page and fill in the required details.

Credentials

When setting up BlueSnap ACH in the dashboard, configure the following credentials:

API User Key - Your BlueSnap API User Key
API Password - Your BlueSnap API Password
Webhook Security Header - Optional security header for webhook signature validation

Connector configuration

After setting up your BlueSnap ACH connector in the dashboard, configure how transactions are routed to it. Choose one of the following options:

Using Flow - Configure BlueSnap ACH as the target connector in Flow to automatically route ACH transactions to this connector
Using the API - Explicitly set the payment_service_id parameter to the BlueSnap ACH connector ID when creating transactions. This overrides any Flow routing rules.

The connector ID can be found in the dashboard under Connections -> Configured connections.

Capabilities

Supported countries

Supported currencies

Integration

BlueSnap ACH uses a redirect integration where BlueSnap’s hosted bank account form is loaded in a popup on your page. The buyer enters their account and routing numbers in the popup, and Gr4vy handles communication with BlueSnap to complete the payment. ACH settlement is asynchronous. After the buyer submits the form the transaction enters a pending state. BlueSnap sends webhooks as the payment progresses:

Event	Description
`CHARGE_PENDING`	The bank debit has been submitted and is awaiting settlement.
`CHARGE`	Settlement confirmed. Funds have been captured from the buyer’s bank account.
`DECLINE`	The debit was rejected by the buyer’s bank.
`FRAUD_DECLINE`	The transaction was declined due to fraud screening.
`REFUND`	A refund has been processed successfully.

Configure your BlueSnap account to send IPN notifications to your Gr4vy webhook endpoint. The webhook security header is optional but recommended to validate that notifications originate from BlueSnap.

Redirect integration

Start by creating a new transaction with the following required fields.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "USD",
        Country = "US",
        Intent = "capture",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "ach",
                    Country = "US",
                    Currency = "USD",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
    }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodAch
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method:      method,
    Country:     country,
    Currency:    currency,
    RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    Intent:        gr4vy.Pointer(components.TransactionIntentCapture),
    PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("USD")
        .country("US")
        .intent(TransactionIntent.CAPTURE)
        .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
            .method(RedirectPaymentMethodCreateMethod.ACH)
            .country("US")
            .currency("USD")
            .redirectUrl("https://example.com/callback")
            .build()))
        .build())
    .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'USD',
    country: 'US',
    intent: 'capture',
    paymentMethod: new RedirectPaymentMethodCreate(
        method: 'ach',
        country: 'US',
        currency: 'USD',
        redirectUrl: 'https://example.com/callback'
    )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="USD",
    country="US",
    intent="capture",
    payment_method={
        "method": "ach",
        "country": "US",
        "currency": "USD",
        "redirect_url": "https://example.com/callback",
    }
)

const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "USD",
    country: "US",
    intent: "capture",
    paymentMethod: {
        method: "ach",
        country: "US",
        currency: "USD",
        redirectUrl: "https://example.com/callback"
    }
})

After the transaction is created, the API response includes payment_method.approval_url and the buyer_approval_pending status.

{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.sandbox.spider.gr4vy.app/connectors/bluesnap/ach.html?token=..."
  },
  "method": "ach"
}

Open the approval_url in a popup so the buyer can enter their bank account and routing numbers in the BlueSnap-hosted form. After the buyer submits the form they are redirected to the redirect_url you provided. Do not rely solely on the redirect — either poll the transaction or (recommended) rely on webhooks to detect the final status.

Recurring payments

ACH Direct Debit via BlueSnap supports storing the bank account for later reuse. Set store: true on the payment method when creating the transaction.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "USD",
        Country = "US",
        Intent = "capture",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "ach",
                    Country = "US",
                    Currency = "USD",
                    RedirectUrl = "https://example.com/callback",
                    Store = true,
                }
            ),
    }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodAch
redirectUrl := "https://example.com/callback"
store := true

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method:      method,
    Country:     country,
    Currency:    currency,
    RedirectURL: redirectUrl,
    Store:       &store,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    Intent:        gr4vy.Pointer(components.TransactionIntentCapture),
    PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("USD")
        .country("US")
        .intent(TransactionIntent.CAPTURE)
        .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
            .method(RedirectPaymentMethodCreateMethod.ACH)
            .country("US")
            .currency("USD")
            .redirectUrl("https://example.com/callback")
            .store(true)
            .build()))
        .build())
    .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'USD',
    country: 'US',
    intent: 'capture',
    paymentMethod: new RedirectPaymentMethodCreate(
        method: 'ach',
        country: 'US',
        currency: 'USD',
        redirectUrl: 'https://example.com/callback',
        store: true
    )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="USD",
    country="US",
    intent="capture",
    payment_method={
        "method": "ach",
        "country": "US",
        "currency": "USD",
        "redirect_url": "https://example.com/callback",
        "store": True,
    }
)

const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "USD",
    country: "US",
    intent: "capture",
    paymentMethod: {
        method: "ach",
        country: "US",
        currency: "USD",
        redirectUrl: "https://example.com/callback",
        store: true
    }
})

Gr4vy creates a BlueSnap vaulted shopper when the transaction is initiated. After the buyer fills in their bank details and the CHARGE_PENDING webhook is received, a stored payment method token is issued that can be used for subsequent payments without the buyer re-entering their bank details. See Recurring payments for an overview of storing and reusing payment methods.

Testing

BlueSnap provides test routing and account numbers for sandbox environments.

Scenario	Routing Number	Account Number
Approved transaction	`998877665`	`223344556`
Declined transaction	`987654321`	`123456789`
Format validation error	`123456789`	`123456789`

Use any US bank account holder name and address for the remaining fields.

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

BlueSnap - ACH Direct Debit

Setup

Credentials

Connector configuration

Capabilities

Supported countries

Supported currencies

Integration

Redirect integration

Recurring payments

Testing

​Setup

​Credentials

​Connector configuration

​Capabilities

​Supported countries

​Supported currencies

​Integration

​Redirect integration

​Recurring payments

​Testing

Setup

Credentials

Connector configuration

Capabilities

Supported countries

Supported currencies

Integration

Redirect integration

Recurring payments

Testing