Skip to main content
POST
/
payments
/
{payment_id}
/
update_metadata
Payments - Update Metadata
curl --request POST \
  --url https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "metadata": {},
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_count": 123
      },
      "management_url": "https://hyperswitch.io",
      "billing_agreement": "<string>"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 1,
        "pix_key": {
          "type": "cpf",
          "value": "<string>"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "<string>"
      },
      "discount_rules": {
        "tiers": [
          {
            "amount": "5.50",
            "end_date": "2027-12-31"
          }
        ]
      },
      "penalties": {
        "fixed_penalty": {
          "value": "2.00",
          "grace_period_days": 1
        },
        "interest": {
          "interest_percentage": "5.00",
          "iof_percentage": "32.45325"
        }
      },
      "collection_actions": {
        "legal_protest": {
          "days_after_due_date": 30
        },
        "auto_write_off_days": 60
      },
      "payment_constraints": {
        "type": "fixed_amount"
      },
      "beneficiary": {
        "name": "João da Silva",
        "document_number": "9615865832"
      }
    },
    "pix_automatico_additional_details": {
      "time": 3600,
      "type": "pix_automatico_push",
      "retry_policy": true,
      "mandate_details": {
        "fixed_recurring_amount": 6540,
        "min_recurring_amount": 6540,
        "start_date": "2026-12-31",
        "end_date": "2026-12-31"
      }
    },
    "finix_additional_details": {
      "fraud_session_id": "1234567890abcdef"
    }
  }
}
'
import requests

url = "https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata"

payload = {
    "metadata": {},
    "feature_metadata": {
        "redirect_response": {
            "param": "<string>",
            "json_payload": {}
        },
        "search_tags": ["<string>"],
        "apple_pay_recurring_details": {
            "payment_description": "<string>",
            "regular_billing": {
                "label": "<string>",
                "recurring_payment_start_date": "2023-09-10T23:59:59Z",
                "recurring_payment_end_date": "2023-09-10T23:59:59Z",
                "recurring_payment_interval_count": 123
            },
            "management_url": "https://hyperswitch.io",
            "billing_agreement": "<string>"
        },
        "pix_additional_details": { "immediate": {
                "time": 1,
                "pix_key": {
                    "type": "cpf",
                    "value": "<string>"
                }
            } },
        "boleto_additional_details": {
            "due_date": "2026-12-31",
            "covenant_code": "3568253",
            "pix_key": {
                "type": "cpf",
                "value": "<string>"
            },
            "discount_rules": { "tiers": [
                    {
                        "amount": "5.50",
                        "end_date": "2027-12-31"
                    }
                ] },
            "penalties": {
                "fixed_penalty": {
                    "value": "2.00",
                    "grace_period_days": 1
                },
                "interest": {
                    "interest_percentage": "5.00",
                    "iof_percentage": "32.45325"
                }
            },
            "collection_actions": {
                "legal_protest": { "days_after_due_date": 30 },
                "auto_write_off_days": 60
            },
            "payment_constraints": { "type": "fixed_amount" },
            "beneficiary": {
                "name": "João da Silva",
                "document_number": "9615865832"
            }
        },
        "pix_automatico_additional_details": {
            "time": 3600,
            "type": "pix_automatico_push",
            "retry_policy": True,
            "mandate_details": {
                "fixed_recurring_amount": 6540,
                "min_recurring_amount": 6540,
                "start_date": "2026-12-31",
                "end_date": "2026-12-31"
            }
        },
        "finix_additional_details": { "fraud_session_id": "1234567890abcdef" }
    }
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    metadata: {},
    feature_metadata: {
      redirect_response: {param: '<string>', json_payload: {}},
      search_tags: ['<string>'],
      apple_pay_recurring_details: {
        payment_description: '<string>',
        regular_billing: {
          label: '<string>',
          recurring_payment_start_date: '2023-09-10T23:59:59Z',
          recurring_payment_end_date: '2023-09-10T23:59:59Z',
          recurring_payment_interval_count: 123
        },
        management_url: 'https://hyperswitch.io',
        billing_agreement: '<string>'
      },
      pix_additional_details: {immediate: {time: 1, pix_key: {type: 'cpf', value: '<string>'}}},
      boleto_additional_details: {
        due_date: '2026-12-31',
        covenant_code: '3568253',
        pix_key: {type: 'cpf', value: '<string>'},
        discount_rules: {tiers: [{amount: '5.50', end_date: '2027-12-31'}]},
        penalties: {
          fixed_penalty: {value: '2.00', grace_period_days: 1},
          interest: {interest_percentage: '5.00', iof_percentage: '32.45325'}
        },
        collection_actions: {legal_protest: {days_after_due_date: 30}, auto_write_off_days: 60},
        payment_constraints: {type: 'fixed_amount'},
        beneficiary: {name: 'João da Silva', document_number: '9615865832'}
      },
      pix_automatico_additional_details: {
        time: 3600,
        type: 'pix_automatico_push',
        retry_policy: true,
        mandate_details: {
          fixed_recurring_amount: 6540,
          min_recurring_amount: 6540,
          start_date: '2026-12-31',
          end_date: '2026-12-31'
        }
      },
      finix_additional_details: {fraud_session_id: '1234567890abcdef'}
    }
  })
};

