48 posts tagged with "release"

Changelog​

Orders​

Cryptocurrency Payment Structure Unification (Breaking):

The cryptocurrency payment parameters in the Create Order request have been restructured for clarity and to group merchant-side data under a dedicated recipient object. See the updated Cryptocurrency Reference Guide for full details.

• Removed the cryptoPayment object. Its fields have been moved and renamed as described below.
• Added order.cost.tokenStandard — the token standard of the customer's wallet cryptocurrency (for example, TRC20, ERC20, BEP20). Replaces the former cryptoPayment.walletTokenStandard. Optional. Should be provided for token-based cryptocurrencies when using crypto_currency_code in order.cost.currency; not needed for native cryptocurrencies or when using asset_code format.
• Added recipient object with the nested merchantBalance object, which declares the currency of the merchant's balance. The merchant balance currency may be fiat or crypto and is independent from order.cost.currency (the currency the customer pays in).
  • recipient.merchantBalance.currency — the merchant balance currency code (replaces the former cryptoPayment.accountCurrency.currency). Required when the merchantBalance object is provided.
  • recipient.merchantBalance.tokenStandard — the token standard of the merchant balance currency (replaces the former cryptoPayment.accountCurrency.networkTokenStandard). Optional. Should be provided when merchantBalance.currency is a token-based cryptocurrency; ignored for fiat currencies.

Migration example:

Before:

{
  "order": {
    "cost": {
      "amount": "20",
      "currency": "USDT"
    }
  },
  "cryptoPayment": {
    "walletTokenStandard": "TRC20",
    "accountCurrency": {
      "currency": "USDC",
      "networkTokenStandard": "TRC20"
    }
  }
}

After:

