API reference

GiveWP

The Orboni for GiveWP plugin adds “Crypto” to your donation forms, with no code. The donor presses Donate, picks a coin on Orboni’s payment page and pays from any wallet or exchange. The money goes to the wallets you set in the dashboard, and once the payment is final on the chain the donation is completed by itself and GiveWP emails its receipt.

It works with the visual form builder’s forms and with GiveWP’s option-based forms. It needs WordPress 6.5, GiveWP 3.0 and PHP 7.4 or later, and is tested on GiveWP 3.0, 3.22 and 4.19.

Set it up

  1. 1In WordPress, go to Plugins → Add New Plugin, search for “Orboni” and install Orboni for GiveWP, then activate it. GiveWP must be active.
  2. 2In the Orboni dashboard, set the wallets you want to be paid to under Wallets, then copy two secret keys under Developers → API keys: the test key (sk_test_…) and the live one (sk_live_…).
  3. 3In WordPress, open Donations → Settings → Payment Gateways → Orboni and paste them. Then tick “Orboni (crypto)” under Donations → Settings → Payment Gateways → Gateways, for the visual builder’s forms and for the option-based ones.
  4. 4Under Developers → Webhooks, add an endpoint at https://your-site.com/wp-json/orboni-givewp/v1/webhook (the plugin’s settings show your site’s own address) with every event, or at least the checkout.session.* ones — once in test mode and once live — and paste each signing secret into its field (whsec_…).
  5. 5With GiveWP’s test mode on, give a donation, and on its payment page, signed in to the dashboard, press Simulate payment: the donation turns Complete. Then switch test mode off to take real donations.

Test mode

GiveWP’s own test mode decides which key a donation is made with: the test key while it is on, the live key once it is off. A test donation takes no real money, and its payment page can simulate a payment. A donation is always read back with the key of its own mode, so switching test mode later never mixes them. While no key is saved for the mode GiveWP is in, Crypto is not offered on your forms, and the plugin’s settings say so.

How donations move

The plugin reads the payment back from Orboni before it changes a donation, and the donation follows the payment as it is now — whether the webhook, the donor’s return or a scheduled check comes first, twice or out of order.

PaymentOrboni saysThe donation
Paid in fullcomplete, paidComplete: GiveWP emails its receipt
On the chain, not final yetprocessingProcessing, until it is final
Part paidpartially_paidProcessing, with how much came; the payment page asks the donor for the rest
Held for your reviewheldProcessing, with the reason; accept it in the dashboard and the donation is completed
Left by the page’s back link, nothing sentopen, unpaidCancelled, and the donor is back on the form; the page is closed at Orboni
Ran out with nothing paidexpired, unpaidAbandoned, if it still waits for payment
Ran out part paidexpired, partially_paidProcessing, with what arrived: change the amount to it and complete the donation, or send the money back
Money that paid it left the chainpayment_reversedRevoked, until the dashboard shows it paid again
More came after it was paidextra_receivedA note with the total; the donation stays Complete

A completed donation is never taken back by anything but a reversal. Each change is written on the donation as a note: the coin, the network, the amount and the session. Without a webhook the donation still moves: the plugin reads the payment when the donor comes back from the payment page, ten minutes after the page opens, and again after it runs out. Money sent to a page the donor left is held for your review in the dashboard, never counted for the cancelled donation.

Good to know

  • Your site’s currency: US dollars, euros, pounds, yen or any other currency a checkout session takes (Currencies in the API reference). The payment page shows the donation in it, and Orboni turns it into dollars at the rate of the day (the European Central Bank’s, or the market’s for a currency the ECB does not publish); the donor pays that in the coin they pick. With a currency not on the list Crypto is not offered on your forms, and the settings page says so.
  • The least is worth $1.00. A smaller donation is turned down on the form with a word why, in dollars by the plugin and in another currency by Orboni when the donor presses Donate.
  • A donation that could not get a payment page — no key saved, Orboni not answering, below the minimum — is marked Failed with a note saying why, and the donor is asked to try again or choose another way to give.
  • One-time donations only: a coin payment is made by the donor each time, so GiveWP takes recurring donations with your other gateways.
  • A donation whose amount was changed by hand after its payment page opened waits in Processing with a note when the payment completes, for you to check.
  • Refunds: the money is in your wallet, so send it back from there, mark the donation Refunded in GiveWP and record the refund in the dashboard. The plugin does not refund through GiveWP.
  • Several sites can share one Orboni project: each adds its own endpoints and acts only on its own donations.
  • Turn on “Debug log” in the settings to see every request and webhook under Donations → Tools → Logs, source “orboni”. Errors are logged either way; keys and signing secrets never are.

What the plugin sends

Each donation makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the site, the donation and its amount, so a retry never makes a second one. Nothing is sent until a donor gives with Crypto.

amountinteger
The donation, in the currency’s smallest unit: cents, or whole yen.
currencystring
The donation’s currency, in lower case: usd, eur, jpy…
descriptionstring
The form’s title: “Winter Beds Appeal”, cut at 250 characters.
detailsstring
The donation’s number and your site’s name: “Donation #1042 to Harbour Light Shelter”.
client_reference_idstring
The GiveWP donation’s id.
metadataobject
give_donation_id, give_form_id, and give_site — a short hash of the site’s address, so two sites on one project never act on each other’s events.
customer_emailstring
The donor’s email, where Orboni sends the receipt when your project sends receipts.
localestring
The language WordPress is showing the donor.
success_url, cancel_urlstring
The plugin’s return addresses, signed by GiveWP: the first reads the payment back and shows GiveWP’s donation confirmation, the second closes an unpaid page and takes the donor back to the form.

The donor’s name, address and phone number are not sent. A completed donation keeps the session’s id as its transaction id, so a payment in the dashboard, an export or a webhook leads to its donation by client_reference_id, and the donation to its payment by the transaction id.

This page as Markdown, for a program or an AI assistant: /docs/givewp.md. Something missing or unclear? Write to us from the dashboard’s Help & Support.