Pay.nl Transaction Gateway API
Official vendor OpenAPI document · agent-readyPaymentsPayment Processingbasic10 EndpointsREST
For Agents
Manage Pay.nl payment orders including creation, capture, void, refund, and status tracking across the European payment gateway.
Use for: I need to create a payment order for a customer checkout, Capture a payment after order fulfillment, Check the status of a payment order, Issue a refund for a completed payment
Not supported: Does not host checkout pages, validate payment methods, or process actual fund transfers - use for order management, capture, refund, and status operations only. Payment processing happens on Pay.nl infrastructure.
Pay.nl is a European payment gateway that processes online payments through various methods including iDEAL, credit cards, and local payment options. The Transaction Gateway API provides comprehensive order management capabilities including creation, updates, capture, void, refund, and status tracking. Authentication uses basic auth with API tokens or Service IDs, and the API follows RESTful conventions with JSON payloads.
Install Jentic One Beta
Connect the Pay.nl Transaction Gateway API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Pay.nl Transaction Gateway API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpay.nl%2Fpay-nl" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpay.nl%2Fpay-nl" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Pay.nl Transaction Gateway API.
Create and manage payment orders with multiple payment methods
Capture full or partial order amounts with product-level granularity
Void and decline pending orders before capture
Process full and partial refunds with optional descriptions
Track order status and payment states in real-time
Configure test mode for development and staging environments
Add multiple payments to a single order
Update order amounts, descriptions, and reference fields
Manage expiration times and return/exchange URLs
Approve or decline orders for risk management
Use Cases
Patterns agents use Pay.nl Transaction Gateway API for, with concrete tasks.
★ E-commerce Checkout Integration
Integrate Pay.nl into an e-commerce checkout flow by creating orders with POST /orders when customers initiate payment. Include the cart amount, return URL for successful payments, and exchange URL for server-side webhooks. Once the customer completes payment through the redirect link, capture the full amount with PATCH /orders/{id}/capture or a partial amount with PATCH /orders/{id}/capture-amount. GET /orders/{id}/status provides real-time payment state for order confirmation pages.
POST /orders with amount, serviceId, returnUrl, and exchangeUrl to create the order. The response includes a redirect link for the customer. After payment completion notification via exchangeUrl, call PATCH /orders/{id}/capture to finalize.
Partial Refund Processing
Process full or partial refunds for customer returns and cancellations using the refund endpoints. PATCH /orders/{id}/refund issues a full refund, while PATCH /orders/{id}/refund-amount allows specifying the exact amount to return. PATCH /orders/{id}/refund-products enables product-level granularity by refunding specific line items and quantities. Each refund can include a description field for internal tracking and customer communication.
To refund specific items, call PATCH /orders/{id}/refund-products with an array of products containing id and quantity. For a flat amount refund, use PATCH /orders/{id}/refund-amount with the Amount object. Include description for audit trails.
Pre-Authorization and Capture Workflow
Implement a two-stage payment flow where authorization happens at order time but capture occurs only after fulfillment. Create the order with POST /orders including testMode: false for production. The order enters an authorized state. When goods ship or services complete, call PATCH /orders/{id}/capture-products to capture only the items being fulfilled, useful for partial shipments. Monitor status via GET /orders/{id}/status to ensure the capture succeeded before finalizing the order.
POST /orders creates the authorization. After fulfillment, call PATCH /orders/{id}/capture-products with the products array specifying which line items and quantities to capture. GET /orders/{id}/status confirms capture completion.
Fraud Prevention and Order Approval
Implement manual order review for high-risk transactions using the approve and decline endpoints. After order creation, orders flagged by internal fraud systems can remain in pending state. Use PATCH /orders/{id}/approve to allow legitimate orders to proceed or PATCH /orders/{id}/decline to cancel suspicious transactions. PATCH /orders/{id}/void provides an additional mechanism to cancel orders before capture. Combined with GET /orders/{id}/status, this enables human-in-the-loop fraud review workflows.
After risk analysis, call PATCH /orders/{id}/decline for orders that fail checks or PATCH /orders/{id}/approve for those that pass. Use PATCH /orders/{id}/void to cancel authorized but not-yet-captured orders.
AI Agent for Payment Operations
Let an AI agent handle routine payment operations for an e-commerce platform - creating orders at checkout, capturing payments post-fulfillment, processing refunds for returns, and checking order status for customer service inquiries. Through Jentic, the agent loads only the specific payment operations it needs and credentials are injected securely without appearing in prompts.
Use the Jentic search query 'create a payment order' to find POST /orders, load its schema, and execute with the checkout details including amount and return URLs.
Key Endpoints
10 endpoints — pay.
METHOD
PATH
DESCRIPTION
POST
/orders
Create a new payment order with amount, service ID, and URLs
PATCH
/orders/{id}/capture
Capture the full authorized amount for an order
PATCH
/orders/{id}/refund
Issue a full refund for a captured order
GET
/orders/{id}/status
Check the current status and action state of an order
PATCH
/orders/{id}/void
Void an authorized but not-yet-captured order
PATCH
/orders/{id}/capture-amount
Capture a specific partial amount from an authorized order
PATCH
/orders/{id}/refund-products
Refund specific products by ID and quantity
POST
/orders
Create a new payment order with amount, service ID, and URLs
PATCH
/orders/{id}/capture
Capture the full authorized amount for an order
PATCH
/orders/{id}/refund
Issue a full refund for a captured order
GET
/orders/{id}/status
Check the current status and action state of an order
PATCH
/orders/{id}/void
Void an authorized but not-yet-captured order
PATCH
/orders/{id}/capture-amount
Capture a specific partial amount from an authorized order
PATCH
/orders/{id}/refund-products
Refund specific products by ID and quantity
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring Pay.nl by hand means encoding its HTTP Basic auth from your token or Service ID, choosing the right connect host, and driving the order capture and refund lifecycle yourself. Through Jentic you install once, import the Pay.nl API from the API Directory, store the credential once, and your agent calls it.
Permission scoping
Pay.nl puts the order id in the URL path (/orders/{id}/status), so a rule can pin your agent to one order: it can read that order's status and nothing else. You choose the operations it may call, so capture, refund, and void are not included unless you add them.
Credential isolation
Your Pay.nl API token or Service ID is stored once, encrypted, by your own Jentic One instance and injected as HTTP Basic auth at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'create a payment order' or 'refund a payment', and Jentic returns the matching Pay.nl operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Stripe provides global payment processing with similar authorization and capture workflows but broader geographic coverage.
Choose Stripe for global reach and extensive payment methods; choose Pay.nl for European focus with strong iDEAL and local payment support.
FAQs
Specific to using Pay.nl Transaction Gateway API through Jentic.
What authentication does the Pay.nl API use?
The Pay.nl API uses HTTP Basic authentication with either an API token (AT-code) or Service ID (SL-code) as credentials. Through Jentic, credentials are stored encrypted and injected as the Authorization header at execution time so they never enter the agent's context.
Can I process partial refunds through the Pay.nl API?
Yes. Use PATCH /orders/{id}/refund-amount to refund a specific amount in cents, or PATCH /orders/{id}/refund-products to refund by product ID and quantity. Both support partial refunds while PATCH /orders/{id}/refund issues a full refund.
Does Pay.nl support test mode for development?
Yes. Include testMode: true in the POST /orders request body to create test orders that process through the Pay.nl sandbox environment without charging real payment methods.
How do I implement a two-stage payment flow with Pay.nl through Jentic?
Search Jentic for 'create payment order' to find POST /orders for authorization, then search 'capture payment after fulfillment' to find PATCH /orders/{id}/capture. Jentic injects credentials automatically and handles the authorization-then-capture workflow.
What payment methods does Pay.nl support?
Pay.nl supports iDEAL, credit cards, and various European local payment methods. The specific payment methods available depend on your Pay.nl merchant account configuration and are selected via paymentMethodId in the order creation request.
Can I void an order before it's captured?
Yes. Use PATCH /orders/{id}/void to cancel an authorized order before capture, or PATCH /orders/{id}/decline to reject an order through the approval workflow. Both prevent the payment from being captured.
Can I limit what my agent is allowed to do with the Pay.nl API?
Yes. Because you run Jentic One yourself, your own rules decide which Pay.nl operations and credentials the agent may use. Since the order id sits in the URL path, such as GET /orders/{id}/status, a rule can pin the agent to a single order and let it read only that order's status. Write operations like PATCH /orders/{id}/capture, PATCH /orders/{id}/refund, and PATCH /orders/{id}/void are excluded unless you explicitly add them.
GET STARTED