Stripe Bank Transfer

Overview

This guide explains how to integrate Stripe Bank Transfer payments with Vrio's API for ACH and SEPA direct bank transfers. Stripe Bank Transfer allows customers to pay directly from their bank accounts, providing a cost-effective payment method for larger transactions.

Supported Transfer Types

Vrio's Stripe Bank Transfer integration supports:

1. ACH Bank Transfers (US)

Currency: USD only
Processing Time: 1-3 business days
Benefits: Lower transaction fees, suitable for larger amounts
Customer Experience: Secure bank account verification through Stripe

2. SEPA Direct Debit (Europe)

Currency: EUR only
Processing Time: 1-2 business days
Benefits: Pan-European coverage, cost-effective
Customer Experience: IBAN-based payment collection

Prerequisites

Before implementing Stripe Bank Transfer, ensure you have:

Stripe Account Configuration:
- Bank Transfer enabled in Stripe Dashboard under "Payments → Payment Methods"
- Appropriate regional settings (US for ACH, Europe for SEPA)
- Webhook endpoints configured for payment status updates
Vrio Merchant Setup:
- Stripe merchant account configured in Vrio dashboard
- Bank Transfer payment method added to your merchant account
- Payment Method ID 13 available for bank transfers

Vrio API Integration

Step 1: Create an Order

First, create an order using Vrio's order creation endpoint:

curl -X POST "https://api.vrio.app/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "connection_id": 1,
    "campaign_id": 18,
    "offers": "[{\"offer_id\":89, \"order_offer_quantity\": 1,\"order_offer_price\":0.50}]",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe",
    "bill_phone": "+1234567890",
    "bill_address1": "123 Main St",
    "bill_city": "Anytown",
    "bill_state": "NY",
    "bill_zipcode": "12345",
    "bill_country": "US",
    "ship_address1": "123 Main St",
    "ship_city": "Anytown",
    "ship_state": "NY", 
    "ship_zipcode": "12345",
    "ship_country": "US"
  }'

This will return an order object with an order_id.

Step 2: Process Bank Transfer Payment

Use the order processing endpoint, Vrio will determine if ACH or SEPA based on the currency of the transaction.

ACH Bank Transfer (US)

curl -X POST "https://api.vrio.app/orders/{order_id}/process" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "payment_method_id": 13,
    "merchant_id": 456,
    "redirect_url": "https://yoursite.com/payment/return"
  }'

Response will include:

{
  "success": true,
  "order_id": 12345,
  "post_data": "https://checkout.stripe.com/c/pay/cs_test_xxxxxxxxxxxxx#fidxxxxxxxxxxxxx",
  "response_code": 101,
  "message": "Order processed successfully"
}

Note: Bank transfer payments typically return response_code: 101, which indicates that the order requires completion after the customer returns from Stripe. For more information about handling 101 response codes, see our detailed guide.

Step 3: Redirect Customer to Stripe

Important: After processing the order, you must redirect the customer to the Stripe-hosted page using the post_data URL from the response.

// Redirect customer to Stripe checkout page
window.location.href = response.post_data;

The customer will complete the bank transfer setup through Stripe's secure interface. After completion, they will be redirected back to your redirect_url with a session_id query parameter.

Step 4: Handle Return from Stripe

When the customer returns to your redirect_url, extract the session_id from the query parameters:

// Extract session_id from URL query parameters
const urlParams = new URLSearchParams(window.location.search);
const sessionId = urlParams.get('session_id');

Step 5: Complete the Order

Important: Check the response code from Step 2. If it's 101, you must complete the order using the session_id returned from the redirect:

curl -X POST "https://api.vrio.app/orders/{order_id}/complete" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "transaction_token": "cs_test_xxxxxxxxxxxxx"
  }'

Note: Use the session_id from the redirect URL as the transaction_token in the completion request.

Payment Flow Overview

Customer Initiates Payment: Customer selects bank transfer as payment method
Create Vrio Order: Your backend creates an order through Vrio API
Process Bank Transfer: Your backend processes the order with payment_method_id: 13
Get Redirect URL: Vrio returns a post_data URL and response_code: 101
Redirect to Stripe: Customer is redirected to Stripe Checkout using the post_data URL
Bank Authorization: Customer authorizes the bank transfer through their banking interface
Return to Merchant: Stripe redirects customer back to your redirect_url with session_id
Complete Vrio Order: Your backend completes the order using the session_id as transaction_token
Payment Processing: Bank transfer is processed (1-3 business days)

Important Considerations

Key Constraints and Limitations

Processing Only: Bank transfers only work when processing orders directly - they are not compatible with authorize and capture workflows
Stripe Only: Bank transfer payments are only supported through Stripe, not other payment processors
Redirect Required: Customers will always be redirected to the specified redirect_url after completing the transaction on Stripe, regardless of approval status
Completion Required: Orders with bank transfer payments that return response_code: 101 must be completed using the /complete endpoint

Processing Times

ACH Transfers: 1-3 business days for processing
SEPA Direct Debit: 1-2 business days for processing
Instant Verification: Bank account verification happens during Checkout

Transaction Limits

ACH: Check with your Stripe account for limits
SEPA: Generally €5,000 per transaction, varies by country
Minimum: Usually $0.50 USD or €0.50 EUR

Common Issues

"Payment method not available" Error

Ensure Bank Transfer is enabled in Stripe Dashboard
Verify merchant account has payment method ID 13 configured
Check regional availability (ACH for US, SEPA for EU)

Order Processing Fails

Ensure redirect_url is properly formatted and accessible
Verify session_id is valid and not expired
Check merchant_id matches your Vrio configuration

For additional support, consult the Stripe Bank Transfer Documentation and Stripe Checkout Reference.