{
  "order": {
    "cost": {
      "amount": "20",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "recipient": {
    "merchantBalance": {
      "currency": "USDC",
      "tokenStandard": "TRC20"
    }
  }
}

E-wallet Payer Data Support:

• Added walletData object to the payer field in the Create Order endpoint.
• Use this object to pass the payer's e-wallet details for providers that accept payments via digital wallets.
• Available fields (all optional): walletId, walletType, walletName, walletHolderName.

Added tokenStandard to cost for partial operations:

The tokenStandard field has been added to the cost object in the following endpoints, mirroring order.cost.tokenStandard for consistency across the order lifecycle:

• POST /order/capture — cost.tokenStandard
• POST /order/refund — cost.tokenStandard

P2P​

Added tokenStandard to cost:

• Added p2p.cost.tokenStandard to the Create P2P Transaction request. Optional.
• Should be provided for token-based cryptocurrencies when using crypto_currency_code in p2p.cost.currency; not needed for native cryptocurrencies or when using asset_code format.

Payouts​

Added tokenStandard to payout.cost:

• Added payout.cost.tokenStandard to the Create Payout Request endpoint. Optional. Should be provided for token-based cryptocurrencies when using crypto_currency_code in payout.cost.currency; not needed for native cryptocurrencies or when using asset_code format.
• The existing payout.cryptoTokenStandard field is unchanged.

Changelog​

Payment Methods​

New Instrument Type mobile_top_up:

• Added mobile_top_up to the list of supported values for instrumentType. This instrument type represents payments made by topping up a mobile phone number. See Payment and Payout Methods for details.
• Affected endpoints:
  • POST /order
  • GET /order/{shopId}/{orderNumber}
  • GET /shops/{shopId}/payment-methods
  • POST /payouts
  • GET /payouts/{shopId}/{payoutNumber}
  • GET /payouts/payout-methods/{shopId}
  • POST /payouts/fields

New Card Brands humo and uzcard:

• Added humo and uzcard to the list of supported card brands.
• Affected fields and endpoints:
  • paymentSystem in GET /order/{shopId}/{orderNumber} payment details
  • paymentSystem in GET /payouts/{shopId}/{payoutNumber} payout details

Changelog​

Orders​

Removed deprecated redirect entry mode:

• The redirect value was deprecated and has been removed from the entryMode enum.
• Affected endpoints:
  • POST /order
  • GET /order/{shopId}/{orderNumber}
  • GET /shops/{shopId}/payment-methods

Changelog​

Orders​

Bank Transfer Payer Data Support:

• Added bankTransferData object to the payer field in the Create Order endpoint.
• When creating an order with instrumentType = bank_transfer, merchants can now pass the payer's bank transfer details (such as bankCode, accountName, accountNumber, etc.) in payer.bankTransferData.
• This allows providing bank-related information for the payer upfront, reducing the need for manual entry on the payment page.
• Requires the company setting "Use customer data as payer information" to be enabled. This setting can be found in the Dashboard under Settings -> Company tab.

Need Action automatic resolution:

• Orders in need_action status caused by a provider response timeout can now be resolved automatically. If the provider's response is eventually received.
• See Order Status Model — Resolution.

Changelog​

Orders​

• Deprecated endpoint: POST /api/v1/order/reject is now deprecated. Use POST /api/v1/order/cancel instead. The reject endpoint will be removed in a future release.

Documentation Updates​

New Page: Customer and Payer Data​

Added a new documentation page — Customer and Payer Data — covering:

• How the system identifies customers (customerId → email + phone → new record)
• Merge rules when "Use customer data as payer information" is enabled for payments and payouts
• Payment and payout flow diagrams showing the data resolution logic
• Payment retry behavior for payer data

Changelog​

Deprecations​

• Order Status: The rejected order status has been removed.

API Updates - Orders and Payouts​

Shop Hosted Integration (DeepLink Support):

• Added deepLink property to the operationReference object in Order Retrieve Order Details, Payout Retrieve Payout Status responses and webhooks Order Callback and Payout Callback.
• This new field provides a URL for redirecting customers to mobile applications (e.g., banking apps) to complete payments or payouts, improving the user experience for instruction-based integrations.
• Updated H2H Integration for Instructions guide to include deepLink details and examples

Changelog​

Payment Methods​

Samsung Pay Support:

• Added samsung_pay to the list of supported values for entryMode in the Create Order and Retrieve Payment Methods endpoints.

Webhooks​

• Previously, the system sent a webhook with status failed when an order was not created because the Create Order endpoint returned a synchronous error (e.g., 412 Precondition Failed).
• Change: The system no longer sends a callback notification in these scenarios. If the order creation returns an error synchronously, no asynchronous webhook will be triggered.

Changelog​

Callbacks​

Signature Verification Logic Update:

We have updated the requirements for generating the control signature to support Unicode characters in callback payloads (e.g., in customer names).

When generating the signature on your side to compare with api-notification-sign, ensure that your JSON encoding preserves Unicode characters and does not escape slashes. For updated examples, please refer to the Configuring Callback documentation.

PHP: Add JSON_UNESCAPED_UNICODE to your json_encode flags.

$message = json_encode($phpInput, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

Python: Use ensure_ascii=False in json.dumps.

message = json.dumps(data, separators=(',', ':'), ensure_ascii=False)

Backward Compatibility:

We recommend applying this update to all integrations. It ensures correct signature verification for Unicode data and is fully backward compatible for ASCII-only payloads.

Changelog​

Crypto Wallets​

Removed Endpoints:

• The following CryptoWallet endpoints have been removed from the API:
  • POST /customers/crypto-wallet — Create Crypto Wallet for a Customer
  • GET /customers/{customerId}/crypto-wallet — Retrieve Customer's Crypto Wallets

Orders​

Customer and Payer Data Handling:

• Updated priority rules when both customer and payer objects are provided in the Create Order request. This behavior applies only when the company setting "Use customer data as payer information" is enabled:
  • Data from customer and payer objects will be merged
  • Fields from the payer object take priority over corresponding fields from customer
  • Missing fields in payer will be supplemented from customer data

Cryptocurrency Payments:

• Customer identification is now required for cryptocurrency payments (instrumentType: crypto_wallet). You must provide at least one of the following fields in the customer object:
  • customerId — to use an existing customer
  • email — to identify or create customer by email
  • phone — to identify or create customer by phone

Shop Hosted Integration:

• When using dataEntryMode: instruction with paymentPageDesign.format: shop_hosted, the payer object with required fields must be provided in the request. If payer data is insufficient, a validation error will be returned.
• Instruction parameters are returned in the operationReference object via webhook and Retrieve Order Details response.

Retrieve Order Details:

• The Retrieve Order Details response has been updated:
  • Added payer object to the payment items in the payments array.
  • Expanded instrumentType: crypto_wallet details (OrderPaymentDetailsCryptoWalletResponse) with:
    • recipientCryptoAddress: The cryptocurrency wallet address of the recipient.
    • recipientCryptoAddressMeta: Additional metadata for the recipient address.
    • senderCryptoAddressMeta: Additional metadata for the sender address.

Create Payout Request:

• The Create Payout Request response (and relevant structures) has been updated for instrumentType: crypto_wallet:
  • Added blockchain: Name of the blockchain.
  • Added tokenStandard: Token standard.
  • Added senderCryptoAddressMeta: Additional metadata for the sender address.
  • Added tronscanUrl: Direct URL to view transaction details.
  • Added amlRisk: Anti-Money Laundering risk level.

Documentation Updates​

Shop Hosted Integration​

The operationReference object structure in the H2H Integration for Instructions documentation has been updated.

Updated Structure:

{
  "operationReference": {
    "parameters": [
      {
        "label": "Reference",
        "value": "KT53386"
      },
      {
        "label": "Amount",
        "value": "10.00"
      },
      {
        "label": "Entity",
        "value": "db76f9cc-fbb0-4394-ac81-7b4fcfd6b2be"
      }
    ]
  }
}

Key Changes:

• type and metadata fields replaced with parameters array
• Parameter items now use label and value fields (previously id, type, value)
• The operationReference object has been moved to the payments array for orders and to the payoutTransactions array for payouts

See the Retrieve Order Details endpoint, Callback, Retrieve Payout Status endpoint, and Callback Payout documentation for the complete schema definition.

Antifraud Manual Review - reviewTimeout Field Correction​

The reviewTimeout field unit has been corrected from hours to minutes. The field accepts values from 1 to 1440 minutes (24 hours).

See the Antifraud Manual Review guide, Retrieve Order Details endpoint, and Retrieve Payout Details endpoint documentation.

Standardized Error Responses​

All API endpoints now include standardized error response codes documentation: