canonical: https://jentic.com/apis/pay.nl/pay-nl # Pay.nl Transaction Gateway API 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. ## For AI agents Manage Pay.nl payment orders including creation, capture, void, refund, and status tracking across the European payment gateway. ## Scope 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. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: 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. Example prompt: 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. Example prompt: 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 | 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 | ## Key resources - **Orders** — Payment orders with status, amount, description, and payment method associations - **Payments** — Individual payment records linked to orders with method and amount details - **Amount** — Currency-aware amount representation in cents with ISO 4217 currency codes - **Order Status** — Status codes and action states tracking payment lifecycle from pending through captured or refunded ## Why Jentic - **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 handling:** 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. - **Discovery method:** 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 - **Stripe API** — Stripe provides global payment processing with similar authorization and capture workflows but broader geographic coverage. - **Mollie API** — Mollie offers European payment processing with similar iDEAL and local payment method support to Pay.nl. - **Adyen API** — Adyen provides enterprise-grade global payment processing with more complex integration requirements than Pay.nl. ## FAQ ### 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.