> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stablecoin Transfer

> Initialize stablecoin payments with support for multiple tokens and chains

export const payment_method_0 = "crypto_address"

## Overview

Initialize stablecoin payments using supported tokens across multiple blockchain networks. This endpoint supports both inbound and outbound crypto transactions with real-time rate conversion.

## Supported Tokens and Chains

<Card>
  **USDT**

  * Tron (TRX)

  **USDC**

  * Ethereum (ETH)
  * Polygon (MATIC)
  * Avalanche C-Chain (AVAXC)
</Card>

<Warning>
  Ensure you use the correct chain for each token to avoid lost transactions. Not all tokens are supported on all chains.
</Warning>

## Transaction Limits

<Card>
  * Minimum: 18 USDT/USDC
  * Maximum: 50,000 USDT/USDC per transaction

  **Transaction limits may vary based on:**

  * Account verification level
  * Transaction history
  * Selected chain/token
</Card>

## Processing Times

<AccordionGroup>
  <Accordion title="TRX Network">
    * Average: 1-3 minutes
    * Network fee: Low (\<\$2)
    * Block confirmations required: 6
  </Accordion>

  <Accordion title="ETH Network">
    * Average: 5-30 minutes
    * Network fee: Variable (gas fees)
    * Block confirmations required: 12
  </Accordion>

  <Accordion title="MATIC/AVAXC">
    * Average: 1-5 minutes
    * Network fee: Low (\<\$2)
    * Block confirmations required: 15
  </Accordion>
</AccordionGroup>

## Initialize Payment

```http theme={null}
POST /payment-sessions
```

### Request Parameters

<ParamField body="amount" type="integer" required>
  Payment amount in minor units (e.g., cents, kobo)

  * Minimum: 100

  * Must be positive integer

  * Example: 10000 = \$100.00 USD
</ParamField>

<ParamField body="currency" type="string" required>
  ISO currency code

  * Supported: NGN, USD, CAD, USDT, USDC

  * Must match payment method

  * Example: "USD"
</ParamField>

<ParamField body="customer" type="object" required>
  Customer information object

  <Expandable title="Customer Fields">
    <ParamField body="email" type="string" required>
      Valid email address
    </ParamField>

    <ParamField body="first_name" type="string" required>
      Customer's first name
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Customer's last name
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      Phone number in E.164 format
    </ParamField>

    <ParamField body="billing_address" type="object" required>
      Billing address details
    </ParamField>

    <ParamField body="type" type="string" required>
      Must be of type `business` or `individual`
    </ParamField>

    <ParamField body="ip_address" type="string" required>
      Customer's ip address

      * Must be ipv4 e.g 127.0.0.1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  Payment description

  * Maximum length: 200 characters

  * Will appear on statements
</ParamField>

<ParamField body="reference" type="string" required>
  Unique transaction reference

  * Must be unique per transaction

  * Maximum length: 50 characters
</ParamField>

<ParamField body="payment_method" type="object" required>
  Payment method details

  <ParamField body="type" type="string" required>
    * Must be of type: "{payment_method_0}"
  </ParamField>
</ParamField>

<ParamField body="order" type="object" required>
  Order information object

  <Expandable title="Order Fields">
    <ParamField body="identifier" type="string" required>
      Unique identifier
    </ParamField>

    <ParamField body="items" type="object[]" required>
      <Expandable title="Items Fields">
        <ParamField type="string" body="name" required />

        <ParamField type="string" body="type" required>
          type must be one of digital,physical
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional additional data

  * Nested objects allowed
</ParamField>

### Request Example

```json theme={null}
{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+2348118873422",
    "billing_address": {
      "line1": "123 Main St",
      "line2": "234 Feranmi Drive",
      "city": "Springfield",
      "state": "CA",
      "country": "US",
      "zip_code": "12345"
    },
    "ip_address": "127.0.0.1"
  },
  "description": "Crypto Payment",
  "currency": "USD",
  "amount": 100000,
  "direction": "incoming",
  "payment_method": {
    "type": "crypto_address"
  },
  "reference": "crypto-tx-123",
  "order": {
    "identifier": "ORD12345",
    "items": [
      {
        "name": "Digital Product",
        "type": "digital"
      }
    ]
  }
}
```

### Response Example

```json theme={null}
{
  "data": {
    "status": "pending",
    "message": "Payment session initialized",
    "payment": {
      "id": "pay_123abc456def",
      "currency": "USD",
      "amount": 100000,
      "description": "Crypto Payment",
      "payment_method": {
        "address": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY",
        "chain": "TRX",
        "currency": "USDT",
        "type": "crypto_address"
      },
      "status": "pending",
      "date": "2024-03-15T12:00:00Z",
      "mode": "live",
      "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "billing_address": {
          "line1": "123 Main St",
          "line2": "234 Feranmi Drive",
          "city": "Springfield",
          "state": "CA",
          "zip_code": "12345",
          "country": "US"
        }
      },
      "reference": "crypto-tx-123",
      "order": {
        "identifier": "ORD12345",
        "items": [
          {
            "name": "Digital Product",
            "type": "digital"
          }
        ]
      }
    }
  }
}
```

## Validation Rules

<AccordionGroup>
  <Accordion title="Amount Validation">
    * Must be within min/max limits
    * Must be in minor units (cents)
    * Must be a positive integer
  </Accordion>

  <Accordion title="Address Validation">
    * Must match chain format
    * Must be active/valid address
    * Must support token type
  </Accordion>

  <Accordion title="Chain/Token Rules">
    * Token must be supported on chain
    * Chain must be active/operational
    * Network fees must be reasonable
  </Accordion>
</AccordionGroup>

## Rate Conversion

<Info>
  * Exchange rates are locked for 15 minutes
  * Rates include network fees
  * Rate source: aggregated from major exchanges
  * Rate updates: every 30 seconds
</Info>

## Webhooks

Monitor transaction status via webhooks:

* `crypto.payment.pending`- Payment detected but unconfirmed
* `crypto.payment.confirmed`- Required confirmations reached
* `crypto.payment.completed`- Funds credited to account
* `crypto.payment.failed`- Transaction failed or expired

## Best Practices

1. **Security**
   * Validate addresses before displaying
   * Show clear network/token warnings
   * Include QR codes for addresses
2. **User Experience**
   * Display real-time rate updates
   * Show confirmation progress
   * Provide clear payment instructions
3. **Error Handling**
   * Handle network congestion
   * Implement payment expiry
   * Monitor transaction status

<Card title="Need Help?">
  For additional assistance:

  * Check our [Error Handling](/errors) guide
  * Contact [Support](mailto:support@juicyway.com)
  * Join our [Discord](https://discord.gg/juice)
</Card>