canonical: https://jentic.com/apis/paynl.com/paynl # Pay.nl Transaction Gateway API Pay.nl Transaction Gateway API enables merchants to create and manage payment orders across multiple European payment methods. The API handles the full payment lifecycle from order creation through capture, void, and refund operations. Merchants can update order amounts before payment, approve or decline orders manually, retry failed transactions, and track order status in real time. The gateway supports flexible payment workflows including partial captures by amount or product line item. ## For AI agents Create and manage Pay.nl payment orders, process captures, voids, and refunds, handle multi-step payment approval flows, and track transaction status across European payment methods. ## Scope Does not handle recurring subscriptions, invoicing, or complex multi-merchant marketplace splits - use for single-merchant payment order processing with standard capture/void/refund workflows only. ## Capabilities - Create payment orders with service ID, amount, return URL, and optional payment method selection - Update order details including amount and description before payment is completed - Retrieve order status with full payment history and state information - Approve or decline pending orders for manual fraud review workflows - Capture full order amount or specific amounts with partial capture support - Capture specific product line items for split fulfillment scenarios - Void authorized orders before capture to release held funds - Abort orders in progress to cancel the transaction flow - Retry failed orders to give buyers a second payment attempt - Add additional payments to existing orders for split payment flows - Manage order lifecycle from creation through final settlement with detailed status tracking ## Use cases ### European E-Commerce Checkout Online merchants in the Netherlands, Belgium, and Germany integrate Pay.nl to accept local payment methods like iDEAL, Bancontact, and SEPA. The merchant creates an order with POST /orders including the cart total and shopper return URL, then redirects to the payment page. After the buyer completes payment, the merchant captures the order or voids it if the order is cancelled. The gateway supports both immediate capture and authorize-then-capture flows. Example prompt: Create a Pay.nl order for €89.99 with iDEAL as the payment method and redirect the customer to complete payment ### Delayed Capture for Physical Goods Merchants selling physical products authorize payment at checkout but delay capture until items ship. After creating the order, they call PATCH `/orders/{id}/approve` to pass fraud checks, then PATCH `/orders/{id}/capture` when the warehouse confirms shipment. If the order is cancelled before shipping, they call PATCH `/orders/{id}/void` to release the authorization without charging the buyer. Example prompt: Authorize a payment for €150, hold the funds, and capture them only after the warehouse confirms shipment - or void if the item goes out of stock ### Partial Capture for Split Fulfillment When orders contain multiple items that ship separately, merchants use partial capture to charge for each fulfilled batch. After creating the order for the full amount, they call PATCH `/orders/{id}/capture-products` with the specific product IDs that shipped, or PATCH `/orders/{id}/capture-amount` with the dollar amount. Unshipped items remain authorized and can be captured or voided later. Example prompt: Capture €45 from a €120 order when the first two items ship, then capture the remaining €75 when the backordered item arrives ### AI Agent Payment Operations Through Jentic, AI agents can manage Pay.nl transactions - creating orders, checking status, capturing payments, and processing refunds - without holding the merchant's API credentials directly. Jentic isolates the basic auth token per call and returns structured responses that agents can reason over, enabling automated payment workflows for European commerce platforms. Example prompt: Search Jentic for 'create pay.nl order', load the schema for POST /orders, and execute it for a €59 test transaction with iDEAL ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/orders` | Create a new payment order | | GET | `/orders/{id}/status` | Check order status with payment details | | PATCH | `/orders/{id}` | Update order amount or description | | PATCH | `/orders/{id}/capture` | Capture full order amount | | PATCH | `/orders/{id}/capture-amount` | Capture specific amount | | PATCH | `/orders/{id}/void` | Void an authorized order | ## Key resources - **Orders** — Create, update, and query payment orders - **Order Status** — Track payment state and transaction history - **Captures** — Full, partial, and product-level payment captures - **Voids and Aborts** — Cancel authorized payments and in-progress transactions - **Approvals** — Manual order approval for fraud review workflows - **Payments** — Add and track individual payment attempts on orders ## Why Jentic - **Setup:** Wiring Pay.nl by hand means learning its HTTP basic auth with your API token and Service ID, and coding the order lifecycle of capture, capture-amount, and void requests yourself. Through Jentic you install once, import Pay.nl from the API Directory, store the token 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 reading the status of one order. You choose the operations it may call, so capturing, voiding, or amending an order is not included unless you add them. - **Credential handling:** Your Pay.nl API token and Service ID are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a European payment order' or 'capture an order', and Jentic returns the matching Pay.nl operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Mollie API** — Another European payment gateway with similar regional coverage and method support. - **Stripe API** — Global payments platform with European method support via Payment Methods API. - **Adyen API** — Enterprise payment platform with European acquiring and local method routing. - **Shopify Admin API** — Storefront platform that can integrate Pay.nl as a payment provider. ## FAQ ### What authentication does the Pay.nl API use? Pay.nl uses HTTP Basic authentication with an API token (AT-code) or Service ID (SL-code) as credentials, encoded into the Authorization header. Through Jentic, the basic auth credential is stored encrypted in the vault and injected at execution time. ### Can I do partial captures with the Pay.nl API? Yes. After creating an order, use PATCH `/orders/{id}/capture-amount` to capture a specific amount, or PATCH `/orders/{id}/capture-products` to capture only the line items that have shipped. The remaining authorized amount stays on hold for later capture or void. ### What payment methods does Pay.nl support? Pay.nl supports major European payment methods including iDEAL (Netherlands), Bancontact (Belgium), SEPA Direct Debit, credit cards, and other local options. The payment method can be specified when creating the order or selected by the buyer on the hosted payment page. ### How do I void a payment before capture? Call PATCH `/orders/{id}/void` to release an authorized payment without charging the buyer. This is typically used when an order is cancelled before fulfillment or when a fraud review flags the transaction. ### What are the rate limits for the Pay.nl API? Pay.nl does not publish hard rate limits in the public spec. For production workloads, expect to handle a few requests per second per merchant. Back off on HTTP 429 responses and use queue-based patterns for high-volume checkout flows. ### How do I create a payment order through Jentic? Search Jentic for 'create pay.nl order', load the schema for POST /orders, and execute the call with the service ID, amount, and return URL. Jentic returns the order ID and redirect link so your app can send the customer to the payment page. ### 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 the agent may call, so you can grant read-only access to GET `/orders/{id}/status` while withholding capture, void, and amend operations. Since Pay.nl puts the order id in the URL path, a rule can pin the agent to reading the status of a single order. Capturing, capture-amount, and void requests are excluded unless you explicitly add them.