On-Ramp Payins (Fiat to Crypto)

Accept fiat payments from Payers and settle funds as crypto into a custodial Web3 wallet managed by Yugo.

For request/response schemas and field-level details, see the API Reference.

---

When to Use This Flow

Use On-Ramp Payins when you want to:

• Receive fiat payments and settle as crypto in a Yugo-managed wallet
• Let Payers pay via open banking, cards, Apple Pay, or Google Pay
• Offload checkout, compliance, and authorization to Yugo

---

Prerequisites

Before using this flow, you must be onboarded as a Merchant with Yugo and have a merchant account opened.

During onboarding, Yugo configures:

• Supported fiat currencies
• Supported crypto assets
• Blockchain networks
• A custodial Web3 wallet managed by Yugo
• Your API credentials for accessing the API

These settings are configured once during onboarding and are not provided dynamically in each API request.

---

Integration Flow

Step 1: Create a Payin Intent

Create a Payin Intent specifying the amount, Payer details, payment method, settlement method, and callback URLs.

API Reference: POST /payins View Create Payin API →

Open Banking

Minimal Payin Intent Request

{
  "amount": {
    "value": "100.00",
    "currency": "EUR"
  },
  "payer": {
    "email": "payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "DE"
  },
  "reference": "order_123",
  "return_url": "https://merchant.com/checkout/complete",
  "webhook_url": "https://merchant.com/api/webhooks/payins",
  "payment": {
    "method": "bank_account"
  },
  "settlement": {
    "method": "yugo_balance"
  }
}

Key fields:

• payment.method = bank_account — triggers the open banking authorization flow
• settlement.method = yugo_balance — funds are converted to crypto and delivered to the Merchant's custodial wallet

For payment-method-specific behavior, see Open Banking.

Card

Minimal Payin Intent Request

{
  "amount": {
    "value": "100.00",
    "currency": "EUR"
  },
  "payer": {
    "email": "payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "DE"
  },
  "reference": "order_123",
  "return_url": "https://merchant.com/checkout/complete",
  "webhook_url": "https://merchant.com/api/webhooks/payins",
  "payment": {
    "method": "card"
  },
  "settlement": {
    "method": "yugo_balance"
  }
}

Key fields:

• payment.method = card — triggers the card authorization flow
• settlement.method = yugo_balance — funds are converted to crypto and delivered to the Merchant's custodial wallet

For payment-method-specific behavior, see Cards.

Apple Pay

Minimal Payin Intent Request

{
  "amount": {
    "value": "100.00",
    "currency": "EUR"
  },
  "payer": {
    "email": "payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "DE"
  },
  "reference": "order_123",
  "return_url": "https://merchant.com/checkout/complete",
  "webhook_url": "https://merchant.com/api/webhooks/payins",
  "payment": {
    "method": "apple_pay"
  },
  "settlement": {
    "method": "yugo_balance"
  }
}

Key fields:

• payment.method = apple_pay — triggers the Apple Pay authorization flow
• settlement.method = yugo_balance — funds are converted to crypto and delivered to the Merchant's custodial wallet

For payment-method-specific behavior, see Apple Pay.

Google Pay

Minimal Payin Intent Request

{
  "amount": {
    "value": "100.00",
    "currency": "EUR"
  },
  "payer": {
    "email": "payer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "DE"
  },
  "reference": "order_123",
  "return_url": "https://merchant.com/checkout/complete",
  "webhook_url": "https://merchant.com/api/webhooks/payins",
  "payment": {
    "method": "google_pay"
  },
  "settlement": {
    "method": "yugo_balance"
  }
}

Key fields:

• payment.method = google_pay — triggers the Google Pay authorization flow
• settlement.method = yugo_balance — funds are converted to crypto and delivered to the Merchant's custodial wallet

For payment-method-specific behavior, see Google Pay.

---

Step 2: Redirect the Payer

The Payin response contains a redirect_url. Redirect the Payer to this URL to continue the payment.

At this point:

• Yugo hosts the checkout experience (in some cases this step is skipped)
• The Payer completes the authorization flow for their chosen payment method
• After completion, the Payer is redirected back to the Merchant's return_url

tip

The more payment details the Merchant supplies when creating the Payin Intent, the less friction for the Payer after redirect. In some cases, the Payer may be redirected directly back to the Merchant.

Open Banking

• The Payer selects their bank (or is redirected directly if pre-selected)
• The Payer authorizes the payment via their bank's authentication flow

For details, see Open Banking — Authorization Flow.

Card

• The Payer enters their card details on Yugo's hosted checkout
• The Payer completes 3D Secure authentication if required

For details, see Cards — Authorization Flow.

Apple Pay

