Update payment form flow

Before updating parameters, complete create your payment form so the form is initialized on the page.

There is no need to call the payment form repeatedly when using multiple tariffs. Request the form once and modify the amount , currency , product_id , or any parameter of the partialIntent object using the form instance’s update method.

To update a Payment Form parameter, generate the signature parameter on your backend. This signature verifies the merchant’s request authenticity on the payment gateway server and originates from the partialIntent encrypted String

Backend setup

Firstly, ensure that the backend is prepared. In the example code, the formUpdate function is called with fields.

Specifically, this method allows updates only to a predefined list of fields, distinct from those available during initial form creation in the paymentIntent object. Updates are limited to select parameters within the partialIntent object.

It is important to note that attempting to update fields not defined in the allowed list results in an error response. Choose your payment scenario to see the fields it requires. Payment amount integer >=0 Required

Description

Order amount in minor units. For example, 1020 means 10 USD and 20 cents. Can be 0 for zero-amount authorization.

Example

1020

Product-based payment product_id string 36 Required

Description

Identifier of the predefined product in UUID v4 format.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Customer ID in the merchant’s system.

Example

4dad42f878

Subscription payment product_price_id string 36 Required

Description

Price ID of the predefined product. Use get product prices to obtain it.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Customer ID in the merchant’s system.

Example

4dad42f878

currency string 3 Required

Description

Currency in three-letter code per the ISO-4217 Wiki standard.

Example

USD

order_description string 255

Description

Order description in your system and for bank processing.

Highly recommended to keep the description brief to improve the clarity of payment processing, ideally not exceeding 100 characters. It is used in the email receipt sent to the customer.

Example

Premium package

order_items string 255

Description

Order items in UTF-8 code.

Example

item1, item2

order_date string 50

Description

Date of order creation following the ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ pattern.

Example

2025-12-21 11:21:30

order_number integer int32

Description

Number of payments by the customer.

Example

1

settle_interval integer [0..240]

Description

Delay before settlement in hours:

  • Visa customer-initiated payments: 240 hours = 10 days
  • Visa merchant-initiated payments: 120 hours = 5 days
  • All other card brands: 168 hours = 7 days
It is highly recommended to validate the value against your payment processor’s PSP limits.

Example

48

force3ds boolean

Description

Routing payments flag for 3DS flow.

Example

true

customer_email string 100

Description

Customer email.

If email on the initialization payment form was:

  • non-empty, you cannot change it to an empty email
  • non-empty, and you provide a new email, the new value is passed
  • empty and you provide a new email, the form uses that email as a prefilled value The customer has the option to change it or to confirm it by submission.

Example

test@solidgate.com

traffic_source string 255

Description

Identifies the marketing or acquisition channel that brought the customer to the transaction.

Example

facebook

transaction_source string 255

Description

Identifies the internal system or flow that triggered the transaction.

Example

main_menu

order_metadata object

Description

Metadata is useful for storing additional, structured information about an object, consisting of up to 10 key-value pairs with a validation limit of 380 characters per field.

The callback notification returns an order_metadata from the order in each state.

Example

{"coupon_code": "NY2025", "partner_id": "123989"}

success_url string 255

Description

Provide this URL if you want to redirect a customer to your own Success Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Success Screen. The Solidgate notification screen is not customizable, but you can define your own success and fail pages during Payment Form initialization with success_url and fail_url.

Example

http://merchant.example/success

fail_url string 255

Description

Provide this URL if you want to redirect a customer to your own Fail Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Fail Screen.

Example

http://merchant.example/fail

Payment 
{
  "amount": 1020,
  "currency": "EUR",
  "order_description": "Premium package",
  "order_items": "item5",
  "order_date": "2025-02-21 11:21:30",
  "order_number": 4,
  "settle_interval": 48,
  "force3ds": true,
  "customer_email": "user-one@mail.com",
  "traffic_source": "Instagram",
  "transaction_source": "Main menu",
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  },
  "success_url": "http://merchant.example/success",
  "fail_url": "http://merchant.example/fail"
}
Product-based payment 
{
  "product_id": "47f95c95-3647-4c5b-ae6d-40fd8d3ac742",
  "customer_account_id": "4dad42f808",
  "currency": "EUR",
  "order_description": "Premium package",
  "order_items": "item5",
  "order_date": "2025-02-21 11:21:30",
  "order_number": 4,
  "settle_interval": 48,
  "force3ds": true,
  "customer_email": "user-one@mail.com",
  "traffic_source": "Instagram",
  "transaction_source": "Main menu",
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  },
  "success_url": "http://merchant.example/success",
  "fail_url": "http://merchant.example/fail"
}
Subscription payment 
{
  "product_price_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "customer_account_id": "4dad42f808",
  "currency": "EUR",
  "order_description": "Premium package",
  "order_items": "item5",
  "order_date": "2025-02-21 11:21:30",
  "order_number": 4,
  "settle_interval": 48,
  "force3ds": true,
  "customer_email": "user-one@mail.com",
  "traffic_source": "Instagram",
  "transaction_source": "Main menu",
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  },
  "success_url": "http://merchant.example/success",
  "fail_url": "http://merchant.example/fail"
}
Step 1. Form partial intent data

For updating, provide transaction-related information. This information resides in a FormUpdateDTO object, created by invoking the formUpdate function on your API instance.

PHP 
<?php

use SolidGate\API\Api;

$api = new Api('public_key', 'secret_key');

$formUpdateDTO = $api->formUpdate(['JSON payment intent // fill as described in documentation']);
Node.js 
const solidGate = require('@solidgate/node-sdk');

let api = new solidGate.Api("public_key", "secret_key");

