API reference

Create iDEAL payments from your own backend — a custom store, WooCommerce, or anything else that can make an HTTP request.

Getting started

  1. Create an OranPay account and connect your Mollie account.
  2. Generate an API key from API keys — pick test mode to build your integration first.
  3. Call the endpoints below with your key in the Authorization header.
  4. Once you're ready to go live, generate a live key. Live payments require your account to be approved by OranPay first — test payments don't.

Authentication

Every request needs your API key as a bearer token. Test keys (sk_test_…) and live keys (sk_live_…) are completely isolated — a test key can only see and act on payments it created, never live ones, and vice versa.

Authorization: Bearer sk_live_your_key_here

Endpoints

POST/api/payments/create

Creates an iDEAL payment and returns a checkout URL to redirect your customer to.

Body

{
  "amountCents": 1999,
  "description": "Order #1042",
  "redirectUrl": "https://yourstore.com/checkout/return",
  "customerEmail": "customer@example.com"  // optional
}

Response — 200

{
  "paymentId": "6f2c...-uuid",
  "checkoutUrl": "https://www.mollie.com/checkout/...",
  "status": "open",
  "mode": "live"
}

Redirect the customer to checkoutUrl. Amounts are in cents — 1999 means €19.99.

GET/api/payments/{id}

Looks up a payment by the paymentId returned from /create. Use this to confirm status after your customer returns from checkout, or as a fallback if your webhook is unreachable.

Response — 200

{
  "paymentId": "6f2c...-uuid",
  "status": "paid",
  "amountCents": 1999,
  "applicationFeeCents": 80,
  "currency": "EUR",
  "description": "Order #1042",
  "mode": "live",
  "createdAt": "2026-08-22T10:00:00.000Z"
}

status is one of: open, pending, paid, failed, expired, canceled, refunded.

POST/api/payments/{id}/refund

Refunds a paid payment, in full or in part.

Body (optional)

{
  "amountCents": 500  // omit for a full refund
}

Response — 200

{
  "refundId": "re_...",
  "paymentId": "6f2c...-uuid",
  "amountCents": 500,
  "status": "pending"
}

A full refund updates the payment's status to refunded once Mollie confirms it (via your webhook, usually within seconds). Partial refunds don't change status — it stays paid.

Webhooks

Set a webhook URL on the API keys page and OranPay will POST to it whenever a payment's status changes:

{
  "type": "payment.status_changed",
  "paymentId": "6f2c...-uuid",
  "status": "paid",
  "amountCents": 1999,
  "currency": "EUR",
  "description": "Order #1042",
  "mode": "live"
}

Known limitation: webhook requests aren't signed yet, so don't trust the payload blindly — call GET /api/payments/{id} to confirm status before, e.g., shipping an order. Signature verification is on the roadmap.

Code samples

cURL

curl -X POST https://your-oranpay-domain.com/api/payments/create \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1999,
    "description": "Order #1042",
    "redirectUrl": "https://yourstore.com/checkout/return"
  }'

Node.js

const res = await fetch("https://your-oranpay-domain.com/api/payments/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORANPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amountCents: 1999,
    description: "Order #1042",
    redirectUrl: "https://yourstore.com/checkout/return",
  }),
});

const { checkoutUrl } = await res.json();
// redirect the customer to checkoutUrl

WooCommerce

Skip the manual integration — install the official plugin from your API keys page. It adds OranPay as a checkout payment method, handles the redirect back from Mollie, and keeps order status in sync automatically (both via the return URL and your webhook).

  1. Download the plugin ZIP from the API keys page.
  2. Upload it under Plugins → Add New → Upload Plugin in WordPress.
  3. Configure it under WooCommerce → Settings → Payments → OranPay (iDEAL) with your API key.

PHP (custom backend, or your own WooCommerce gateway)

$response = wp_remote_post('https://your-oranpay-domain.com/api/payments/create', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('ORANPAY_API_KEY'),
        'Content-Type'  => 'application/json',
    ],
    'body' => wp_json_encode([
        'amountCents'  => (int) round($order->get_total() * 100),
        'description'  => 'Order #' . $order->get_id(),
        'redirectUrl'  => $order->get_checkout_order_received_url(),
        'customerEmail'=> $order->get_billing_email(),
    ]),
]);

$body = json_decode(wp_remote_retrieve_body($response), true);
// redirect to $body['checkoutUrl']

Questions? Contact support.