Skip to main content
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

1

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"]
2

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)
3

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)
Register a payment account before execute. Store reference_id before the HTTP call.
4

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.
Last modified on May 22, 2026