let partialIntentData = {
    /// fill it as described in documentation
}
let formUpdateDTO = api.formUpdate(partialIntentData);

const dataToFront = formUpdateDTO.toObject()

/// This values should be applied on front end in the following way

const form.update(dataToFront)
Go 
package main

import (
    "encoding/json"
    "fmt"

    solidgate "github.com/solidgate-tech/go-sdk"
)

type UpdateParams struct {
    ...
}

func main() {
    solidgateSdk := solidgate.NewSolidGateApi("public_key", "secret_key")
    partialIntent := solidgate.PartialIntent{} // fill in the necessary information for updating as described in the documentation
    partialIntentBytes, err := json.Marshal(partialIntent)

    if err != nil {
        fmt.Print(err)
    }

    formUpdateDto, err := solidgateSdk.FormUpdate(partialIntentBytes)

    if err != nil {
        fmt.Print(err)
    }

    // ...
}
Kotlin 
val api = Api(HttpClient(), Credentials("public_key", "secret_key"))

val attributes = Attributes(mapOf(
    // fill as described in documentation
))

val formUpdateDTO = api.formUpdate(attributes)
Python 
from solidgate import ApiClient

client = ApiClient("public_key", "secret_key")

partial_intent_dict = {} # fill as described in documentation
responseDTO = client.form_update(partial_intent_dict)
Step 2. Pass generated data to frontend

The FormUpdateDTO object, returned by the FormUpdateDTO function, is a class instance. Convert it to a plain object for use in frontend code. This conversion is accomplished by calling the toObject function on the FormUpdateDTO object, resulting in a plain JavaScript object.

After forming the merchant data and converting it to a plain object, use it in frontend code to update with the partialIntent encrypted String

Partial form update

partialIntent string

Description

Encrypted aes-cbc-256 string of JSON request data with random IV (16 bytes) and secret key is the first 32 bytes of the merchant secret key.

Example

E5FKjxw5vRjjIZ....vmG2YFjg5xcvuedQ==

signature string

Description

Signature of request.

It allows verifying whether the request from the Merchant is genuine on the payment gateway server.

Example

MjNiYjVj…ZhYmMxMzNiZDY=

React 
import React, { FC, useRef, useCallback, useEffect } from 'react'
import ReactDOM from 'react-dom';
import Payment, { InitConfig, ClientSdkInstance } from "@solidgate/react-sdk"

export const MyPayment: FC<{
  merchantData: InitConfig['merchantData']
  update?: {
    partialIntent: string;
    signature: string;
  }
}> = (props) => {
  const formResolve = useRef<(form: ClientSdkInstance) => void>(() => {})
  const formPromise = useRef<Promise<ClientSdkInstance>>()

  const handleOnReadyPaymentInstance = useCallback((form: ClientSdkInstance) => {
    formResolve.current(form)
  }, [])

  useEffect(() => {
    formPromise.current = new Promise<ClientSdkInstance>((resolve) => {
      formResolve.current = resolve
    })
  }, [])

  useEffect(() => {
    if (props.update && formPromise.current) {
      formPromise.current.then((form) => form
        .update(props.update)
        .then(callbackForSuccessUpdate)
        .catch(callbackForFailedUpdate)
      )
    }
  }, [props.update])

  return (
    <Payment
      merchantData={props.merchantData}
      onReadyPaymentInstance={handleOnReadyPaymentInstance}
  />)
}
Vanilla JS 
form
  .update({ partialIntent, signature })
  .then(callbackForSuccessUpdate)
  .catch(callbackForFailedUpdate);
Vue 
<template>
  <Payment
    :merchant-data="merchantData"
      @ready-payment-instance="onReadyPaymentInstance"
  />
</template>

<script lang="ts" setup>
import { defineAsyncComponent } from 'vue'
import { InitConfig, ClientSdkInstance } from '@solidgate/vue-sdk'
const Payment = defineAsyncComponent(() => import('@solidgate/vue-sdk'))

const merchantData: InitConfig['merchantData'] = {
  merchant: '<<--YOUR MERCHANT ID-->>',
  signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
  paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
}

function onReadyPaymentInstance(form: ClientSdkInstance): void {
  form
      .update({ partialIntent, signature })
      .then(callbackForSuccessUpdate)
      .catch(callbackForFailedUpdate)
}
</script>
Angular 
import {Component} from '@angular/core';
import {BehaviorSubject, filter} from 'rxjs'
import {InitConfig, SdkMessage, MessageType} from '@solidgate/angular-sdk';

@Component({
  selector: 'app-root',
  template: `
    <ngx-solid-payment
      [merchantData]="merchantData"
      (readyPaymentInstance)="formSubject$.next($event)"
    ></ngx-solid-payment>
  `
})
export class AppComponent {
  formSubject$ = new BehaviorSubject<ClientSdkInstance | null>(null)

  form$ = this.formSubject$.pipe(filter(Boolean))

  merchantData: InitConfig['merchantData'] = {
    merchant: '<<--YOUR MERCHANT ID-->>',
    signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
    paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
  }

  update(payload: {
    partialIntent: string;
    signature: string;
  }): void {
    this.form$.subscribe(form => form
      .update(payload)
      .then(callbackForSuccessUpdate)
      .catch(callbackForFailedUpdate))
  }
}
It is very important to handle possible errors, including network errors, in callbackForFailedUpdate by calling a valid update or init. Otherwise, the form remains unresponsive.

If an invalid parameter exists in the updateIntent request, such as a non-unique product_id, an error occurs.

Update Error 
{
  "error": {
    "code": "2.01",
    "message": [
      "Invalid Data"
    ]
  }
}