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

​
Field mapping

FieldMeaningHow to choose it
titleCustomer-facing title.Required.
descriptionCustomer-facing description.Optional.
amountAmount to collect.Optional; omit for flexible-amount links.
currencyFiat or crypto asset to collect.Use a supported asset reference, for example naira or usdt.
typePayment link rail.Use fiat for bank-transfer style links or crypto for crypto links.
networkCrypto network.Required for crypto links; use a network reference for the selected currency.
expiresInLink lifetime in hours.Positive number.
metadataPartner-defined reconciliation data.Optional object. Store your own IDs such as customerId, ticketId, eventId, liveTagId, vendorId, or partnerReference.
idPayment link ID.Returned by create/list endpoints; use it to expire a link.
codePublic link code.Returned by create/list endpoints; use it with /public/payment-links/{code}.

​
Allowed values

FieldAllowed values
typecrypto, fiat
statuspending, completed, expired, failed, cancelled

​
Endpoints

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

{
  "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.