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 BDT PayIn shop whose configured schema accepts a customer mobile number, send it inside fields:

{
  "fields": {
    "mobile_number": "01700000000"
  }
}

This example does not make mobile_number mandatory for every BDT shop. Obtain the assigned BDT shop's current PayIn and PayOut schemas before integrating. 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.

Mapping BDT v1 requests to v2

The following comparison covers the request fields in the BDT v1 create PayIn and create PayOut guides. It describes the current v2 contract; not every v1 field has an equivalent.

v1 request field	v2 request field	Migration rule
external_id	order_id	Keep the merchant order identifier as a string. In v2 it must be unique per merchant and operation type across shops. Do not recreate an existing v1 payment through v2.
amount	amount	Change the decimal string "500.00" to a JSON number such as 500 or 500.25, positive and with at most two decimal places.
currency	currency	Keep "BDT"; it must match the selected shop.
shop_code	method	Keep the assigned shop code. Both may be omitted to use the active default shop. A payment-method name is not a substitute for a shop code.
callback_url	callback_url	Optional in the v1 guide; required in v2 and must be an absolute HTTPS URL without embedded credentials.
merchant_user_id	customer_account_id with limitations	v2 accepts an optional JSON integer, not the arbitrary string accepted by v1. There is no direct equivalent for "merchant-user-001" or an ID whose leading zeros are significant.
merchant_user_ip	fields.merchant_user_ip	Send the customer IP as an IPv4 or IPv6 string. Required status is defined separately by the selected shop's PayIn or PayOut schema.
PayIn paymentData	fields, except return URLs	Move shop-specific payer data into fields, using the selected PayIn schema. Do not send the v1 wrapper.
PayIn paymentData.mobile_number	fields.mobile_number	Keep the value as a string and preserve the leading zero when the shop accepts the v1 local format. The key must be allowed by the shop's schema if one exists. It is not an alias of fields.phone.
PayIn paymentData.return_user_url	success_url, pending_url, fail_url	Supply all three at the top level. They may contain the same valid HTTP(S) URL if you use a single return page. Do not send return_user_url inside fields.
PayOut card_number	account_number	Send the recipient as a top-level string. Card shops accept 12–19 digits; shops with the mobile payment method require + and 8–15 digits. Confirm other wallet formats with your integration contact.

Customer identity and IP limitations

A numeric v1 identity such as "77" can be represented by "customer_account_id": 77 when it identifies the same customer. Do not truncate, strip meaningful leading zeros, or hash an arbitrary customer ID to make it fit. Agree on a stable identity mapping before using customer-based limits or checks. Omitting the field is allowed by v2, but does not preserve the identity previously supplied to v1.

Do not use fields.merchant_user_id as a workaround: it does not populate the operation's customer identity. For the customer IP, use fields.merchant_user_ip as described above. The API connection's source IP is not a replacement for the customer's IP.

Other request differences

• Authentication changes: v2 signs the raw JSON body only and signs an empty string for GET. Do not reuse the v1 timestamp-based signature. See authentication.
• Status lookup changes: v1 uses the merchant's external_id and an optional shop_code query parameter; v2 uses the returned transaction_id in /api/v2/transactions/{transaction_id}. There is no v2 lookup by order_id; do not copy v1 lookup parameters into it.
• Balance and transaction history remain separate v1 APIs. The v1 list filters and pagination parameters have no v2 equivalent. The v1 transaction-history signature has its own canonical format; see the v1 guide.
• Unknown top-level create fields are rejected. Additional fields keys can be ignored by a configured shop schema, so a successful create response alone does not prove that every supplied key was retained.