8. Shop-specific `fields`

The optional fields object in POST /api/v2/deposits and POST /api/v2/withdrawals carries additional data for the shop selected by method. When method is omitted, the merchant's active default shop is selected. PayIn and PayOut can have different input schemas for the same shop.

The v2 API has no endpoint for retrieving a shop's field schema. Before integrating a shop, obtain its exact code and the PayIn or PayOut field specification: required names, types, formats, allowed values, and any defaults. These rules come from the current shop configuration. There is no universal list of required fields for every v2 merchant.

Rule	v2 behavior
JSON shape	`fields` is a JSON object. Omit it when the selected shop requires no additional values. A JSON array is rejected.
Required keys	Missing required fields in the selected shop's schema make the create request fail with HTTP 400.
Types and values	Configured field types and validation rules are applied. Some allowed-value lists come from current merchant-operation settings.
Standard customer fields	Non-empty `first_name`, `last_name`, `middle_name`, `email`, and `phone` values must be strings for both directions. Additional schema rules may also apply.
Unknown keys	When a shop schema exists, unknown `fields` keys are ignored. `merchant_user_ip` is a supported system field even when not listed in that schema. Do not rely on other unknown keys being saved.
No shop schema	If the selected shop has no input schema for that direction, the supplied `fields` object is accepted after standard customer-field, IP, and reserved-name checks.
Reserved names	`method` and `customer_account_id` cannot appear inside `fields`. For deposits, `success_url`, `pending_url`, `fail_url`, and `return_user_url` are also reserved. For withdrawals, `account_channel`, `recipient_account`, and `account_number` are also reserved.
Responses	Create and status responses do not echo `fields`; use the documented response schemas for those endpoints. In particular, a payer account supplied here is not guaranteed to appear in deposit status; confirm the supported mapping for your channel.

Customer IP

Send the customer's IP address as fields.merchant_user_ip in either a deposit or withdrawal request. It must be a string containing one IPv4 or IPv6 address, without surrounding whitespace, a port, a CIDR suffix, or a list of addresses. An invalid value, including an empty string, returns HTTP 400.

The field is supported even when not listed in the shop schema. Its required status comes from the selected shop's PayIn or PayOut input schema; it is not required globally. If optional and unavailable, omit it or send null. If required, omission or null returns HTTP 400. The API does not substitute the connection's source IP or a schema default for the customer's IP.

{
  "fields": {
    "merchant_user_ip": "203.0.113.10"
  }
}

The supplied IP becomes the operation's customer IP and is available to configured payment checks and provider mappings. It does not change API-key authentication or the API connection's IP whitelist. Keep the same value when retrying an order: changing it under the same order_id returns HTTP 409. Do not send merchant_user_ip at the top level of a v2 request.

For a VND EPT PayOut shop configured with recipient bank details, send the recipient account in top-level account_number and the configured bank details in fields:

{
  "fields": {
    "bank_code": "VVCB",
    "holder": "Nguyen Van An"
  }
}

For a VND EPT PayIn shop, its configured schema may instead use account_number and holder inside fields. Confirm the assigned shop's current schema and allowed bank codes. The v1 paymentData pages describe v1 requests; v2 uses fields, different top-level fields, a JSON-number amount, and its own authentication and response format.

Customer IP​

Customer IP