# Update the Merchant Configuration `POST /v2/merchant-config` Core API v2, Merchant Configuration. Update the configuration of the authenticated merchant. **Authentication:** Send `Authorization: Bearer `. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer ` ## Request body Content type `application/json`, required. Type: object (UpdateMerchantConfigRequestDTO). - `defaultPaymentMethodOptions` (object (CreatePaymentMethodOptionsDTO)): Default payment method options. - `card` (object (CreateCardPaymentMethodOptionsDTO)): Card-specific processing options. - `mode` (string): The processing mode for card payments. One of `cascade`, `direct`, `route`. Example: `cascade`. - `gatewayProfile` (string): Specific gateway profile to use, bypassing cascade routing. Required for `direct` processing and ignored otherwise. - `cascade` (string): The cascade to use for gateway routing. Required for `cascade` processing and ignored otherwise. - `captureMethod` (string): Capture method for card payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number): Delay in days before capture occurs. Only applicable when captureMethod is 'automaticDelayed'. Maximum 5. Example: `7`. - `recurringCaptureMethod` (string): Capture method to use for recurring card payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number): Delay in days before capture occurs for recurring card charges. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Maximum 5. Example: `7`. - `route` (string): The route that chooses the gateway for each card payment. Required for `route` processing and ignored otherwise. The route must be active and have an active version. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`. - `paypal` (object (CreatePaypalPaymentMethodOptionsDTO)): PayPal-specific processing options. - `gatewayProfile` (string): Gateway profile ID for PayPal processing. - `captureMethod` (string): Capture method for PayPal payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number): Delay in days before capture occurs for PayPal payments. Only applicable when captureMethod is 'automaticDelayed'. Maximum 15. Example: `7`. - `recurringCaptureMethod` (string): Capture method to use for recurring PayPal payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number): Delay in days before capture occurs for recurring PayPal payments. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Maximum 15. Example: `7`. - `applePay` (object (CreateApplePayPaymentMethodOptionsDTO)): Apple Pay-specific processing options. - `gatewayProfile` (string): Gateway profile ID for Apple Pay processing. - `captureMethod` (string): Capture method for Apple Pay payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number): Delay in days before capture occurs for Apple Pay payments. Only applicable when captureMethod is 'automaticDelayed'. Maximum 5. Example: `7`. - `recurringCaptureMethod` (string): Capture method to use for recurring Apple Pay payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number): Delay in days before capture occurs for recurring Apple Pay payments. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Maximum 5. Example: `7`. - `captureMethod` (string): Default capture method to use for this payment. If provided on a payment method level, it will override this value. One of `automatic`, `automaticDelayed`, `manual`. - `captureDelay` (number): Default capture delay to use for this payment. If provided on a payment method level, it will override this value. Maximum 5. - `recurringCaptureMethod` (string): Capture method to use for recurring charges on this payment. If provided on a payment method level, it will override this value. One of `automatic`, `automaticDelayed`, `manual`. - `recurringCaptureDelay` (number): Capture delay to use for recurring charges on this payment. If provided on a payment method level, it will override this value. Maximum 5. - `displayCurrency` (string): Display currency to be used for the merchant. If not provided, will be set to USD. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`. - `timezone` (string): Timezone for the merchant, in IANA format. If not provided, will be set to UTC. Example: `Europe/Paris`. - `enableRecurringPaymentBundling` (boolean): Whether to bundle recurring payments for the same customer into a single charge. Example: `false`. - `preferCaptureAtNight` (boolean): Whether delayed captures should be scheduled at night in the shopper's local time, derived from the UTC offset their browser reported at authorization. Captures fall back to the standard schedule when no offset was reported. Example: `false`. - `blacklistCustomerOnChargeback` (boolean): Whether recording a chargeback always blacklists the customer. While this is `true`, the `blacklistCustomer` field of a chargeback request is ignored. If not provided, will be set to true. Example: `true`. - `lineItemDescriptionSource` (string): Which name a line item description defaults to when none is supplied on the request: the name of the price it references, or the name of the product behind that price. If not provided, will be set to price. One of `price`, `product`. Example: `price`. - `relatedSubscriptionWindowMinutes` (integer): How many minutes apart two of the same customer's subscriptions may be created and still be presented as related in the dashboard. 0 disables the time window; subscriptions sharing a setup payment are grouped regardless. If not provided, will be set to 0. Minimum 0. Maximum 1440. Example: `0`. ## Responses ### `200` OK Type: object (MerchantConfigDTO). - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the merchant configuration. - `defaultPaymentMethodOptions` (object, required): Default payment method options for the merchant. - `captureMethod` (string, required): Capture method for the payment. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number, required, nullable): Delay in days before capture occurs. Only applicable when captureMethod is 'automaticDelayed'. Example: `7`. - `recurringCaptureMethod` (string, required, nullable): Capture method to use for recurring charges. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number, required, nullable): Delay in days before capture occurs for recurring charges. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Example: `7`. - `card` (object, nullable): Card-specific processing options. - `mode` (string, required): The processing mode for card payments. One of `cascade`, `direct`, `route`. Example: `cascade`. - `gatewayProfile` (object, required, nullable): Specific gateway profile to use, bypassing cascade routing. Only present if `mode` is `direct` - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): ID of the Gateway Profile. Example: `gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL`. - `active` (boolean, required): Whether the gateway profile is active and available for processing. Example: `true`. - `title` (string, required): Title of the Gateway Profile. Example: `Profile #1`. - `integration` (string, required): Associated Gateway Integration. One of `stripe`, `adyen`, `checkout`, `paypal`. Example: `stripe`. - `environment` (string, required, nullable): The environment the gateway profile operates in. One of `live`, `test`. Example: `test`. - `supportedPaymentMethods` (array of string, required): Supported payment methods for the Gateway Profile. Each item: One of `card`, `paypal`, `applePay`. - `cascade` (object, required, nullable): The cascade to use for gateway routing. Only present if `mode` is `cascade` - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the cascade. - `name` (string, required): Example: `My Cascade`. - `description` (string, required, nullable): Example: `Simple cascade`. - `active` (boolean, required): Whether the cascade is active and available for routing. Example: `true`. - `algorithm` (string, required): The algorithm used for gateway selection. Available options: roundRobin, weightedRoundRobin, priorityQueue. One of `roundRobin`, `weightedRoundRobin`, `priorityQueue`. Example: `weightedRoundRobin`. - `captureMethod` (string, required, nullable): Capture method for card payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number, required, nullable): Delay in days before capture occurs. Only applicable when captureMethod is 'automaticDelayed'. Example: `7`. - `recurringCaptureMethod` (string, required, nullable): Capture method to use for recurring card payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number, required, nullable): Delay in days before capture occurs for recurring charges. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Example: `7`. - `route` (object, required, nullable): The route that chooses the gateway for each card payment when `mode` is `route`. `null` when no route is set. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the route. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`. - `name` (string, required): Example: `Card routing`. - `description` (string, required, nullable): Example: `Sends US-issued cards to a domestic gateway`. - `active` (boolean, required): Whether the route is active. A route is available for routing only while it is active and has an active version. Example: `true`. - `paypal` (object, nullable): PayPal-specific processing options. - `mode` (string, required): Processing mode for PayPal payments, will always be `direct` One of `cascade`, `direct`. Example: `direct`. - `gatewayProfile` (object, required): Gateway profile ID for PayPal processing. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): ID of the Gateway Profile. Example: `gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL`. - `active` (boolean, required): Whether the gateway profile is active and available for processing. Example: `true`. - `title` (string, required): Title of the Gateway Profile. Example: `Profile #1`. - `integration` (string, required): Associated Gateway Integration. One of `stripe`, `adyen`, `checkout`, `paypal`. Example: `stripe`. - `environment` (string, required, nullable): The environment the gateway profile operates in. One of `live`, `test`. Example: `test`. - `supportedPaymentMethods` (array of string, required): Supported payment methods for the Gateway Profile. Each item: One of `card`, `paypal`, `applePay`. - `captureMethod` (string, required, nullable): Capture method for PayPal payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number, required, nullable): Delay in days before capture occurs for PayPal payments. Only applicable when captureMethod is 'automaticDelayed'. Example: `7`. - `recurringCaptureMethod` (string, required, nullable): Capture method to use for recurring PayPal payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number, required, nullable): Delay in days before capture occurs for recurring PayPal payments. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Example: `7`. - `applePay` (object, nullable): Apple Pay-specific processing options. - `mode` (string, required): Processing mode for Apple Pay payments, will always be `direct` One of `cascade`, `direct`. Example: `direct`. - `gatewayProfile` (object, required): Gateway profile ID for Apple Pay processing. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): ID of the Gateway Profile. Example: `gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL`. - `active` (boolean, required): Whether the gateway profile is active and available for processing. Example: `true`. - `title` (string, required): Title of the Gateway Profile. Example: `Profile #1`. - `integration` (string, required): Associated Gateway Integration. One of `stripe`, `adyen`, `checkout`, `paypal`. Example: `stripe`. - `environment` (string, required, nullable): The environment the gateway profile operates in. One of `live`, `test`. Example: `test`. - `supportedPaymentMethods` (array of string, required): Supported payment methods for the Gateway Profile. Each item: One of `card`, `paypal`, `applePay`. - `captureMethod` (string, required, nullable): Capture method for Apple Pay payments. 'automatic' captures immediately, 'automaticDelayed' captures after a configurable delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `captureDelay` (number, required, nullable): Delay in days before capture occurs for Apple Pay payments. Only applicable when captureMethod is 'automaticDelayed'. Example: `7`. - `recurringCaptureMethod` (string, required, nullable): Capture method to use for recurring Apple Pay payments. 'automatic' captures immediately, 'automaticDelayed' captures after a delay, 'manual' requires a separate capture request. One of `automatic`, `automaticDelayed`, `manual`. Example: `automatic`. - `recurringCaptureDelay` (number, required, nullable): Delay in days before capture occurs for recurring Apple Pay payments. Only applicable when recurringCaptureMethod is 'automaticDelayed'. Example: `7`. - `displayCurrency` (string, required): Display currency for the merchant. Used in statistics. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`. - `timezone` (string, required): Timezone for the merchant, in IANA format. Example: `UTC`. - `enableRecurringPaymentBundling` (boolean, required): Whether to bundle recurring payments for the same customer into a single charge. Example: `false`. - `preferCaptureAtNight` (boolean, required): Whether delayed captures should be scheduled at night in the shopper's local time, derived from the UTC offset their browser reported at authorization. Captures fall back to the standard schedule when no offset was reported. Example: `false`. - `blacklistCustomerOnChargeback` (boolean, required): Whether recording a chargeback always blacklists the customer. While this is `true`, the `blacklistCustomer` field of a chargeback request is ignored. Example: `true`. - `lineItemDescriptionSource` (string, required): Which name a line item description defaults to when none is supplied on the request: the name of the price it references, or the name of the product behind that price. One of `price`, `product`. Example: `price`. - `relatedSubscriptionWindowMinutes` (number, required): How many minutes apart two of the same customer's subscriptions may be created and still be presented as related in the dashboard. 0 disables the time window; subscriptions sharing a setup payment are grouped regardless. Example: `0`. ### `202` The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway. Type: object (ProvisioningInProgress). - `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`. - `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`. ### Errors - `400`: The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it. - `401`: No API key was supplied, or the key is not valid. `type` is `authentication_error`. - `403`: The API key is valid but lacks the permission this operation requires. `type` is `permission_error`. - `409`: `type` is `conflict_error`. The supplied `X-Idempotency-Key` was already used with a different request body (`code` is `idempotency_conflict`, and retrying will not help), or the resource is being modified by another in-flight request (`code` is `resource_locked`, and retrying with backoff will). - `429`: Too many requests. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry. - `500`: The request could not be completed because of an unexpected error. `type` is `api_error`. - `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff. - `504`: The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly. Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md). --- Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/merchant-config-controller-set