Onramps API

Create NGN-funded onramps over the private API and settle them to a Yara wallet, a crypto wallet, or a USD bank account.

PalmPay powers the funding leg through a fixed-amount, single-use virtual account. After the customer pays into that account, Yara routes the funds to the destination attached to the onramp.

Overview

An onramp has two stages:

Funding: Yara creates a single-use PalmPay bank account for the exact NGN amount required.
Settlement: Once the payment is received and verified, Yara settles the onramp to the selected destination.

You can supply the destination in one of four ways:

by recipient_id
by inline recipient object
by yara_tag
by omitting all destination selectors, which defaults to the caller's own Yara wallet

Only one explicit destination selector may be supplied in the same request.

Authentication

All onramp endpoints require your secret API key in the x-yara-api-key header.

x-yara-api-key: <secret-key>
Content-Type: application/json

Endpoints

POST /api/v1/onramps
GET /api/v1/onramps?id=<onramp_id>
GET /api/v1/onramps?reference=<reference>

Response Envelope

Successful responses use this envelope:

{
  "data": {},
  "message": "success"
}

Validation errors return:

{
  "error": "..."
}

Create an onramp

POST /api/v1/onramps

Request fields

Field	Type	Required	Notes
`amount`	number	Yes	Amount to fund in NGN
`reference`	string	No	Caller-supplied reference
`payment_remarks`	string	No	Optional free-form note
`recipient_id`	string	No	Existing saved recipient
`recipient`	object	No	Inline recipient object using the same shape as `POST /api/v1/recipients`
`yara_tag`	string	No	Direct YaraTag destination

Destination rules

Supply at most one of recipient_id, recipient, or yara_tag
If all three are omitted, the onramp defaults to the caller's own Yara wallet
Inline recipient objects may only use YARA_TAG, CRYPTO_WALLET, or USD_BANK_ACCOUNT

Request examples

Self-wallet onramp

If you omit all destination selectors, the onramp settles to the caller's own Yara wallet.

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 100000,
    "reference": "onramp-self-001",
    "payment_remarks": "Top up my Yara wallet"
  }'

Onramp by saved recipient ID

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 150000,
    "reference": "onramp-crypto-001",
    "recipient_id": "8d3dc7d0-8db7-4e84-93e0-0c4d04802da4",
    "payment_remarks": "NGN onramp to saved crypto wallet"
  }'

Onramp directly to a YaraTag

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 150000,
    "reference": "onramp-yaratag-001",
    "yara_tag": "$ayo",
    "payment_remarks": "NGN onramp to YaraTag"
  }'

Onramp with inline crypto recipient

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 150000,
    "reference": "onramp-crypto-inline-001",
    "payment_remarks": "NGN onramp to crypto wallet",
    "recipient": {
      "recipient_type": "CRYPTO_WALLET",
      "name": "Ada Base Wallet",
      "email": "[email protected]",
      "crypto_details": {
        "token": "USDC",
        "chain": "BASE",
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      }
    }
  }'

Onramp with inline USD bank recipient

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 250000,
    "reference": "onramp-usdbank-inline-001",
    "payment_remarks": "NGN onramp to USD bank",
    "recipient": {
      "recipient_type": "USD_BANK_ACCOUNT",
      "name": "Ada Cooper",
      "email": "[email protected]",
      "usd_bank_details": {
        "account_number": "123456789012",
        "routing_number": "021000021",
        "bank_name": "JPMorgan Chase Bank",
        "account_owner_name": "Ada Cooper",
        "street_line_1": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US",
        "checking_or_savings": "checking"
      }
    }
  }'

Onramp with inline YaraTag recipient

curl -X POST "https://api.yara.cash/api/v1/onramps" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 50000,
    "reference": "onramp-yaratag-inline-001",
    "payment_remarks": "NGN onramp to YaraTag recipient",
    "recipient": {
      "recipient_type": "YARA_TAG",
      "yara_tag": "$ayo"
    }
  }'

Response example

{
  "data": {
    "id": "460b5fc1-3b52-4aa2-a1b5-eb359bf20f7d",
    "reference": "test-mags-002",
    "status": "DEPOSIT_PENDING",
    "funding_status": "ACTIVE",
    "expected_ngn_amount": 3000,
    "quoted_usd_amount": 2.1135045057050292,
    "estimated_net_payout_amount": 2.1135045057050292,
    "estimated_net_payout_currency": "USD",
    "destination": {
      "type": "YARA_TAG",
      "recipient_id": "e7a3d8e8-b0f3-4ae2-8d8d-c8d4eaef8ad2",
      "name": "OLUWASEYI OLADELE",
      "yara_tag": "ayo"
    },
    "funding_account": {
      "provider": "palmpay",
      "account_number": "8776644943",
      "bank_name": "PalmPay",
      "bank_code": "100033",
      "beneficiary_name": "OLUWASEYI OLADELE",
      "narration": "Yara/OLUWASEYI OLADELE",
      "expected_amount": 3000,
      "currency": "NGN",
      "expires_at": "2026-07-09T03:59:59Z",
      "provider_reference": "24260709033042163487"
    },
    "created_at": "2026-07-09T03:29:59Z",
    "updated_at": "2026-07-09T03:29:59Z"
  },
  "message": "success"
}

Response notes

status describes the onramp lifecycle
funding_status describes the PalmPay funding leg
funding_account.account_number is the one-time account the payer must fund
funding_account.expires_at is the cutoff time for that funding account

Common values returned today include:

status: DEPOSIT_PENDING, DEPOSIT_RECIEVED, PAYOUT_SUCCESS, PAYOUT_FAILED, REVIEW_REQUIRED
funding_status: ACTIVE, PAID, FAILED, EXPIRED, REVIEW_REQUIRED

Get an onramp

You can fetch an onramp by ID or by reference.

By ID

curl -X GET "https://api.yara.cash/api/v1/onramps?id=460b5fc1-3b52-4aa2-a1b5-eb359bf20f7d" \
  -H "x-yara-api-key: <secret-key>" \
  -H "Content-Type: application/json"

By reference

curl -X GET "https://api.yara.cash/api/v1/onramps?reference=test-mags-002" \
  -H "x-yara-api-key: <secret-key>" \
  -H "Content-Type: application/json"

The response uses the same payload shape as POST /api/v1/onramps.

Webhooks

Onramp webhooks are sent to the webhook URL configured on the active API key for the account.

Yara emits these onramp-specific webhook events:

ONRAMP_CREATED
ONRAMP_FUNDING_RECEIVED
ONRAMP_COMPLETED
ONRAMP_FAILED

Onramp lifecycle notifications are emitted as ONRAMP_* events only. Legacy PAYOUT_SUCCESS is not part of the onramp webhook lifecycle.

Use data.eventId as your idempotency key. For onramp events, the ID format is:

<onramp_id>:<event_name>

See the webhook reference for full payload examples.

Recommended client flow

Option A: Save a recipient first

POST /api/v1/recipients
Store the returned recipient.id
POST /api/v1/onramps with recipient_id
Wait for ONRAMP_* webhooks or poll GET /api/v1/onramps

Option B: Create the recipient inline

POST /api/v1/onramps with recipient
Wait for ONRAMP_* webhooks or poll GET /api/v1/onramps

Option C: Send to a YaraTag directly

POST /api/v1/onramps with yara_tag
Wait for ONRAMP_* webhooks or poll GET /api/v1/onramps