---
updatedAt: 2026-09-16T10:59:27.000Z
agentTools:
  projectIndex: https://readme.floid.io/llms.txt
---

# Payin USA

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

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

### Response:

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

```json
// 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`

```json
{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "COMPLETED",
  "amount": 100.50,
  "player_info": {
    "email": "recipient@example.com",
    "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`

```json
{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "FAILED",
  "amount": 100.50,
  "player_info": {
    "email": "recipient@example.com",
    "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`

```json
{
  "payment_id": "fde35e9f-346c-4b17-9d25-c36vb3f2fc40",
  "status": "RISK_DECLINED",
  "amount": 100.50,
  "player_info": {
    "email": "recipient@example.com",
    "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

1. **Create Payment** → `POST /us/payments/create`
2. **User Bank Connection** → User visits payment\_url, connects bank via Plaid
3. **Process Payment** → System processes automatically
4. **Webhook Delivered** → One of the webhook responses listed above