Pay-in to wallet

Purpose: Get pay-in resources for adding funds to a customer's or business's wallet via crypto or fiat.

The pay-in endpoint provides two distinct flows:

Crypto Pay-ins: Returns a wallet address for receiving cryptocurrency from external wallets
Fiat Pay-ins (Onramp): Returns a payment link for customers/businesses to buy crypto with card, bank transfer, or Apple Pay

Choose the Right Flow: Use crypto payins when customers are sending from their own wallets (MetaMask, Coinbase, etc.). Use fiat payins when customers are buying crypto with traditional payment methods.

Business Customer Support: This endpoint fully supports both individual customers (cus_xxx) and business customers (biz_xxx). Simply provide the wallet ID for either customer type.

When to Use This Endpoint

Use pay-in endpoint for:

Getting a wallet address for crypto transfers from external wallets
Creating onramp payment links for fiat-to-crypto purchases
Providing customers (individual or business) multiple ways to add funds to their wallet

Don't use pay-in endpoint for:

Moving crypto between wallets (use /v1/transfers instead)
Checking balances (use /v1/balances instead)

Wallet ID Required: This endpoint requires a wallet ID (wal_xxx). Create a wallet first using POST /v1/wallets for individual customers or POST /v1/businesses/:id/wallets for business customers if they don't have one yet.

How It Works

Crypto Pay-ins

Call the endpoint with a wallet ID and crypto rail (e.g., polygon)
Receive the wallet address for that network
Share the address with your customer to send crypto from their external wallet
Monitor deposits via webhooks or balance checks

Fiat Pay-ins (Onramp)

Call the endpoint with a wallet ID, fiat rail (e.g., card), amount, and currency
Receive an onramp URL that handles the payment flow
Redirect the customer to the payment URL
Crypto arrives in the wallet automatically after successful payment

Response Examples

Crypto Pay-in Response

{
  "id": "tr_abc123xyz",
  "to": "wal_abc123",
  "rail": "polygon",
  "resource": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "state": "awaiting_funds"
}

Fiat Pay-in Response

{
  "id": "tr_def456uvw",
  "to": "wal_abc123",
  "rail": "card",
  "resource": "https://pay.swipelux.com/checkout/abc123def456",
  "state": "awaiting_funds"
}

Common Use Cases

These use cases apply to crypto-to-crypto flows where users are depositing from external wallets.

Display Pay-in QR Code

Generate a QR code from the payin address for easy mobile scanning. Use the address returned from the pay-in endpoint with any QR code library.

Show Pay-in Instructions

Provide clear instructions to your customers:

Copy the address from the API response
Open your crypto wallet app
Send USDC on the specified network to this address
Wait for blockchain confirmation (1-3 minutes)

Warning: Only send assets on the specified network. Sending assets from other networks will result in loss of funds.

Monitor Incoming Deposits

Monitor balance changes to detect when crypto payins arrive:

Request:

GET /v1/customers/{customerId}/balance
X-API-Key: YOUR_SECRET_API_KEY

Response:

{
  "customerId": "cus_abc123",
  "balance": 150.50,
  "currency": "USD",
  "updatedAt": "2024-01-15T10:35:00Z"
}

Poll this endpoint periodically to detect balance increases. For real-time notifications, use webhooks.

Note: External crypto payins (sent to the payin address) appear directly in the wallet balance. They don't create transfer records since the transfer happened on-chain, outside of the Swipelux API.

Request Parameters

Field	Type	Required	Description
`to`	string	Yes	Wallet ID (e.g., `wal_abc123`)
`rail`	string	Yes	Payment rail: `polygon` (crypto) or `card`, `wire`, `apple_pay`, `open_banking` (fiat)
`amount`	string	For fiat only	Amount to payin (required for fiat rails)
`currency`	string	For fiat only	Currency code (e.g., `USD`, `EUR`) - required for fiat rails

Response Fields

Field	Type	Description
`id`	string	Transfer ID for tracking the payin (e.g., `tr_abc123`)
`to`	string	Wallet ID from request
`rail`	string	Payment rail from request
`resource`	string	Wallet address (for crypto) or payment URL (for fiat)
`state`	string	Pay-in state (`awaiting_funds`, `pending`, `completed`, etc.)
`hints`	array	Optional suggestions for next API calls

Error Responses

Status	Error	Solution
`400`	Invalid rail	Check supported rails: `polygon`, `card`, `wire`, `apple_pay`, `open_banking`
`400`	Amount and currency required	For fiat rails, include both `amount` and `currency` fields
`404`	Wallet not found	Create the wallet first using `POST /v1/wallets`
`500`	Failed to create onramp payin	Retry the request or contact support

Best Practices

Network Mismatch Warning: Always display the network name (e.g., "Polygon") prominently when showing payin addresses. Sending assets on the wrong network will result in permanent loss.

Address Reusability (Crypto Pay-ins)

Do: Call the API once and store the address

Call POST /v1/payin with rail: "polygon"
Store the returned address in your database
Reuse the stored address for all subsequent displays

Don't: Call the API every time you need to show the address

This wastes API calls
The address doesn't change, so caching is safe

Fiat Pay-in Flow

For fiat payins, always generate a fresh payment URL:

Call POST /v1/payin with amount, currency, and rail
Get the payment URL from the resource field
Redirect customer to the URL or display in iframe
Wait for webhook notification of payment completion

User Experience

Show Network Clearly: Display "Polygon Network" or "Polygon (MATIC)" prominently
Copy Button: Add a one-click copy button next to the address
QR Code: Generate a QR code for mobile users
Minimum Amounts: Inform users about any minimum payin amounts
Confirmation Time: Set expectations (e.g., "1-3 minutes on Polygon")

Security

Never expose your API key in frontend code
Always call this endpoint from your backend
Validate webhook signatures before processing payin notifications
Log all payin address requests for audit purposes

Next Steps

After creating deposits:

Track Balances - Monitor customer balances after deposits
Configure Webhooks - Get notified when payins arrive
Create Crypto Transfers - Send crypto from customer wallets to external addresses