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

Webhook notification

When a split payment is fully funded and processed, Yara sends the SPLIT_PAYMENT_COMPLETED webhook event to your configured webhook URL.

• The webhook includes the split payment ID, reference, pricing breakdown, payout destination, and final status
• totalExpectedAmount is the exact amount that must be funded before this event is emitted
• developerFee is the amount credited to the API caller, while netPayoutAmount is sent to the recipient bank account

See the webhook reference for the full payload example.

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