• The Payer sees the Apple Pay button on Yugo's hosted checkout
• The Payer authorizes the payment via Apple Pay (Touch ID, Face ID, or passcode)

For details, see Apple Pay — Authorization Flow.

Google Pay

• The Payer sees the Google Pay button on Yugo's hosted checkout
• The Payer authorizes the payment via Google Pay

For details, see Google Pay — Authorization Flow.

---

Step 3: Track Payin Status

Option A: Webhooks

Yugo sends a webhook every time the Payin status changes.

When you receive a webhook, we recommend verifying the updated status via the API (Option B).

API Reference: View Webhook Reference →

Option B: Polling

You can retrieve the current Payin status at any time.

API Reference: GET /payins/{id} View Get Payin API →

Status Lifecycle

See the Payin Status Lifecycle for the full state diagram and status definitions per payment and settlement method combination.

Status lifecycle for this flow:

Open Banking

Status	Meaning
INTENT	Payin Intent created by Merchant
INITIATED	Authorization process initiated (redirect link generated)
AUTHORIZED	Payment authorized by Payer's bank
RECEIVED	Yugo received the fiat funds
SETTLED	Crypto transferred to Merchant's custodial wallet
COMPLETED	Transaction finalized.
FAILED	Authorization failed or rejected by bank
EXPIRED	Payin session expired

Card

Status	Meaning
INTENT	Payin Intent created by Merchant
INITIATED	Authorization process initiated (redirect link generated)
AUTHORIZED	Payment authorized by card issuer
RECEIVED	Yugo received the fiat funds
SETTLED	Crypto transferred to Merchant's custodial wallet
COMPLETED	Dispute window closed. Transaction finalized.
DISPUTED	Payer raised a dispute. Yugo debited transaction funds.
FAILED	Authorization failed or rejected
EXPIRED	Payin session expired

warning

Card payments are subject to chargebacks. The dispute window is up to 120 days. See Cards for details.

Apple Pay

Status	Meaning
INTENT	Payin Intent created by Merchant
INITIATED	Authorization process initiated (redirect link generated)
AUTHORIZED	Payment authorized by card issuer
RECEIVED	Yugo received the fiat funds
SETTLED	Crypto transferred to Merchant's custodial wallet
COMPLETED	Dispute window closed. Transaction finalized.
DISPUTED	Payer raised a dispute. Yugo debited transaction funds.
FAILED	Authorization failed or rejected
EXPIRED	Payin session expired

warning

Apple Pay payments are processed via card networks and are subject to chargebacks. The dispute window is up to 120 days. See Apple Pay for details.

Google Pay

Status	Meaning
INTENT	Payin Intent created by Merchant
INITIATED	Authorization process initiated (redirect link generated)
AUTHORIZED	Payment authorized by card issuer
RECEIVED	Yugo received the fiat funds
SETTLED	Crypto transferred to Merchant's custodial wallet
COMPLETED	Dispute window closed. Transaction finalized.
DISPUTED	Payer raised a dispute. Yugo debited transaction funds.
FAILED	Authorization failed or rejected
EXPIRED	Payin session expired

warning

Google Pay payments are processed via card networks and are subject to chargebacks. The dispute window is up to 120 days. See Google Pay for details.

For the full state diagram, see Status Lifecycle.

---

Settlement

Open Banking

• Bank authorization is real-time
• Fiat transfer and conversion are asynchronous
• Crypto is sent to the Merchant's custodial wallet after fiat Settlement completes

Card

• Card authorization is real-time
• Fiat transfer and conversion are asynchronous
• Funds are typically received by Yugo within 3 business days
• Crypto is sent to the Merchant's custodial wallet after fiat funds are received, usually on the 4th day
• 90% of the crypto amount is released initially; the remaining 10% is released after 180 days
• The dispute window is up to 120 days

Apple Pay

• Apple Pay authorization is real-time
• Fiat transfer and conversion are asynchronous
• Funds are typically received by Yugo within 3 business days
• Crypto is sent to the Merchant's custodial wallet after fiat funds are received, usually on the 4th day
• 90% of the crypto amount is released initially; the remaining 10% is released after 180 days
• The dispute window is up to 120 days

Google Pay

• Google Pay authorization is real-time
• Fiat transfer and conversion are asynchronous
• Funds are typically received by Yugo within 3 business days
• Crypto is sent to the Merchant's custodial wallet after fiat funds are received, usually on the 4th day
• 90% of the crypto amount is released initially; the remaining 10% is released after 180 days
• The dispute window is up to 120 days

For full settlement details, see Yugo Balance Settlement.

---

Managing On-Ramp Funds

After Settlement, crypto funds are available in the Merchant Portal, where you can:

• View wallet balances and transaction history
• Manage received funds and Payouts
• Configure API keys and users