Collect with Ruby - Dollr Developer Docs

Invoices vs orders: These guides walk through invoices (formal billing, line items, publish). The collect flow is the same for orders — use /v1/orders/* instead of /v1/invoices/* and set source_type: "ORDER" on the checkout session. See Orders and Parties & counterparties.Hosted checkout: To skip party, invoice, session, and execute steps entirely, see Hosted checkout.

End-to-end invoice collection with Ruby 3.x and the standard library (net/http, json). For other languages, see Quick Start.

API Reference: Obtain token · Collect

Prerequisites

Ruby 3.0+
gem install json (stdlib json is built in)
API credentials via environment variables — server-side only

Steps

Authenticate

require "net/http"
require "json"
require "uri"

BASE_URL = "https://api.heydollr.app"

def dollr_post(path, body, token = nil)
  uri = URI("#{BASE_URL}#{path}")
  req = Net::HTTP::Post.new(uri)
  req["Content-Type"] = "application/json"
  req["Authorization"] = "Bearer #{token}" if token
  req.body = body.to_json
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  JSON.parse(res.body)
end

token_res = dollr_post("/v1/jwt/client/obtain/token", {
  client_id:     ENV["DOLLR_CLIENT_ID"],
  client_secret: ENV["DOLLR_CLIENT_SECRET"],
})
token = token_res["access_token"]

Party, counterparty, invoice

party = dollr_post("/v1/parties/create", {
  fullname: "Amara Kamara", phone: "231771234567",
  email: "amara@example.com", country_code: "LR",
}, token)

cp = dollr_post("/v1/counterparties/create", {
  relationship_type: "CUSTOMER", party_id: party["id"],
}, token)

invoice = dollr_post("/v1/invoices/create", {
  counterparty_id: cp["id"], currency: "USD",
  note: "Consulting", fee_bearer: "PAYER", as_payment_link: true,
}, token)

Publish, session, execute

require "securerandom"

invoice_id = invoice["id"]
dollr_post("/v1/invoices/#{invoice_id}/items/add", {
  name: "Strategy Session", currency: "USD", qty: 1, amount: 250.0,
}, token)
# PUT publish — use Net::HTTP::Put

reference_id = SecureRandom.uuid
session = dollr_post("/v1/sessions/checkout", {
  source_id: invoice_id, source_type: "INVOICE",
}, token)

dollr_post("/v1/executions/collection", {
  session_id:         session["id"].to_s,
  payment_account_id: "YOUR_PAYMENT_ACCOUNT_ID",
  currency:           "USD",
  reference_id:       reference_id,
}, token)

Poll status

uri = URI("#{BASE_URL}/v1/status/collection/#{reference_id}")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{token}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
status = JSON.parse(res.body)

Try it yourself

Hosted checkout

Mobile money and card on a Dollr-hosted page — fastest path.

Orders

Same collect flow with source_type: ORDER and /v1/orders/*.

Direct checkout

One API call to create source — API-embedded flow.

​Prerequisites

​Steps

​Try it yourself

Hosted checkout

Orders

Direct checkout

​Related

Prerequisites

Steps

Try it yourself

Related