Merchant On-ramp (Fiat Deposit) Integration
Accept fiat payments and receive cryptocurrency payouts. This hosted integration handles the entire payment flow, from user authorization to crypto settlement.
Integration Type
External Link Hosted - Payment flow is hosted by Yugo
Process Overview
- Merchant Onboarding (one-time setup) - Yugo configures your account with payment currency, cryptocurrency, blockchain network, and wallet address
- Create Session - Call the generate-link endpoint with payment details and user information
- Redirect User - Send the user to the hosted payment link
- Payment Processing - Yugo handles the payment flow
- Settlement - Yugo executes the crypto payout to your wallet
Merchant Onboarding
Before using the API, your account must be configured by Yugo administrators:
| Configuration | Description | Common Values |
|---|---|---|
| Payment Currency | Fiat currency for payments | EUR |
| Cryptocurrency | Crypto asset for payouts | USDC |
| Blockchain Network | Network for crypto payouts | Polygon |
| Wallet Address | Your wallet for receiving payouts | Your Web3 address |
Contact your Yugo integration team to complete onboarding.
API Endpoints
Generate Hosted Payment Link
Create a hosted payment session and get a redirect URL.
POST https://api.yugo.finance/payments/on-ramp-merchant/hosted/generate-link
Headers
| Header | Value |
|---|---|
x-api-key | Your API key |
Request Body
json
{
"amount": 100.0,
"names": "John Doe",
"userId": "merchant-123",
"userEmail": "john.doe@gmail.com",
"userAddress1": "123 Main St, Sofia, Bulgaria",
"userIpAddress": "87.126.116.201",
"webhookUrl": "https://yourdomain.com/webhook",
"webhookPayload": "internal-order-id-xyz",
"revision": "internal-order-id-xyz",
"hostedRedirectUrl": "https://yourdomain.com/users/merchant-123"
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | ✅ | Amount in EUR. Minimum: 5 EUR, Maximum: 5000 EUR |
names | string | ✅ | Full name of the user |
userId | string | ✅ | Unique user ID in your system |
userEmail | string | ✅ | User's email address |
userAddress1 | string | ✅ | User's residential address |
userIpAddress | string | ❌ | End-user's public IP address |
webhookUrl | string | ❌ | Your backend endpoint for status updates |
webhookPayload | string | ❌ | Arbitrary string echoed back in webhooks |
revision | string | ❌ | Internal reference ID |
hostedRedirectUrl | string | ✅ | URL to redirect user after clicking "back to merchant" |
Note: Payment currency, cryptocurrency, blockchain network, and wallet address are configured during onboarding and not included in API requests.
Response
json
{
"hostedLink": "https://checkout.yugo.finance/s/sess_a1b2c3d4e5f6g7h8i9j",
"expiresAt": "2025-04-17T11:12:34.567Z"
}Important:
- OTT (One-Time Token) expires 2 minutes after link generation
- Session expires 15 minutes after link generation
Get Transaction
Retrieve transaction details and status.
GET https://api.yugo.finance/transaction?transactionId={transactionId}
Headers
| Header | Value |
|---|---|
x-api-key | Your API key |
Response
json
{
"uuid": "5d141fb0-dea0-4499-8361-0915807d1151",
"type": "MerchantOnRampTransfer",
"names": "John Doe",
"chainId": 137,
"address": "0xB8C043De299eC1C12840979F7Ea230A9b22dDE3B",
"currency": "EUR",
"cryptoCurrency": "USDC",
"paymentLink": "https://oba.revolut.com/ui/index.html?transactionId=3e5...",
"paymentStatus": "PROCESSING",
"bankDepositStatus": "SUCCESS",
"createdAt": "2025-04-17T10:12:34.567Z",
"lastUpdated": "2025-04-17T10:14:22.001Z"
}Status Reference
Payment Status
| Status | Description |
|---|---|
INTENT | Transaction created; authorization flow not yet started |
STARTED | Authorization with the bank has started |
FAILED_INTENT | Authorization failed or was rejected by the bank |
PROCESSING | Transaction is being processed |
COMPLETED | Funds settled and crypto transferred to merchant's Web3 address |
Bank Deposit Status
| Status | Description |
|---|---|
PENDING | Waiting for funds to be received |
SUCCESS | Funds successfully received in bank account |
FAILED | Bank deposit failed or timed out |
Webhooks
Bank Deposit Webhook
When Yugo receives funds (typically within 1 minute after bank authorization), a webhook is sent to your backend.
Webhook Requirements
| Requirement | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Expected Response | HTTP 200 |
| Retry Policy | Up to 5 retries with exponential backoff |
Webhook Payload
json
{
"eventType": "merchant_on_ramp_success",
"transactionId": "5d141fb0-dea0-4499-8361-0915807d1151",
"amount": 100.0,
"currency": "EUR",
"timestamp": "2025-04-17T10:14:22.001Z",
"webhookPayload": "internal-order-id-xyz"
}Required Response
Your endpoint must respond with HTTP 200:
json
{
"message": "merchant_on_ramp_success event processed successfully"
}Transaction Verification
After receiving a webhook, verify the transaction status:
GET https://api.yugo.finance/transaction?transactionId=5d141fb0-dea0-4499-8361-0915807d1151
Expected Response
json
{
"uuid": "5d141fb0-dea0-4499-8361-0915807d1151",
"bankDepositStatus": "SUCCESS",
"paymentStatus": "PROCESSING"
}Important: Only proceed with your business logic after confirming
bankDepositStatus: "SUCCESS".
Additional Configuration
Contact your Yugo integration team during onboarding to configure:
Custom Webhook Events
- Payment Status Updates - Notifications for all payment status changes
- Payout Confirmations - Notifications when crypto payout is completed
- Error Notifications - Alerts for failed transactions or processing errors
Enhanced Payment Information
- Exchange Rate Details - Real-time exchange rates applied to transactions
- Payout Transaction Hash - Blockchain transaction hash for crypto payouts
- Additional fields as needed