--- title: "Payments - Update Metadata" method: POST path: "/payments/{payment_id}/update_metadata" tags: ["Payments"] --- # Payments - Update Metadata `POST /payments/{payment_id}/update_metadata` ## Path parameters - `payment_id` string, required ## Request body - PaymentsUpdateMetadataRequest - `metadata` object, required — Metadata is useful for storing additional, unstructured information on an object. - `feature_metadata` FeatureMetadata — additional data that might be required by hyperswitch - `redirect_response` RedirectResponse - `param` string, nullable - `json_payload` object, nullable - `search_tags` string[], nullable — Additional tags to be used for global search - `apple_pay_recurring_details` ApplePayRecurringDetails - `payment_description` string, required — A description of the recurring payment that Apple Pay displays to the user in the payment sheet - `regular_billing` ApplePayRegularBillingDetails, required - `label` string, required — The label that Apple Pay displays to the user in the payment sheet with the recurring details - `recurring_payment_start_date` string, date-time, nullable — The date of the first payment - `recurring_payment_end_date` string, date-time, nullable — The date of the final payment - `recurring_payment_interval_unit` 'year' | 'month' | 'day' | 'hour' | 'minute' - `recurring_payment_interval_count` integer, nullable — The number of interval units that make up the total payment interval - `billing_agreement` string, nullable — A localized billing agreement that the payment sheet displays to the user before the user authorizes the payment - `management_url` string, required — A URL to a web page where the user can update or delete the payment method for the recurring payment - `pix_additional_details` union - object - `immediate` ImmediateExpirationTime, required - `time` integer, required — Expiration time in seconds - `pix_key` union - object - … - object - … - object - … - object - … - object - … - object - `scheduled` ScheduledExpirationTime, required - `date` string, required — Expiration time in terms of date, format: YYYY-MM-DD - `validity_after_expiration` integer, nullable — Days after expiration date for which the QR code remains valid - `pix_key` union - object - … - object - … - object - … - object - … - object - … - `boleto_additional_details` BoletoAdditionalDetails - `due_date` string, nullable — Due Date for the Boleto - `document_kind` 'commercial_invoice' | 'service_invoice' | 'promissory_note' | 'rural_promissory_note' | 'receipt' | 'insurance_policy' | 'credit_card_invoice' | 'proposal' | 'deposit_or_funding' | 'cheque' | 'direct_promissory_note' | 'other' - `payment_type` 'fixed_amount' | 'flexible_amount' | 'installment' - `covenant_code` string, nullable - `pix_key` union - object - `type` 'cpf', required - `value` string, required - object - `type` 'cnpj', required - `value` string, required - object - `type` 'email', required - `value` string, required - object - `type` 'phone', required - `value` string, required - object - `type` 'evp_token', required - `value` string, required - `discount_rules` SantanderPaymentDiscountRules — Defines the type of discount applied to a payment, such as whether it's a fixed date discount, a daily calendar discount, or a daily business discount. - `discount_type` 'standard' | 'fixed_date' | 'daily_calendar' | 'daily_business' — Defines the type of discount applied to a payment, such as whether it's a fixed date discount, a daily calendar discount, or a daily business discount. - `tiers` DiscountTier[], required — A generic vector of discount tiers - `amount` string, nullable — The discount value (e.g., "5.50"). - `end_date` string, nullable — The ISO-8601 date until which this discount is valid - `penalties` PenaltyRules — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `fixed_penalty` PenaltyDetail — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `value` string, nullable — The numeric value (as a string to preserve decimal precision) - `grace_period_days` integer, nullable — Grace period: Days after due date before this applies - `interest` InterestDetail — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `interest_percentage` string, nullable — Percentage of Juros (Interest). Pattern: ^[0-9]{1,3}\.[0-9]{2}$ - `iof_percentage` string, nullable — Percentage of IOF (Financial Operations Tax). Pattern: \d{3}$\.\d{5} Only provided if the agreement is "Cobra IOF na Barra ou Cadastro" - `collection_actions` CollectionActions — Represents the legal or administrative actions that may be taken for non-payment, such as protest rules and automatic write-off timelines. - `legal_protest` ProtestRules - `protest_type` 'disabled' | 'calendar_days' | 'business_days' | 'contract_default', required — Defines the type of protest for non-payment, such as whether the count is based on calendar days, business days, or if the protest logic is determined by a pre-signed contract with the bank. - `days_after_due_date` integer, required — Number of days after the due date to initiate the protest - `auto_write_off_days` integer, nullable — Days after which the bill is automatically cancelled/written off - `payment_constraints` union — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - object - `type` 'fixed_amount', required - object - `type` 'flexible_amount', required - `details` FlexibleAmountDetails, required — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - `min_value` string, nullable — Minimum value allowed (e.g., "10.00") - `max_value` string, nullable — Maximum value allowed (e.g., "5000.00") - `value_type` 'percentage' | 'flat_amount' — Defines how the payment amount is calculated for penalties or discounts, either as a percentage or as a flat amount. - object - `type` 'installment', required - `details` InstallmentDetails, required — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - `max_partial_payments` integer, nullable — Maximum number of partial payments allowed (Up to 99 for Santander). - `value_type` 'percentage' | 'flat_amount' — Defines how the payment amount is calculated for penalties or discounts, either as a percentage or as a flat amount. - `beneficiary` BeneficiaryDetails — Represents the end-recipient of a payout or fund transfer. - `name` string, nullable — The full legal name of the individual or entity receiving the funds. - `document_number` string, nullable — The customer's unique identification number (e.g., Tax ID, SSN, Passport Number). Used by processors to verify the identity of the recipient and prevent fraud. Length of the document number depends upon the document_type. For CPF/CNPJ it is typically 11/14 digits long. - `document_type` 'cpf' | 'cnpj' | 'psn' | 'other' — Represents the type of identification document used for validation. - `pix_automatico_additional_details` union — Represents the specific data for Santander Pix Automatico (recurring PIX payments) Split into CIT (Customer Initiated Transaction) and MIT (Merchant Initiated Transaction) variants - object — Data for PixAutomaticoPush Payment Method Type CIT (Customer Initiated Transaction) - used during mandate setup - `time` integer, required — Time in seconds until which the push notification is valid - `retry_policy` boolean, nullable — Enable retry policy for failed payments (maps to PERMITE_3R_7D if true) - `mandate_details` SantanderMandateDetails - `fixed_recurring_amount` integer, nullable — Fixed amount for each recurring charge in minor units (e.g., cents). If not provided, the mandate will allow variable amounts. - `min_recurring_amount` integer, nullable — Minimum amount for each recurring charge in minor units (e.g., cents). If not provided, there will be no minimum limit on the amount. - `start_date` string, nullable — Start date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid immediately. - `end_date` string, nullable — End date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid indefinitely. - `periodicity` 'weekly' | 'monthly' | 'quarterly' | 'semiannually' | 'annually' - `type` 'pix_automatico_push', required - object — Data for PixAutomaticoQr Payment Method Type CIT (Customer Initiated Transaction) - used during mandate setup + non 0$ mandate setup - `retry_policy` boolean, nullable — Enable retry policy for failed payments (maps to PERMITE_3R_7D if true) - `mandate_details` SantanderMandateDetails - `fixed_recurring_amount` integer, nullable — Fixed amount for each recurring charge in minor units (e.g., cents). If not provided, the mandate will allow variable amounts. - `min_recurring_amount` integer, nullable — Minimum amount for each recurring charge in minor units (e.g., cents). If not provided, there will be no minimum limit on the amount. - `start_date` string, nullable — Start date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid immediately. - `end_date` string, nullable — End date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid indefinitely. - `periodicity` 'weekly' | 'monthly' | 'quarterly' | 'semiannually' | 'annually' - `type` 'pix_automatico_qr', required - object — Data for Santander Pix Automatico MIT (Merchant Initiated Transaction) - used during recurring charge creation - `receiver_details` SantanderPixAutomaticoReceiverDetails — Represents the receiver details for Santander Pix Automatico recurring charges - `branch_code` string, nullable — Branch code (agencia) of the receiver's bank account - `account_number` string, nullable — Account number (conta) of the receiver - `account_type` 'current' | 'savings' | 'payment' — Account type for Santander Pix Automatico recurring charges - `mandate_execution_date` string, nullable — Execution date for the mandate charge (maps to data_de_vencimento). Format: YYYY-MM-DD. If not provided, defaults to current date + 1 day. - `auto_adjust_date` boolean, nullable — Whether to automatically adjust the due date to the next business day if it falls on a non-business day. Maps to ajuste_dia_util in Santander API. Defaults to true if not provided. - `type` 'pix_automatico_mit', required - `finix_additional_details` FinixAdditionalDetails - `fraud_session_id` string, nullable — The fraud session ID used for Finix fraud detection ## Response `200` Metadata updated successfully - PaymentsUpdateMetadataResponse - `payment_id` string, required — The identifier for the payment - `metadata` object, nullable — Metadata is useful for storing additional, unstructured information on an object. - `status` 'succeeded' | 'failed' | 'cancelled' | 'cancelled_post_capture' | 'processing' | 'requires_customer_action' | 'requires_merchant_action' | 'requires_payment_method' | 'requires_confirmation' | 'requires_capture' | 'partially_captured' | 'partially_captured_and_capturable' | 'partially_authorized_and_requires_capture' | 'partially_captured_and_processing' | 'conflicted' | 'expired' | 'review' — Represents the overall status of a payment intent. The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture). - `feature_metadata` FeatureMetadata — additional data that might be required by hyperswitch - `redirect_response` RedirectResponse - `param` string, nullable - `json_payload` object, nullable - `search_tags` string[], nullable — Additional tags to be used for global search - `apple_pay_recurring_details` ApplePayRecurringDetails - `payment_description` string, required — A description of the recurring payment that Apple Pay displays to the user in the payment sheet - `regular_billing` ApplePayRegularBillingDetails, required - `label` string, required — The label that Apple Pay displays to the user in the payment sheet with the recurring details - `recurring_payment_start_date` string, date-time, nullable — The date of the first payment - `recurring_payment_end_date` string, date-time, nullable — The date of the final payment - `recurring_payment_interval_unit` 'year' | 'month' | 'day' | 'hour' | 'minute' - `recurring_payment_interval_count` integer, nullable — The number of interval units that make up the total payment interval - `billing_agreement` string, nullable — A localized billing agreement that the payment sheet displays to the user before the user authorizes the payment - `management_url` string, required — A URL to a web page where the user can update or delete the payment method for the recurring payment - `pix_additional_details` union - object - `immediate` ImmediateExpirationTime, required - `time` integer, required — Expiration time in seconds - `pix_key` union - object - … - object - … - object - … - object - … - object - … - object - `scheduled` ScheduledExpirationTime, required - `date` string, required — Expiration time in terms of date, format: YYYY-MM-DD - `validity_after_expiration` integer, nullable — Days after expiration date for which the QR code remains valid - `pix_key` union - object - … - object - … - object - … - object - … - object - … - `boleto_additional_details` BoletoAdditionalDetails - `due_date` string, nullable — Due Date for the Boleto - `document_kind` 'commercial_invoice' | 'service_invoice' | 'promissory_note' | 'rural_promissory_note' | 'receipt' | 'insurance_policy' | 'credit_card_invoice' | 'proposal' | 'deposit_or_funding' | 'cheque' | 'direct_promissory_note' | 'other' - `payment_type` 'fixed_amount' | 'flexible_amount' | 'installment' - `covenant_code` string, nullable - `pix_key` union - object - `type` 'cpf', required - `value` string, required - object - `type` 'cnpj', required - `value` string, required - object - `type` 'email', required - `value` string, required - object - `type` 'phone', required - `value` string, required - object - `type` 'evp_token', required - `value` string, required - `discount_rules` SantanderPaymentDiscountRules — Defines the type of discount applied to a payment, such as whether it's a fixed date discount, a daily calendar discount, or a daily business discount. - `discount_type` 'standard' | 'fixed_date' | 'daily_calendar' | 'daily_business' — Defines the type of discount applied to a payment, such as whether it's a fixed date discount, a daily calendar discount, or a daily business discount. - `tiers` DiscountTier[], required — A generic vector of discount tiers - `amount` string, nullable — The discount value (e.g., "5.50"). - `end_date` string, nullable — The ISO-8601 date until which this discount is valid - `penalties` PenaltyRules — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `fixed_penalty` PenaltyDetail — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `value` string, nullable — The numeric value (as a string to preserve decimal precision) - `grace_period_days` integer, nullable — Grace period: Days after due date before this applies - `interest` InterestDetail — Represents the rules for applying discounts to a payment, such as a percentage discount or a fixed amount discount, along with any applicable grace periods. - `interest_percentage` string, nullable — Percentage of Juros (Interest). Pattern: ^[0-9]{1,3}\.[0-9]{2}$ - `iof_percentage` string, nullable — Percentage of IOF (Financial Operations Tax). Pattern: \d{3}$\.\d{5} Only provided if the agreement is "Cobra IOF na Barra ou Cadastro" - `collection_actions` CollectionActions — Represents the legal or administrative actions that may be taken for non-payment, such as protest rules and automatic write-off timelines. - `legal_protest` ProtestRules - `protest_type` 'disabled' | 'calendar_days' | 'business_days' | 'contract_default', required — Defines the type of protest for non-payment, such as whether the count is based on calendar days, business days, or if the protest logic is determined by a pre-signed contract with the bank. - `days_after_due_date` integer, required — Number of days after the due date to initiate the protest - `auto_write_off_days` integer, nullable — Days after which the bill is automatically cancelled/written off - `payment_constraints` union — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - object - `type` 'fixed_amount', required - object - `type` 'flexible_amount', required - `details` FlexibleAmountDetails, required — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - `min_value` string, nullable — Minimum value allowed (e.g., "10.00") - `max_value` string, nullable — Maximum value allowed (e.g., "5000.00") - `value_type` 'percentage' | 'flat_amount' — Defines how the payment amount is calculated for penalties or discounts, either as a percentage or as a flat amount. - object - `type` 'installment', required - `details` InstallmentDetails, required — Represents the rules for legal protest (official debt registration) for non-payment, including the type of protest and the number of days after which the protest is initiated. - `max_partial_payments` integer, nullable — Maximum number of partial payments allowed (Up to 99 for Santander). - `value_type` 'percentage' | 'flat_amount' — Defines how the payment amount is calculated for penalties or discounts, either as a percentage or as a flat amount. - `beneficiary` BeneficiaryDetails — Represents the end-recipient of a payout or fund transfer. - `name` string, nullable — The full legal name of the individual or entity receiving the funds. - `document_number` string, nullable — The customer's unique identification number (e.g., Tax ID, SSN, Passport Number). Used by processors to verify the identity of the recipient and prevent fraud. Length of the document number depends upon the document_type. For CPF/CNPJ it is typically 11/14 digits long. - `document_type` 'cpf' | 'cnpj' | 'psn' | 'other' — Represents the type of identification document used for validation. - `pix_automatico_additional_details` union — Represents the specific data for Santander Pix Automatico (recurring PIX payments) Split into CIT (Customer Initiated Transaction) and MIT (Merchant Initiated Transaction) variants - object — Data for PixAutomaticoPush Payment Method Type CIT (Customer Initiated Transaction) - used during mandate setup - `time` integer, required — Time in seconds until which the push notification is valid - `retry_policy` boolean, nullable — Enable retry policy for failed payments (maps to PERMITE_3R_7D if true) - `mandate_details` SantanderMandateDetails - `fixed_recurring_amount` integer, nullable — Fixed amount for each recurring charge in minor units (e.g., cents). If not provided, the mandate will allow variable amounts. - `min_recurring_amount` integer, nullable — Minimum amount for each recurring charge in minor units (e.g., cents). If not provided, there will be no minimum limit on the amount. - `start_date` string, nullable — Start date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid immediately. - `end_date` string, nullable — End date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid indefinitely. - `periodicity` 'weekly' | 'monthly' | 'quarterly' | 'semiannually' | 'annually' - `type` 'pix_automatico_push', required - object — Data for PixAutomaticoQr Payment Method Type CIT (Customer Initiated Transaction) - used during mandate setup + non 0$ mandate setup - `retry_policy` boolean, nullable — Enable retry policy for failed payments (maps to PERMITE_3R_7D if true) - `mandate_details` SantanderMandateDetails - `fixed_recurring_amount` integer, nullable — Fixed amount for each recurring charge in minor units (e.g., cents). If not provided, the mandate will allow variable amounts. - `min_recurring_amount` integer, nullable — Minimum amount for each recurring charge in minor units (e.g., cents). If not provided, there will be no minimum limit on the amount. - `start_date` string, nullable — Start date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid immediately. - `end_date` string, nullable — End date for the recurring charges. Format: YYYY-MM-DD. If not provided, the mandate will be valid indefinitely. - `periodicity` 'weekly' | 'monthly' | 'quarterly' | 'semiannually' | 'annually' - `type` 'pix_automatico_qr', required - object — Data for Santander Pix Automatico MIT (Merchant Initiated Transaction) - used during recurring charge creation - `receiver_details` SantanderPixAutomaticoReceiverDetails — Represents the receiver details for Santander Pix Automatico recurring charges - `branch_code` string, nullable — Branch code (agencia) of the receiver's bank account - `account_number` string, nullable — Account number (conta) of the receiver - `account_type` 'current' | 'savings' | 'payment' — Account type for Santander Pix Automatico recurring charges - `mandate_execution_date` string, nullable — Execution date for the mandate charge (maps to data_de_vencimento). Format: YYYY-MM-DD. If not provided, defaults to current date + 1 day. - `auto_adjust_date` boolean, nullable — Whether to automatically adjust the due date to the next business day if it falls on a non-business day. Maps to ajuste_dia_util in Santander API. Defaults to true if not provided. - `type` 'pix_automatico_mit', required - `finix_additional_details` FinixAdditionalDetails - `fraud_session_id` string, nullable — The fraud session ID used for Finix fraud detection ## Other responses - `400` — Missing mandatory fields --- [API](https://skmtc.net/hyperswitch/apis/dynamic-routing-openapi-3-0.md) · [All operations](https://skmtc.net/hyperswitch/apis/dynamic-routing-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hyperswitch/dynamic-routing-openapi-3-0/revisions/8fbf69ab2597/schema)