Additional fields

INFO

This section describes optional and context-specific fields that can be included in payment and payout requests. These fields allow for extended customization and support integration scenarios that require additional metadata or business logic parameters.

AdditionalFields you can add in next methods:

Deposit H2H - Card & P2P — hosted on the secure subdomain. Requires the merchant to have a PCI DSS certificate and allows direct card data transmission between servers (host-to-host).

Deposit H2H - Token — hosted on the token subdomain. Enables recurring payments using previously obtained tokens.

Deposit H2С - Card — hosted on the init subdomain. Does not require PCI DSS. Used to initiate a payment without card data; the user is then redirected to a web form to enter card details.

Payout H2H — a server-to-server interaction method, similar to deposits.

These fields may be used for both deposits and payouts.

Different payment gateways integrated with PayStar may require different sets of additional fields. Some of these fields can also be used for validation or routing purposes. In other words, the exact set of required additional fields depends on the specific financial flow and cannot be predefined in this documentation.

You have two options:

Provide all available additional fields in your request;

Contact your Account Manager to confirm which fields are required in your specific use case.

CURL Example all additional fields

curl --request POST \
  --url https://secure.PayStar.uk/api/v1/integration/deposit-order\ 
  --header 'Authorization: Bearer YOUR TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'accept: text/plain' \
  --data '{
    "amount": 100, 
    "currency": "USD",
    "externalTransactionId": "Merch-bf95219b-393d-4323-91bf-639be",
    "additionalFields": [ 
        {
            "key": "type",
            "value": "card"
        },
        {
            "key": "productCode",
            "value": "Merch-12345" 
        }, 
        {
            "key": "phoneNumber",
            "value": "+44644012345"
        },
        {
            "key": "telecomOperator",
            "value": "vadafone" 
        }
    ]
}

DOWNLOAD

Additional_fields.json - download the full list of Additional fields in a single JSON file.

Payment method & card

Field	Description with Example
productCode	Internal product or service code, e.g. Merch-12345
cardNumber	Full card number PAN, e.g. 1234123412341234
cardExpireMonth	Card expiry month MM, e.g. 05
cardExpireYear	Card expiry year YY, e.g. 26
cardCvv	CVV or CVC code 3–4 digits, e.g. 583
cardHolder	Name on the card, e.g. JOHN WEAK
cardToken	Tokenized card identifier for recurring or saved payments, e.g. a1b2c3d4e5f6g7h8

Customer identity KYC

Field	Description with Example
firstName	Customer’s first name
middleName	Customer’s middle name
lastName	Customer’s last name
customerDocumentId	Government-issued ID number; add type if needed, e.g. Passport 123456789
customerBirthdayDate	Date of birth YYYY-MM-DD, e.g. 2019-04-05
customerNationality	Nationality ISO 3166-1 alpha-3, e.g. UKR

Customer contact & address

Field	Description with Example
email	Customer email address, e.g. john.wick@continental.com
phoneNumber	Customer’s phone number, e.g. 44644012345
telecomOperator	Mobile network name used for telecom or mobile payments, e.g. vodafone or airtel
dialingCode	International dialing code, e.g. 31
customerAddress	Full street address line 1; add line 2 if needed, e.g. 123 Main Street, Apt 5B
customerCity	City or locality, e.g. Amsterdam
customerState	State or region where applicable, e.g. CA or Île-de-France
customerZipCode	Postal or ZIP code local format, e.g. 1012 AB
customerCountryCode	ISO 3166-1 alpha-3 country code, e.g. NLD
customerCountry	Full country name if PSP expects name, e.g. Netherlands

Bank & payment details

Field	Description with Example
beneficiaryName	Full legal name of account holder, e.g. John Smith or Natalia Ivanova
bankName	Bank name, e.g. Goldman Sachs
bankAccount	Beneficiary’s bank account number, e.g. 1234567890
iban	International Bank Account Number, e.g. NL91ABNA0417164300
bankCode	National bank identifier country-specific, e.g. DE BLZ 37040044 or BR 237
bankBranch	Branch identifier or name local format, e.g. UK sort code 20-00-00 or Main Branch Mumbai
ifcsCode	Indian bank IFSC 11-char code, e.g. HDFC0001234

Crypto

Field	Description with Example
cryptoWalletAdress	Customer’s crypto wallet address; specify chain if needed, e.g. 0x12ab34cd56ef… Ethereum or TQ1x9… TRON

Browser & 3DS context

Field	Description with Example
browserUserAgent	Full browser User-Agent string, e.g. Mozilla/5.0 Windows NT 10.0; Win64; x64…
browserAcceptHeader	HTTP Accept header from browser, e.g. text/html,application/xhtml+xml
browserLanguage	Language set in the browser, e.g. en-EN
browserJavaEnabled	Is Java enabled true/false, e.g. true
browserJavascriptEnabled	Is JavaScript enabled true/false, e.g. true
browserColorDepth	Screen color depth in bits, e.g. 24
browserScreenWidth	Screen width in pixels, e.g. 1920
browserScreenHeight	Screen height in pixels, e.g. 1080
browserTZ	Timezone offset from UTC in minutes, e.g. -180
browserChallengeWindowSize	3DS challenge window size code: 01 = 250x400, 02 = 390x400, 03 = 500x600 example 03

Merchant / store

Field	Description with Example
storeUrl	Merchant’s website or checkout URL, e.g. https://merchant.example.com/

Miscellaneous

Field	Description with Example
ip	User's IP address, e.g. 62.76.69.168
payeerIdentifier	Payer's ID on the merchant side, e.g. Merch-12345
telecomOperator	Mobile network name used for telecom/mobile payments, e.g. vodafone or airtel

Payment method & card#

Customer identity KYC#

Customer contact & address#

Bank & payment details#

Crypto#

Browser & 3DS context#

Merchant / store#

Miscellaneous#

Payment method & card

Customer identity KYC

Customer contact & address

Bank & payment details

Crypto

Browser & 3DS context

Merchant / store

Miscellaneous