Payment Flow & Webhook Documentation

Create Payment Session

The method allows creating a payment flow using Plaid and Checkbook integration for ACH payment processing in the United States.

Base URL:

Production: https://api.floid.app

Endpoint: POST /us/payments/create

Authentication:

Authorization: Bearer YOUR_API_TOKEN

Variables

amount (float) | Payment amount in USD.
sandbox (int) Optional | Test environment:

0: Production (default)
1: Sandbox

Example Body Request:

{
  "amount": 100.50,
  "sandbox": 0
}

Response:

// For production environment
{
  "code": 200,
  "payment_token": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "payment_url": "https://usapayments.floid.io?id=fde35e9f-346c-4b17-9d25-c36vb3f2fc40"
}

// For sandbox environment
{
  "code": 200,
  "payment_token": "sandbox_fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "payment_url": "https://usapayments.floid.io?id=sandbox_fde35e9f-346c-4b17-9d25-c36vb3f2fc40"
}

Webhook Responses

Your webhook endpoint will receive POST requests with the following possible payloads:

Response States

COMPLETED | Payment completed successfully
FAILED | Payment failed at some stage of the process
RISK_DECLINED | Payment declined by risk assessment
PROCESSED | Client deposit processed

Webhook Types

1. Payment Completed Successfully

webhook_type: payment_completed

{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "COMPLETED",
  "amount": 100.50,
  "player_info": {
    "email": "[email protected]",
    "bank_info": {
      "institution": "Chase Bank",
      "account": "****1234"
    }
  },
  "transaction_details": {
    "invoice_id": "inv_1234567890_abc123",
    "processor_token_used": true,
    "digital_check_method": "iav_digital_check",
    "transaction_completed": true
  },
  "timestamp": "2024-01-15T10:35:00.000Z",
  "webhook_type": "payment_completed"
}

2. Payment Failed - General Error

webhook_type: payment_failed

{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "FAILED",
  "amount": 100.50,
  "player_info": {
    "email": "[email protected]",
    "bank_info": {
      "institution": "Chase Bank",
      "account": "****1234"
    }
  },
  "reason": "Payment processing failed",
  "error_details": "Unable to complete payment - general processing error",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "webhook_type": "payment_failed"
}

3. Payment Declined by Risk

webhook_type: payment_risk_declined

{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "RISK_DECLINED",
  "amount": 100.50,
  "player_info": {
    "email": "[email protected]",
    "bank_info": {
      "institution": "Chase Bank",
      "account": "****1234"
    }
  },
  "reason": "Payment declined due to risk assessment",
  "risk_assessment": {
    "risk_score": 85,
    "recommendation": "DECLINE"
  },
  "timestamp": "2024-01-15T10:31:00.000Z",
  "webhook_type": "payment_risk_declined"
}

Sandbox

For the test environment, use "sandbox": 1 in the payment creation request.

Banks enabled for sandbox:

Bank of America
Chase Bank
Wells Fargo
Citibank

Test credentials for the widget:

User: user_good
Password: pass_good

Test cases:

Successful user: user_good - Connection is made successfully and payment is processed.
User with error: user_bad - Connection fails and error webhook is received.
Amount limit: Amounts over $10,000 USD will generate limit exceeded error.

NOTE: Interactions with Plaid Link in sandbox are automatically approved after 7 seconds.

Retry Logic

The system will retry failed webhook deliveries:

Initial attempt
Retry after 1 minute if failed
Retry after 5 minutes if failed
Retry after 15 minutes if failed
Final retry after 1 hour

Flow Summary

Create Payment → POST /us/payments/create
User Bank Connection → User visits payment_url, connects bank via Plaid
Process Payment → System processes automatically
Webhook Delivered → One of the webhook responses listed above