Payment Links

Payment links let your business collect crypto or fiat payments through a hosted Rivo payment page.

Field mapping

Field	Meaning	How to choose it
`title`	Customer-facing title.	Required.
`description`	Customer-facing description.	Optional.
`amount`	Amount to collect.	Optional; omit for flexible-amount links.
`currency`	Fiat or crypto asset to collect.	Use a supported asset reference, for example `naira` or `usdt`.
`type`	Payment link rail.	Use `fiat` for bank-transfer style links or `crypto` for crypto links.
`network`	Crypto network.	Required for crypto links; use a network `reference` for the selected `currency`.
`expiresIn`	Link lifetime in hours.	Positive number.
`metadata`	Partner-defined reconciliation data.	Optional object. Store your own IDs such as `customerId`, `ticketId`, `eventId`, `liveTagId`, `vendorId`, or `partnerReference`.
`id`	Payment link ID.	Returned by create/list endpoints; use it to expire a link.
`code`	Public link code.	Returned by create/list endpoints; use it with `/public/payment-links/{code}`.

Allowed values

Field	Allowed values
`type`	`crypto`, `fiat`
`status`	`pending`, `completed`, `expired`, `failed`, `cancelled`

Endpoints

POST /business/v1/payment-links
GET  /business/v1/payment-links
POST /business/v1/payment-links/{id}/expire

Create a payment link

{
  "title": "Invoice 1001",
  "description": "Customer invoice",
  "amount": 25000,
  "currency": "naira",
  "type": "fiat",
  "expiresIn": 24,
  "metadata": {
    "partnerReference": "invoice-1001",
    "customerEmail": "customer@example.com",
    "customerPhone": "+2348012345678"
  }
}

For business API-key requests, include Idempotency-Key when creating or expiring payment links. The response includes the link code and payment details. Store the returned ID and code for support and reconciliation. Use metadata for your own business mapping. Rivo stores it and returns it with the payment link, but Rivo does not enforce partner-specific meaning for those fields. Example response:

{
  "status": "success",
  "message": "Payment link created successfully",
  "data": {
    "id": "payment_link_id",
    "code": "abc123",
    "title": "Invoice 1001",
    "amount": 25000,
    "currency": "naira",
    "type": "fiat",
    "status": "pending",
    "expiresAt": "2026-07-11T12:00:00.000Z",
    "metadata": {
      "partnerReference": "invoice-1001",
      "customerEmail": "customer@example.com",
      "customerPhone": "+2348012345678"
    }
  }
}

For crypto payment links, creationStatus may initially be pending while the provider generates the deposit address. Continue reading the payment link or use the public link endpoint until the address details are available.

Get Started

Core Concepts

Testing and Launch

Field mapping

Allowed values

Endpoints

Create a payment link

​Field mapping

​Allowed values

​Endpoints

​Create a payment link

Field mapping

Allowed values

Endpoints

Create a payment link