fetch('https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        
    ],
    'feature_metadata' => [
        'redirect_response' => [
                'param' => '<string>',
                'json_payload' => [
                                
                ]
        ],
        'search_tags' => [
                '<string>'
        ],
        'apple_pay_recurring_details' => [
                'payment_description' => '<string>',
                'regular_billing' => [
                                'label' => '<string>',
                                'recurring_payment_start_date' => '2023-09-10T23:59:59Z',
                                'recurring_payment_end_date' => '2023-09-10T23:59:59Z',
                                'recurring_payment_interval_count' => 123
                ],
                'management_url' => 'https://hyperswitch.io',
                'billing_agreement' => '<string>'
        ],
        'pix_additional_details' => [
                'immediate' => [
                                'time' => 1,
                                'pix_key' => [
                                                                'type' => 'cpf',
                                                                'value' => '<string>'
                                ]
                ]
        ],
        'boleto_additional_details' => [
                'due_date' => '2026-12-31',
                'covenant_code' => '3568253',
                'pix_key' => [
                                'type' => 'cpf',
                                'value' => '<string>'
                ],
                'discount_rules' => [
                                'tiers' => [
                                                                [
                                                                                                                                'amount' => '5.50',
                                                                                                                                'end_date' => '2027-12-31'
                                                                ]
                                ]
                ],
                'penalties' => [
                                'fixed_penalty' => [
                                                                'value' => '2.00',
                                                                'grace_period_days' => 1
                                ],
                                'interest' => [
                                                                'interest_percentage' => '5.00',
                                                                'iof_percentage' => '32.45325'
                                ]
                ],
                'collection_actions' => [
                                'legal_protest' => [
                                                                'days_after_due_date' => 30
                                ],
                                'auto_write_off_days' => 60
                ],
                'payment_constraints' => [
                                'type' => 'fixed_amount'
                ],
                'beneficiary' => [
                                'name' => 'João da Silva',
                                'document_number' => '9615865832'
                ]
        ],
        'pix_automatico_additional_details' => [
                'time' => 3600,
                'type' => 'pix_automatico_push',
                'retry_policy' => true,
                'mandate_details' => [
                                'fixed_recurring_amount' => 6540,
                                'min_recurring_amount' => 6540,
                                'start_date' => '2026-12-31',
                                'end_date' => '2026-12-31'
                ]
        ],
        'finix_additional_details' => [
                'fraud_session_id' => '1234567890abcdef'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata"

	payload := strings.NewReader("{\n  \"metadata\": {},\n  \"feature_metadata\": {\n    \"redirect_response\": {\n      \"param\": \"<string>\",\n      \"json_payload\": {}\n    },\n    \"search_tags\": [\n      \"<string>\"\n    ],\n    \"apple_pay_recurring_details\": {\n      \"payment_description\": \"<string>\",\n      \"regular_billing\": {\n        \"label\": \"<string>\",\n        \"recurring_payment_start_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_end_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_interval_count\": 123\n      },\n      \"management_url\": \"https://hyperswitch.io\",\n      \"billing_agreement\": \"<string>\"\n    },\n    \"pix_additional_details\": {\n      \"immediate\": {\n        \"time\": 1,\n        \"pix_key\": {\n          \"type\": \"cpf\",\n          \"value\": \"<string>\"\n        }\n      }\n    },\n    \"boleto_additional_details\": {\n      \"due_date\": \"2026-12-31\",\n      \"covenant_code\": \"3568253\",\n      \"pix_key\": {\n        \"type\": \"cpf\",\n        \"value\": \"<string>\"\n      },\n      \"discount_rules\": {\n        \"tiers\": [\n          {\n            \"amount\": \"5.50\",\n            \"end_date\": \"2027-12-31\"\n          }\n        ]\n      },\n      \"penalties\": {\n        \"fixed_penalty\": {\n          \"value\": \"2.00\",\n          \"grace_period_days\": 1\n        },\n        \"interest\": {\n          \"interest_percentage\": \"5.00\",\n          \"iof_percentage\": \"32.45325\"\n        }\n      },\n      \"collection_actions\": {\n        \"legal_protest\": {\n          \"days_after_due_date\": 30\n        },\n        \"auto_write_off_days\": 60\n      },\n      \"payment_constraints\": {\n        \"type\": \"fixed_amount\"\n      },\n      \"beneficiary\": {\n        \"name\": \"João da Silva\",\n        \"document_number\": \"9615865832\"\n      }\n    },\n    \"pix_automatico_additional_details\": {\n      \"time\": 3600,\n      \"type\": \"pix_automatico_push\",\n      \"retry_policy\": true,\n      \"mandate_details\": {\n        \"fixed_recurring_amount\": 6540,\n        \"min_recurring_amount\": 6540,\n        \"start_date\": \"2026-12-31\",\n        \"end_date\": \"2026-12-31\"\n      }\n    },\n    \"finix_additional_details\": {\n      \"fraud_session_id\": \"1234567890abcdef\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {},\n  \"feature_metadata\": {\n    \"redirect_response\": {\n      \"param\": \"<string>\",\n      \"json_payload\": {}\n    },\n    \"search_tags\": [\n      \"<string>\"\n    ],\n    \"apple_pay_recurring_details\": {\n      \"payment_description\": \"<string>\",\n      \"regular_billing\": {\n        \"label\": \"<string>\",\n        \"recurring_payment_start_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_end_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_interval_count\": 123\n      },\n      \"management_url\": \"https://hyperswitch.io\",\n      \"billing_agreement\": \"<string>\"\n    },\n    \"pix_additional_details\": {\n      \"immediate\": {\n        \"time\": 1,\n        \"pix_key\": {\n          \"type\": \"cpf\",\n          \"value\": \"<string>\"\n        }\n      }\n    },\n    \"boleto_additional_details\": {\n      \"due_date\": \"2026-12-31\",\n      \"covenant_code\": \"3568253\",\n      \"pix_key\": {\n        \"type\": \"cpf\",\n        \"value\": \"<string>\"\n      },\n      \"discount_rules\": {\n        \"tiers\": [\n          {\n            \"amount\": \"5.50\",\n            \"end_date\": \"2027-12-31\"\n          }\n        ]\n      },\n      \"penalties\": {\n        \"fixed_penalty\": {\n          \"value\": \"2.00\",\n          \"grace_period_days\": 1\n        },\n        \"interest\": {\n          \"interest_percentage\": \"5.00\",\n          \"iof_percentage\": \"32.45325\"\n        }\n      },\n      \"collection_actions\": {\n        \"legal_protest\": {\n          \"days_after_due_date\": 30\n        },\n        \"auto_write_off_days\": 60\n      },\n      \"payment_constraints\": {\n        \"type\": \"fixed_amount\"\n      },\n      \"beneficiary\": {\n        \"name\": \"João da Silva\",\n        \"document_number\": \"9615865832\"\n      }\n    },\n    \"pix_automatico_additional_details\": {\n      \"time\": 3600,\n      \"type\": \"pix_automatico_push\",\n      \"retry_policy\": true,\n      \"mandate_details\": {\n        \"fixed_recurring_amount\": 6540,\n        \"min_recurring_amount\": 6540,\n        \"start_date\": \"2026-12-31\",\n        \"end_date\": \"2026-12-31\"\n      }\n    },\n    \"finix_additional_details\": {\n      \"fraud_session_id\": \"1234567890abcdef\"\n    }\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox.hyperswitch.io/payments/{payment_id}/update_metadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {},\n  \"feature_metadata\": {\n    \"redirect_response\": {\n      \"param\": \"<string>\",\n      \"json_payload\": {}\n    },\n    \"search_tags\": [\n      \"<string>\"\n    ],\n    \"apple_pay_recurring_details\": {\n      \"payment_description\": \"<string>\",\n      \"regular_billing\": {\n        \"label\": \"<string>\",\n        \"recurring_payment_start_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_end_date\": \"2023-09-10T23:59:59Z\",\n        \"recurring_payment_interval_count\": 123\n      },\n      \"management_url\": \"https://hyperswitch.io\",\n      \"billing_agreement\": \"<string>\"\n    },\n    \"pix_additional_details\": {\n      \"immediate\": {\n        \"time\": 1,\n        \"pix_key\": {\n          \"type\": \"cpf\",\n          \"value\": \"<string>\"\n        }\n      }\n    },\n    \"boleto_additional_details\": {\n      \"due_date\": \"2026-12-31\",\n      \"covenant_code\": \"3568253\",\n      \"pix_key\": {\n        \"type\": \"cpf\",\n        \"value\": \"<string>\"\n      },\n      \"discount_rules\": {\n        \"tiers\": [\n          {\n            \"amount\": \"5.50\",\n            \"end_date\": \"2027-12-31\"\n          }\n        ]\n      },\n      \"penalties\": {\n        \"fixed_penalty\": {\n          \"value\": \"2.00\",\n          \"grace_period_days\": 1\n        },\n        \"interest\": {\n          \"interest_percentage\": \"5.00\",\n          \"iof_percentage\": \"32.45325\"\n        }\n      },\n      \"collection_actions\": {\n        \"legal_protest\": {\n          \"days_after_due_date\": 30\n        },\n        \"auto_write_off_days\": 60\n      },\n      \"payment_constraints\": {\n        \"type\": \"fixed_amount\"\n      },\n      \"beneficiary\": {\n        \"name\": \"João da Silva\",\n        \"document_number\": \"9615865832\"\n      }\n    },\n    \"pix_automatico_additional_details\": {\n      \"time\": 3600,\n      \"type\": \"pix_automatico_push\",\n      \"retry_policy\": true,\n      \"mandate_details\": {\n        \"fixed_recurring_amount\": 6540,\n        \"min_recurring_amount\": 6540,\n        \"start_date\": \"2026-12-31\",\n        \"end_date\": \"2026-12-31\"\n      }\n    },\n    \"finix_additional_details\": {\n      \"fraud_session_id\": \"1234567890abcdef\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "payment_id": "<string>",
  "metadata": {},
  "status": "requires_confirmation",
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_count": 123
      },
      "management_url": "https://hyperswitch.io",
      "billing_agreement": "<string>"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 1,
        "pix_key": {
          "type": "cpf",
          "value": "<string>"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "<string>"
      },
      "discount_rules": {
        "tiers": [
          {
            "amount": "5.50",
            "end_date": "2027-12-31"
          }
        ]
      },
      "penalties": {
        "fixed_penalty": {
          "value": "2.00",
          "grace_period_days": 1
        },
        "interest": {
          "interest_percentage": "5.00",
          "iof_percentage": "32.45325"
        }
      },
      "collection_actions": {
        "legal_protest": {
          "days_after_due_date": 30
        },
        "auto_write_off_days": 60
      },
      "payment_constraints": {
        "type": "fixed_amount"
      },
      "beneficiary": {
        "name": "João da Silva",
        "document_number": "9615865832"
      }
    },
    "pix_automatico_additional_details": {
      "time": 3600,
      "type": "pix_automatico_push",
      "retry_policy": true,
      "mandate_details": {
        "fixed_recurring_amount": 6540,
        "min_recurring_amount": 6540,
        "start_date": "2026-12-31",
        "end_date": "2026-12-31"
      }
    },
    "finix_additional_details": {
      "fraud_session_id": "1234567890abcdef"
    }
  }
}
{
  "error_type": "invalid_request",
  "message": "Missing required param: {param}",
  "code": "IR_04"
}

Authorizations

​
api-key
string
header
required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path Parameters

​
payment_id
string
required

The identifier for payment

Body

application/json
​
metadata
object
required

Metadata is useful for storing additional, unstructured information on an object.

​
feature_metadata
object | null

additional data that might be required by hyperswitch

Response

Metadata updated successfully

​
payment_id
string
required

The identifier for the payment

​
metadata
object | null

Metadata is useful for storing additional, unstructured information on an object.

​
status
enum<string> | null
default:requires_confirmation

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).

Available options:
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
​
feature_metadata
object | null

additional data that might be required by hyperswitch