--- updatedAt: 2026-05-15T14:07:05.000Z agentTools: projectIndex: https://developer.pay.nl/llms.txt --- # Service:UpdatePaymentMethod Update the settings of a payment method on a specific service. The payment method needs to be enabled and you need to have access to that service. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "PAY. Global Management System API's", "description": "The restful API for interacting with the Pay.", "termsOfService": "https://www.pay.nl/en/terms-conditions", "contact": { "name": "Pay.", "url": "https://developer.pay.nl", "email": "support@pay.nl" }, "license": { "name": "Proprietary", "url": "https://www.pay.nl/en/terms-conditions" }, "version": "2" }, "servers": [ { "url": "https://gms.pay.nl", "description": "Pay.nl" } ], "paths": { "/v2/services/{serviceId}/paymentmethods/{paymentMethodId}": { "patch": { "operationId": "service_payment_method_update_patch", "tags": [ "Services" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service.Output.PaymentMethodSettings" }, "examples": { "success": { "$ref": "#/components/examples/PaymentMethodSettingsOkResponse" } } }, "application/vnd.validation+json": { "schema": { "$ref": "#/components/schemas/Service.Output.PaymentMethodSettings" }, "examples": { "success": { "$ref": "#/components/examples/PaymentMethodSettingsOkResponse" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "410": { "$ref": "#/components/responses/Gone" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Unprocessable entity", "content": { "application/vnd.validation+json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "summary": "Service:UpdatePaymentMethod", "description": "Update the settings of a payment method on a specific service. The payment method needs to be enabled and you need to have access to that service.", "parameters": [ { "name": "serviceId", "in": "path", "description": "Provide the SL-code of the service that you want to add payment methods for", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "SL-1234-4321" }, { "name": "paymentMethodId", "in": "path", "description": "The ID of the payment method you want to enable", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false, "example": "10" } ], "requestBody": { "description": "Update the settings of a payment method on a specific service. The payment method needs to be enabled and you need to have access to that service.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Service.Input.PaymentMethod.IdealPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.PayByBankPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.SofortPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.In3PaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.PayPalPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.DirectDebitPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.PayByPhonePaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.GivaCardPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.BillinkPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.KlarnaPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.AmazonPayPaymentMethod" }, { "$ref": "#/components/schemas/Service.Input.PaymentMethod.WeroPaymentMethod" } ] }, "examples": { "ideal": { "$ref": "#/components/examples/idealSettings" }, "payByBank": { "$ref": "#/components/examples/payByBankSettings" }, "sofort": { "$ref": "#/components/examples/sofortSettings" }, "in3": { "$ref": "#/components/examples/in3Settings" }, "paypal": { "$ref": "#/components/examples/payPalSettings" }, "directDebit": { "$ref": "#/components/examples/directDebitSettings" }, "payByPhone": { "$ref": "#/components/examples/payByPhoneSettings" }, "givacard": { "$ref": "#/components/examples/givacardSettings" }, "billink": { "$ref": "#/components/examples/billinkSettings" }, "klarna": { "$ref": "#/components/examples/klarnaSettings" }, "amazonPay": { "$ref": "#/components/examples/amazonPaySettings" }, "wero": { "$ref": "#/components/examples/weroSettings" } } } }, "required": false }, "deprecated": false }, "parameters": [ { "name": "Accept-Language", "in": "header", "description": "Locales for the following languages are accepted, all others are treated with \"en_GB\" by default.", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "en_GB", "de_DE", "es_ES", "fr_BE", "fr_FR", "it_IT", "nl_BE", "nl_NL", "nl", "de", "en", "fr", "es", "it" ] }, "style": "simple", "explode": false, "examples": { "default_locale": { "summary": "Query for results in en_GB.", "value": "en_GB" } } } ] } }, "components": { "schemas": { "Service.Output.PaymentMethodSettings": { "type": "object", "description": "Settings for a payment method within a service. Used as the response for the service payment method settings endpoint.", "deprecated": false, "properties": { "settings": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/ValueOutput" }, "defaultValue": { "$ref": "#/components/schemas/ValueOutput" } } }, "items": { "$ref": "#/components/schemas/ValueOutput" } } }, "title": "Service Payment Method Settings" }, "ValueOutput": { "type": "object", "description": "A generic value containing a default value and a current value.", "deprecated": false, "properties": { "defaultValue": {}, "value": {} }, "title": "Value" }, "Service.Input.PaymentMethod.DirectDebitPaymentMethod": { "type": "object", "description": "Input for configuring the Direct Debit payment method on a service.", "deprecated": false, "properties": { "webUrl": { "format": "uri", "externalDocs": { "url": "https://schema.org/url" }, "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Direct Debit Payment Method Input" }, "Service.Input.PaymentMethod.PayByPhonePaymentMethod": { "type": "object", "description": "Input for configuring the Pay By Phone payment method on a service.", "deprecated": false, "properties": { "limit1d": { "minimum": 0, "type": [ "integer", "null" ] }, "limit1w": { "minimum": 0, "type": [ "integer", "null" ] }, "limit1m": { "minimum": 0, "type": [ "integer", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Pay By Phone Payment Method Input" }, "Service.Input.PaymentMethod.IdealPaymentMethod": { "type": "object", "description": "Input for configuring the iDEAL payment method on a service.", "deprecated": false, "properties": { "idealFailoverType": { "enum": [ 0, 1, 2, 3 ], "description": "The ideal fail over type to use when the ideal payment method is not available. This setting determines how the payment should be handled when the ideal payment method is not available.", "type": [ "integer", "null" ] }, "idealWeroRSMEnabled": { "type": [ "integer", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service iDEAL Payment Method Input" }, "Service.Input.PaymentMethod.PayByBankPaymentMethod": { "type": "object", "description": "Input for configuring the Pay By Bank payment method on a service.", "deprecated": false, "properties": { "creditor": { "type": [ "boolean", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Pay By Bank Payment Method Input" }, "Service.Input.PaymentMethod.SofortPaymentMethod": { "type": "object", "description": "Input for configuring the Sofort payment method on a service.", "deprecated": false, "properties": { "payoutConfirmation": { "enum": [ 0, 1 ], "description": "When you would like to receive the payment confirmation for the Sofort payment method. 0 = Confirmed with Sofort, 1 = Amount received by Pay. Sofort is not a guaranteed payment method, so the payment can still be canceled after the confirmation.", "example": 1, "type": [ "integer", "null" ] }, "maxPayoutAmount": { "description": "The maximum amount that can be paid out using the Sofort payment method.", "example": 100000, "type": [ "integer", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Sofort Payment Method Input" }, "Service.Input.PaymentMethod.KlarnaPaymentMethod": { "type": "object", "description": "Input for configuring the Klarna payment method on a service.", "deprecated": false, "properties": { "capture": { "enum": [ -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "The capture setting for the Klarna payment method. This setting determines when the payment is captured where -1 means manual captures only, 0 means direct capture, and the other values indicate after how many days the payment should be captured.", "type": [ "integer", "null" ] }, "dataLevel": { "enum": [ 0, 1, 2, 3 ], "description": "Send data to klarna about historic payments in the EMD attachment. This is used to determine the risk of the transaction. The higher the value, the more data is sent.", "type": [ "integer", "null" ] }, "voidPending": { "description": "Klarna may check orders manually. This process slows the transaction workflow by at least 4 hours. Set this setting to true to automatically cancel these transactions. The customer is then sent back to the checkout to select another payment method.", "example": true, "type": [ "boolean", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Klarna Payment Method Input" }, "Service.Input.PaymentMethod.In3PaymentMethod": { "type": "object", "description": "Input for configuring the in3 payment method on a service.", "deprecated": false, "properties": { "in3Premium": { "type": [ "boolean", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service in3 Payment Method Input" }, "Service.Input.PaymentMethod.BillinkPaymentMethod": { "type": "object", "description": "Input for configuring the Billink payment method on a service.", "deprecated": false, "properties": { "capture": { "enum": [ -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90 ], "type": [ "integer", "null" ] }, "trustScoreType": { "minimum": 0, "maximum": 2, "type": [ "integer", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Billink Payment Method Input" }, "Service.Input.PaymentMethod.PayPalPaymentMethod": { "type": "object", "description": "Input for configuring the PayPal payment method on a service.", "deprecated": false, "properties": { "merchantId": { "type": [ "string", "null" ] }, "shippingRequired": { "type": [ "boolean", "null" ] }, "protectionEligibility": { "type": [ "boolean", "null" ] }, "showOrderLines": { "type": [ "boolean", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service PayPal Payment Method Input" }, "Service.Input.PaymentMethod.AmazonPayPaymentMethod": { "type": "object", "description": "Input for configuring the Amazon Pay payment method on a service.", "deprecated": false, "properties": { "capture": { "enum": [ -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "The capture setting for the Amazon Pay payment method. \n This setting determines when the payment is captured where -1 means manual captures only, 0 means direct capture, \n and the other values indicate after how many days the payment should be captured.", "type": [ "integer", "null" ] }, "sandbox": { "description": "Whether the Amazon Pay payment method should be used in sandbox mode.", "type": [ "boolean", "null" ] }, "merchantId": { "type": [ "string", "null" ] }, "clientId": { "type": [ "string", "null" ] }, "clientSecret": { "type": [ "string", "null" ] }, "accessKeyId": { "type": [ "string", "null" ] }, "secretAccessKey": { "type": [ "string", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Amazon Pay Payment Method Input" }, "Service.Input.PaymentMethod.WeroPaymentMethod": { "type": "object", "description": "Input for configuring the wero payment method on a service.", "deprecated": false, "properties": { "weroTransactionFlow": { "type": [ "string", "null" ], "enum": [ "DIRECT", "AUTHORISATION", null ] }, "weroAutoCapture": { "type": [ "integer", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service Wero Payment Method Input" }, "Service.Input.PaymentMethod.GivaCardPaymentMethod": { "type": "object", "description": "Input for configuring the GivaCard payment method on a service.", "deprecated": false, "properties": { "username": { "type": [ "string", "null" ] }, "cardName": { "type": [ "string", "null" ] }, "brandName": { "type": [ "string", "null" ] }, "paymentProfileId": { "readOnly": true } }, "title": "Service GivaCard Payment Method Input" }, "ErrorOutput": { "type": "object", "description": "Standard error response body returned when an API request fails.", "deprecated": false, "properties": { "type": { "default": "https://developer.pay.nl/docs/error-codes", "example": "https://developer.pay.nl/docs/error-codes", "type": "string", "description": "URI identifying the error type documentation." }, "code": { "type": "string", "description": "PAY error code identifying the error.", "example": "PAY-1404", "pattern": "^PAY-\\d{1,4}$" }, "title": { "type": "string", "description": "Short, human-readable summary of the error.", "example": "Resource not found" }, "detail": { "type": "string", "description": "Detailed explanation of the error.", "example": "The requested resource is not found" }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/ViolationOutput" }, "description": "Field-level validation violations, when applicable.", "example": [ { "propertyPath": "name", "message": "This value should not be blank." } ] }, "trace": { "type": "array", "items": { "type": "string" }, "description": "Stack trace entries (only included in non-production environments).", "example": [] } } }, "ViolationOutput": { "type": "object", "description": "A single field-level validation violation within an error response.", "deprecated": false, "properties": { "propertyPath": { "type": [ "string", "null" ], "description": "JSON pointer or property path to the invalid field, or null for a general error.", "example": "name" }, "message": { "type": "string", "description": "Human-readable description of the validation failure.", "example": "This value should not be blank." }, "code": { "type": [ "string", "null" ], "description": "PAY error code for this violation.", "example": "PAY-1422", "pattern": "^PAY-\\d{1,4}$" } } } }, "responses": { "BadRequest": { "description": "Bad request, see response body for more information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "BadRequest": { "summary": "Bad Request", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1400", "title": "Bad request", "detail": "The given input is malformed", "violations": [ { "propertyPath": null, "message": "Bad request", "code": "PAY-1400" } ] } } } } } }, "Unauthorized": { "description": "Unauthorized. Supplied credentials are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "Unauthorized": { "summary": "Supplier credentials are invalid", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1401", "title": "Authentication is needed to access this resource", "detail": "", "violations": [ { "propertyPath": null, "message": "Authentication is needed to access this resource", "code": "PAY-1401" } ] } } } } } }, "Forbidden": { "description": "Forbidden. Supplied credentials have no rights", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "Forbidden": { "summary": "Supplier credentials have no rights", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1403", "title": "Access denied", "detail": "", "violations": [ { "propertyPath": null, "message": "Access denied", "code": "PAY-1403" } ] } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "NotFound": { "summary": "The requested resource is not found", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1404", "title": "The requested resource is not found", "detail": "", "violations": [ { "propertyPath": null, "message": "The requested resource is not found", "code": "PAY-1404" } ] } } } } } }, "MethodNotAllowed": { "description": "Used HTTP method is not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "MethodNotAllowed": { "summary": "The used HTTP method is not allowed", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1405", "title": "The request method is not supported by the target resource", "detail": "", "violations": [ { "propertyPath": null, "message": "The request method is not supported by the target resource", "code": "PAY-1405" } ] } } } } } }, "NotAcceptable": { "description": "Not acceptable. The supplied content type in the accept parameter in the header is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "NotAcceptable": { "summary": "The supplied content type in the accept parameter in the header is not supported", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1406", "title": "There is no content that is acceptable by this server", "detail": "", "violations": [ { "propertyPath": null, "message": "There is no content that is acceptable by this server", "code": "PAY-1406" } ] } } } } } }, "Gone": { "description": "Indicates that this resource is no longer available for use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "Gone": { "summary": "The requested resource is no longer available", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1410", "title": "The requested resource is no longer available", "detail": "", "violations": [ { "propertyPath": null, "message": "The requested resource is no longer available", "code": "PAY-1410" } ] } } } } } }, "UnsupportedMediaType": { "description": "Unsupported media. The supplied content type in the content-type parameter in the header is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "UnsupportedMediaType": { "summary": "The supplied content type in the content-type parameter in the header is not supported", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1415", "title": "The server does not support the requested media type", "detail": "", "violations": [ { "propertyPath": null, "message": "The server does not support the requested media type", "code": "PAY-1415" } ] } } } } } }, "TooManyRequests": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "TooManyRequests": { "summary": "Rate limit reached.", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1429", "title": "Too many requests", "detail": "Rate limit reached, try again in 15 minutes.", "violations": [ { "propertyPath": null, "message": "Too many requests", "code": "PAY-1429" } ] } } } } } }, "InternalServerError": { "description": "An internal error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "InternalServerError": { "summary": "An internal error occurred.", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1500", "title": "An internal error has occurred", "detail": "Failed to process request due to X", "violations": [ { "propertyPath": null, "message": "An internal error has occurred", "code": "PAY-1500" } ] } } } } } }, "ServiceUnavailable": { "description": "The server is currently unable to handle your request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" }, "examples": { "ServiceUnavailable": { "summary": "The server is currently unable to handle your request.", "value": { "type": "https://developer.pay.nl/docs/error-codes", "code": "PAY-1503", "title": "The server is unable to handle your request, try again later.", "detail": "The server is currently unable to handle your request, try again in 15 minuntes.", "violations": [ { "propertyPath": null, "message": "The server is unable to handle your request, try again later.", "code": "PAY-1503" } ] } } } } } } }, "examples": { "directDebitSettings": { "summary": "Enable Direct Debit with a specific configuration", "description": "Enable Direct Debit with a specific configuration", "value": { "webUrl": "https://example.com", "description": "Preset for DirectDebit" } }, "payByPhoneSettings": { "summary": "Enable Pay by Phone with a specific configuration", "description": "Enable Pay by Phone with a specific configuration", "value": { "limit1d": 1200, "limit1w": 2400, "limit1m": 4800 } }, "idealSettings": { "summary": "Enable iDEAL with a specific configuration", "description": "Enable iDEAL with a specific configuration", "value": { "idealFailoverType": 2, "idealWeroRSMEnabled": 1 } }, "payByBankSettings": { "summary": "Enable PayByBank with a specific configuration", "description": "Enable PayByBank with a specific configuration", "value": { "creditor": false } }, "sofortSettings": { "summary": "Enable Sofort with a specific configuration", "description": "Enable Sofort with a specific configuration", "value": { "payoutConfirmation": 1, "maxPayoutAmount": 100000 } }, "klarnaSettings": { "summary": "Enable Klarna with a specific configuration", "description": "Enable Klarna with a specific configuration", "value": { "capture": 0, "dataLevel": 1, "voidPending": true } }, "in3Settings": { "summary": "Enable IN3 with a specific configuration", "description": "Enable IN3 with a specific configuration", "value": { "in3Premium": false } }, "billinkSettings": { "summary": "Enable Billink with a specific configuration", "description": "Enable Billink with a specific configuration", "value": { "capture": 0, "trustScoreType": 1 } }, "payPalSettings": { "summary": "Enable PayPal with a specific configuration", "description": "Enable PayPal with a specific configuration", "value": { "merchantId": "1234567890", "shippingRequired": true, "protectionEligibility": true, "showOrderLines": true } }, "amazonPaySettings": { "summary": "Enable Amazon Pay with a specific configuration", "description": "Enable Amazon Pay with a specific configuration", "value": { "capture": 1, "sandbox": false, "merchantId": "123456", "clientId": "123456", "clientSecret": "123456", "accessKeyId": "123456", "secretAccessKey": "123456" } }, "weroSettings": { "summary": "Enable wero with a specific configuration", "description": "Enable wero with a specific configuration", "value": { "weroTransactionFlow": "DIRECT", "weroAutoCapture": 2 } }, "givacardSettings": { "summary": "Enable GivaCard with a specific configuration", "description": "Enable GivaCard with a specific configuration", "value": { "username": "username", "cardName": "GivaCard", "brandName": "GivaCard" } }, "PaymentMethodSettingsOkResponse": { "summary": "Settings for payment method", "description": "Settings for payment method", "value": { "settings": { "idealFailoverType": { "defaultValue": 0, "value": 1 } } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "description": "HTTP Basic authentication using your API token as the username and an empty password.", "scheme": "basic" }, "BearerAuth": { "type": "http", "description": "Example: Bearer 12345xx6xxx1x2x123456789123xx123x12345x4", "scheme": "bearer" } } }, "security": [ { "BasicAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Services", "description": "Services" } ] } ```