Developer Hub

Built by engineers, for engineers.

Typed SDKs. Sandbox credentials in one click. Idempotency, signed webhooks and predictable rate limits, all documented. No sales email required to start reading.

Start building API reference

API stats

Median latency: [~90ms]
Idempotent writes: 100%
Rate limit: 100 req/s
Event retention: 30 days

Quickstart

Three steps from npm install to a real pay-in.

Start in sandbox. Flip to production when you're ready.

Step 01
Install the SDK
Pick your language. We publish typed SDKs for Node, Python, PHP and Java. A Go SDK is in beta.
```
"color:#FFE66D">$ npm install @modena/node
```

Step 02

Authenticate

Keys start with sk_test_ for sandbox and sk_live_ for production. Never ship keys to clients — only to your server.

"color:#FFE66D">import Modena "color:#FFE66D">from "@modena/node";
"color:#FFE66D">const modena = "color:#FFE66D">new Modena(process.env.MODENA_KEY);

Step 03

Create your first pay-in

All write endpoints accept an Idempotency-Key header. Use it on every retry.

"color:#FFE66D">const payin = "color:#FFE66D">await modena.payins.create({
  amount: 12000,
  currency: "eur",
  payment_method: "sepa_credit",
  wallet: "wal_4f9c3a",
  reference: "Order #4281",
}, { idempotencyKey: crypto.randomUUID() });

SDKs

Typed clients, first-party.

No wrappers over wrappers. Each SDK is generated from the OpenAPI spec and reviewed by hand.

Node.js / TypeScript

@modena/node

Python

modena

PHP

modena/modena-php

Java / Kotlin

eu.modena:modena-java

Beta

github.com/modena/modena-go

Beta

.NET

Modena.Net

Planned

Sandbox

Test credentials, no call required.

A fully isolated sandbox, pre-seeded with EU test identities, SEPA accounts and card numbers.

Separate data plane
Zero chance of a sandbox transaction hitting a production account.
Realistic KYC flows
Deterministic test identities that approve, reject or escalate on demand.
Instant test settlement
Simulated SEPA clearing so you can build end-to-end without waiting.

Request sandbox access Browse endpoints

Sandbox request

"color:#FFE66D">$ curl https://api.sandbox.modenapay.com/v1/ping \
  "color:#FFE66D">-u sk_test_••••:

{ "status": "ok", "region": "eu">-central", "version": "v1.142" }

API reference

Designed to be read, not just ctrl-F'd.

A preview of the endpoint browser. The full reference lives in the docs.

API Reference — preview

Full docs →

POST/v1/payins

Create a pay-in (collect money from a buyer).

Request

"color:#FFE66D">$ curl https://api.modenapay.com/v1/payins \
  "color:#FFE66D">-u sk_test_••••: \
  "color:#FFE66D">-H "Idempotency">-Key: 2f8a-4c90" \
  "color:#FFE66D">-d amount=12000 \
  "color:#FFE66D">-d currency=eur \
  "color:#FFE66D">-d payment_method=sepa_credit \
  "color:#FFE66D">-d wallet=wal_4f9c3a \
  "color:#FFE66D">-d reference="Order #4281"

Response · 200

JSON

{
  "id": "pay_01HR1E8JXZW4SR2V",
  "object": "payin",
  "amount": 12000,
  "currency": "eur",
  "status": "pending",
  "payment_method": "sepa_credit",
  "wallet": "wal_4f9c3a",
  "reference": "Order #4281",
  "created": 1735120812
}

Platform primitives

Things we don't expect you to build yourself.

Webhooks

Delivery with exponential backoff, signed with HMAC SHA-256. Replay any event from the dashboard for up to 30 days.

modena.webhooks.verify(
  body,
  req.headers["Modena-Signature"],
  process.env.WEBHOOK_SECRET
);

Idempotency

Every write endpoint accepts an Idempotency-Key header. We cache the response for 24 hours — safe to retry on any network error.

POST /v1/payins
Idempotency-Key: 2f8a-4c90-b53d-0e92

Rate limits

Default 100 req/s per account, burst of 300. Published headers on every response. Higher limits available on request.

RateLimit-Limit: 100
RateLimit-Remaining: 92
RateLimit-Reset: 1735120812

Looking for architecture guides, versioning policy or migration notes? Read the full docs.

Build with us

Get sandbox keys in minutes.

Tell us what you're building and we'll provision a sandbox with seeded test data.

Talk to engineers Trust & compliance