Skip to content

Split Payments

Create and track temporary NGN virtual accounts for split payments. Yara returns a funding account immediately, and once funded, Yara credits the developer fee share to the caller wallet and pays the recipient bank account in NGN.

Create Split Payment Virtual Account

Create a temporary NGN virtual account for a split payment.

POST /api/v1/split-payments/virtual-accounts

curl -X POST "https://api.yara.cash/api/v1/split-payments/virtual-accounts" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "amount": 100000,
    "currency": "NGN",
    "recipient": {
      "account_number": "0123456789",
      "bank_code": "058"
    },
    "developer_fee_percentage": 2.5,
    "reference": "split-test-001",
    "payment_remarks": "Split payment test"
  }'

Request body:

  • amount — recipient payout amount in NGN
  • currency — must be NGN
  • recipient.account_number — recipient bank account number
  • recipient.bank_code — recipient bank code
  • developer_fee_percentage — percentage credited to the API caller after successful funding
  • reference — optional client reference for idempotent create requests
  • payment_remarks — optional remarks stored with the split payment

Response

{
  "data": {
    "id": "split-payment-uuid",
    "reference": "split-va-abc123",
    "virtual_account": {
      "bank_name": "Partner Bank",
      "bank_code": "000",
      "bank_account_number": "1234567890",
      "bank_beneficiary_name": "Yara customer"
    },
    "recipient": {
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "Resolved Recipient Name"
    },
    "pricing": {
      "base_amount": 100000,
      "provider_fee": 600,
      "developer_fee_percentage": 2.5,
      "developer_fee_amount": 2500,
      "total_expected_amount": 103100
    },
    "recipient_payout_amount": 100000,
    "status": "ACTIVE",
    "expires_at": "2026-05-20T18:00:00Z"
  },
  "message": "success"
}

Notes:

  • reference in the response is the system funding reference used for status lookup
  • pricing.total_expected_amount is the exact amount that must be paid into the virtual account
  • recipient_payout_amount is the amount that will be sent to the recipient bank account

Get Split Payment Virtual Account

Fetch a split payment virtual account by reference.

GET /api/v1/split-payments/virtual-accounts?reference=<reference>

curl -X GET "https://api.yara.cash/api/v1/split-payments/virtual-accounts?reference=split-va-abc123" \
  -H "x-yara-api-key: <secret-key>" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "id": "split-payment-uuid",
    "reference": "split-va-abc123",
    "virtual_account": {
      "bank_name": "Partner Bank",
      "bank_code": "000",
      "bank_account_number": "1234567890",
      "bank_beneficiary_name": "Yara customer"
    },
    "recipient": {
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "Resolved Recipient Name"
    },
    "pricing": {
      "base_amount": 100000,
      "provider_fee": 600,
      "developer_fee_percentage": 2.5,
      "developer_fee_amount": 2500,
      "total_expected_amount": 103100
    },
    "recipient_payout_amount": 100000,
    "status": "ACTIVE",
    "expires_at": "2026-05-20T18:00:00Z"
  },
  "message": "success"
}

Authentication

All split-payment endpoints require the x-yara-api-key header with a valid secret key.

Common errors

400 Bad Request

Returned when:

  • currency is not NGN
  • amount is less than or equal to zero
  • developer_fee_percentage is less than 0 or greater than or equal to 100
  • recipient account details are invalid or cannot be resolved
  • reference is missing on the GET request

Example:

{
  "error": "currency must be NGN"
}

401 Unauthorized

Returned when the x-yara-api-key header is missing or invalid.

Example:

Unauthorized