Enhanced Customer Management​

The Create New Customer and Retrieve Customer Information endpoints have been expanded with additional customer profile fields:

• affiliatedId: An optional identifier for customer. This field allows merchants to pass arbitrary values that will be stored in the customer record.
• billingAddress: Complete billing address information for customer profiles.
• birthDate: Customer's date of birth in ISO 8601 format (YYYY-MM-DD).

Cryptocurrency Payment Enhancements​

The Create Order endpoint now includes cryptocurrency payment support through the new cryptoPayment object:

• walletTokenStandard: Specifies the token standard for the customer's wallet cryptocurrency (e.g., TRC20, ERC-20, BEP-20). Required for token-based cryptocurrencies but not for native cryptocurrencies like BTC or ETH.
• accountCurrency: Configures the merchant account currency for cryptocurrency payments, including both the currency and its network token standard when applicable.
• The cryptoTokenStandard field has been removed from the order creation request, with this functionality now handled through the dedicated cryptoPayment object.

The Create Crypto Wallet endpoint has been updated:

• The tokenStandard field has been renamed to networkTokenStandart within the accountCurrency object for consistency.
• The accountCurrency field is now nullable.

Expanded Payment Method Support​

New transfer types are now available across multiple endpoints for enhanced regional payment coverage:

• rapipago: Support for Rapipago payment method in Argentina.
• pse: Support for PSE (Pagos Seguros en Línea) in Colombia.

These new transfer types have been added to:

• Create Order
• Retrieve Order Details
• Retrieve Payment Methods
• Retrieve Payout Methods
• Retrieve Required Payout Fields
• Create Payout Request
• Retrieve Payout Status

New payment entry modes for digital wallets:

• apple_pay: Apple Pay integration.
• google_pay: Google Pay integration.

Recurring Payments Configuration​

The Create Order endpoint's recurringPayments object has been refined:

• billingIntervalQuantity and intervalType are now required fields when setting up recurring subscriptions.
• The paymentCount field is now nullable, allowing for indefinite subscriptions.

Payout Enhancements​

The Create Payout Request endpoint has been updated with improved data organization:

• Removed the paymentData field from both recipient and sender objects.
• Added bankAccountUserId to the bankTransferData object for enhanced bank account identification.
• Introduced payoutChannel field in the payoutData object to specify the channel used for payouts.
• Personal data now includes an optional id field.

The Retrieve Required Payout Fields endpoint response has been streamlined:

• Removed paymentData from the available categories.

Modified Endpoints​

Payouts​

Retrieve required payout fields

• The request‑body property payoutSettings.shopId is now required (previously nullable).

Orders​

Create order

• paymentSettings.instrumentType now accepts the new enum value cash.
• For bank‑transfer payments, paymentSettings.transferType now supports the new enum value codi.

Retrieve order details

• payments[].instrumentType now accepts cash.
• payments[].paymentDetails now includes a new schema for cash payments.
• For bank‑transfer payments, payments[].transferType now supports codi.

Retrieve payment methods

• Query parameter instrumentTypes now supports cash.
• Response properties instrumentType, transferType, and transferTypes[] now include cash and codi.

Payouts​

Create payout request

• The request‑body property instrumentType now accepts cash.

Retrieve required payout fields

• instrumentType now accepts cash.
• payoutSettings.transferType now accepts codi.

Retrieve payout methods

• Query parameter instrumentTypes now supports cash.
• Query parameter transferTypes now supports codi.
• Response properties instrumentType, transferType, and transferTypes[] now include cash and codi.

Retrieve payout status

• payoutDetails.recipient.transferType now supports codi.
• payoutTransactions[].instrumentType now supports cash.

Orders​

Create order

• The request body now supports the customer.saveCard property, allowing customers to save their card for future use.
• The payer.cardData object now includes a savedCardId property for referencing previously saved cards.
• paymentSettings.redirectUrls now supports a pending URL for handling pending payment states.
• The transferType property now accepts a new enum value: clabe.

Retrieve order details

• The payments array in the response now includes a chargebacks property (replacing the previous chargeback property).
• The paymentDetails object for card payments now includes a savedCardId property.
• For bank transfers, the transferType property now supports the new clabe value.
• The paymentType property now supports the new enum value: saved_card_payment.

Retrieve payment methods

• The transferType and transferTypes properties in the response now support the clabe value.

Payouts​

Create payout request

• The request body now supports a redirectUrls property for handling payout redirections.

Retrieve required payout fields

• The payoutSettings.transferType property now supports the new clabe value.

Retrieve payout methods

• The transferTypes query parameter now supports the clabe value.

Retrieve payout status

• The transferType in payoutDetails.recipient object for bank transfers now supports the clabe transfer type.

Chargebacks​

Retrieve chargebacks

• The structure of the chargebackDetails property within the response has been significantly revised. chargebackDetails is now an array (previously an object).

Orders​

Extended customer Object:

• In the Create Order endpoint, the customer object now includes a new optional birthDate parameter. This field allows you to specify the customer’s date of birth for enhanced identification or compliance requirements.

Extended addressData Object:

• In the Create Order endpoint, the addressData object inside customer.details now includes a new optional address parameter. This field is intended to capture the address information, including house numbers, required for certain billing processes.

New bank_transfer TransferType:

For instrumentType == bank_transfer, we have introduced additional TransferTypes that can be used for European online banking solutions:

Payouts​

Removed Deprecated Endpoint:

• The previously supported endpoint /payouts/fields/{providerCode}/{instrumentType}/ has been completely removed from the system.

New street Parameter:

• In both the Retrieve Required Payout Fields response and the Create Payout Request request, a new street parameter has been added within addressData.
• This field is intended to capture only the name of the street for use in providers that require more granular address information during payout processing.

Orders​

New authorized Payment Status:

• The Retrieve Order Details response and the Order Status Callback now include a new possible status value, authorized, under data -> payments -> paymentStatus -> status.

Crypto Wallets​

New accountCurrency Object:

• In the body of the Create Crypto Wallet for a Customer endpoint, a new object called accountCurrency has been introduced.
• This is used to specify the merchant’s account currency (fiat or crypto). Some providers require an additional account currency parameter for settlement or balance denomination alongside the actual crypto wallet currency.

Extended Response Fields:

• In the Retrieve Customer's Crypto Wallets endpoint, data -> cryptoWallets now includes two new fields: accountCurrency and accountCurrencyTokenStandard.
• These fields allow you to view the configured merchant account currency and any relevant token standards (e.g., "ERC-20") in the wallet details.

Renamed Fields in Wallet Response:

• In the Retrieve Customer's Crypto Wallets endpoint, the existing walletAddress field is now called wallet, and cryptoCurrency is renamed to currency.

Orders and Payouts​

Validation for orderNumber and payoutNumber:

• New length constraints: orderNumber and payoutNumber now must be at least 3 characters and no more than 255 characters.
  • This impacts the Create Order endpoint (see the orderNumber field).
  • This impacts the Create Payout Request endpoint (see the payoutNumber field).

affiliatedId Object in customer

• Both Create Order and Create Payout Request now support a new optional metaData object within the customer object. This includes the optional affiliatedId field for passing arbitrary values used for custom routing. Changes have been introduced to this endpoint, but its full functionality will be available in upcoming releases.

Orders​

Customer Object Updates:

• In the Create Order endpoint, the firstName and lastName fields inside the customer object are now optional and may be null. This allows you to create orders without strictly requiring the customer’s name information.

Payment Page Language Parameter:

• A new optional language field is available under paymentPageDesign in the Create Order request:
  • Accepts an ISO 639-1 code (for example, "en" for English).
  • Unsupported languages will default to English.
  • If omitted, the payment page language will continue to be determined by the payer’s IP address.
  • Note: The parameter is accepted now, but actual language switching functionality will be activated in a future release.

Order Cancel and Refund Request Updates:

• The request body for the Cancel Order (in development) endpoint has been updated. The endpoint’s functionality remains under development and will be fully available in a future release.
• The request body for the Refund Order (in development) endpoint has also been updated. Similar to cancellation, its functionality is still in progress and not yet fully operational.

New payer Object in Create Order:

• In the Create Order endpoint, a payer object has been added. When instrumentType = card and dataEntryMode = h2h, you can send card data directly. This removes the need for the payer to manually enter card information on the payment page. Changes have been introduced to this endpoint, but its full functionality will be available in upcoming releases.

Payouts​

Payout Endpoints Enhancements:

• In the Create Payout Request and Retrieve Required Payout Fields endpoints, new object cryptoWalletData has been added to the recipient and sender arrays.

Orders and Payouts​

• This change allows for multiple transferType selections within a single payment method.
  When instrumentType is bank_transfer, please rely on transferTypes. transferType remains for backward compatibility but will be removed in future releases:

  • If only one transfer type is added for payment method for the shop, it will appear in transferType and in transferTypes.
  • If multiple transfer types are added for payment method for the shop, transferType will be null and you should use transferTypes.

• Added new TransferType values: imps, upi_p2p, upi_fast_vip. For more details, see Payment and Payout Methods.

Orders​

• Introduced two new endpoints for supporting cryptocurrency payment orders. For usage guidelines, refer to API: Request examples:

  • Create Crypto Wallet for a Customer
  • Retrieve Customer's Crypto Wallets

• Extended paymentType to include the new value order_by_webhook in the Retrieve Order Details endpoint and the Callback. This value is required for crypto acceptance operations such as Create Crypto Wallet for a Customer.

General​

• Added the statusReason field in the following responses:

  • Retrieve Order Details and Callback (for order status).
  • Retrieve Payout Status and Callback Payout (for payout status).

  This field provides a short explanation for the current status (e.g., need_action, failed, or cancelled).
  It may contain system-generated messages or payment provider error details.
  This field remains empty for statuses like completed or in_progress.

• Extended transferType options to include pesalink for bank transfers. This broadens the range of available methods.

General​

• Renamed parameter in the Retrieve Customer Information endpoint from customerIds[] to customerIds.

Payouts​

• Added the serialNumber field to voucher payouts in the responses from Retrieve Payout Status and Callback Payout. This is accomplished by introducing a new schema in payoutDetails (data -> payments -> paymentDetails) specifically for voucher support.
• Added the new fields serialNumber and pin for voucher support in orders in the Retrieve Order Details endpoint and Callback, via a new schema in paymentDetails.
• Expanded the paymentSystem enum within the paymentDetails object to include maestro:
  • In the Retrieve Order Details endpoint and Callback.
  • Also added maestro in the payoutDetails object for Retrieve Payout Status and Callback Payout.
• Extended transferType options to include additional methods, such as wise and n26, broadening the range of available payout methods.

API Updates​

To support new integrations, we have introduced a new field documentNumber in the response for the Retrieve Required Payout Fields endpoint (recipient/sender -> documentData -> documentNumber).

Orders​

To improve the payment experience and streamline the checkout process, we have updated how customer information is handled in our API.

• New Feature: Introduced a details object within the customer object in the Create Order endpoint. Merchants can now provide additional customer details, specifically address information, which can be used to pre-fill the payer's information on the payment page.
  To learn more about optimizing the payment page experience, see Optimize the Payment Page Experience.

  • New Fields in details.addressData:
    • city: City name of the customer/payer.
    • countryCode: ISO 3166-1 alpha-2 country code representing the customer's/payer's country.
    • state: State or province name.
    • zipCode: Postal code.

• Update: Expanded descriptions of existing transferType options to include:

  • fpx: Financial Process Exchange, an online payment gateway for real-time bank transfers.
  • trustly: Direct bank transfer service allowing payments without using cards.

Cryptocurrency​

As we continue to implement support for cryptocurrency payments/payouts, several updates have been made. All changes are backward-compatible, and additional enhancements are planned for future releases.

• Update: Modified the rules for specifying cryptoTokenStandard and currency in the Create Order and Create Payout Request endpoints.

• Update: Expanded the responses of the Retrieve Order Details endpoint under payments -> paymentDetails with new fields for instrumentType=crypto_wallet:

  • senderCryptoAddress: The sender's cryptocurrency wallet address.
  • txHash: The transaction hash of the cryptocurrency payment.

• Update: Expanded the responses of the Retrieve Payout Status endpoint for instrumentType=crypto_wallet:

  • Under data -> payoutDetails -> sender:
    • senderCryptoAddress: The sender's cryptocurrency wallet address.
    • txHash: The transaction hash of the cryptocurrency payout.
  • Under data -> payoutDetails -> recipient:
    • recipientCryptoAddress: The recipient's cryptocurrency wallet address.
    • recipientCryptoAddressMeta: Additional metadata about the recipient's crypto address, such as network or tag.
    • txHash: The transaction hash of the cryptocurrency payout.

Webhooks​

• Update: Adjusted the Order Status Webhook to align with the documentation. The order of fields within data -> payments -> paymentDetails has been corrected to ensure proper webhook signature formation. The updated field order is as follows:

  Before:

  "paymentDetails": {
    "paymentSystem": "visa",
    "maskedCardNumber": "123456******1234",
    "rrn": "rrn583743856734",
    "authCode": "auth94753457343"
  }
  

  After:

  "paymentDetails": {
    "paymentSystem": "visa",
    "authCode": "auth94753457343",
    "rrn": "rrn583743856734",
    "maskedCardNumber": "123456******1234"
  }
  

• Update: Modified the Payout Status Webhook to match the documentation. The order of fields within data has been corrected for proper webhook signature formation. The updated field order is:

  Before:

  {
    "data": {
      "id": 54222,
      "shopId": 123,
      "payoutNumber": "56573FDFVFDBWF",
      "payoutStatus": "in_progress",
      "purpose": "string"
    }
  }
  

  After:

  {
    "data": {
      "shopId": 123,
      "id": 54222,
      "payoutStatus": "in_progress",
      "payoutNumber": "56573FDFVFDBWF",
      "purpose": "string"
    }
  }
  

All other functionalities remain unchanged.

Upcoming Features​

• New Endpoints in Development: Introduced two new endpoints—Create New Customer and Retrieve Customer Information—which are essential for the upcoming support of cryptocurrency payments and payouts. These endpoints are currently under development and are expected to become operational in the next release.

General​

• Update: Additional dataEntryModes options have been introduced, including instruction, iframe, and html, providing flexible methods for customer data entry in the Retrieve Payment Methods and Create Order endpoints.
• Update: Expanded transferType options for payouts, adding the following new methods:
  • sbp - Russian System for Fast Payments
  • open_finance - Open banking options
  • virtual_account - Virtual account payments
  • spei - Mexican interbank electronic payments (SPEI)
  • vietqr - Vietnamese QR code payments
  • paysafecard - Prepaid voucher service
  • multibanco - Portuguese bank transfer method
  • bancontact - Belgian payment method
  • blik - Polish mobile payment system
  • p24 - Przelewy24, a Polish online payment system
  • rapidtransfer - Rapid Transfer for bank payments
  • upi - India’s Unified Payments Interface
  • thb_qr - Thai QR payments
  • sberbank - Sberbank Online for Russian transfers
  • account2card - Direct bank-to-card transfer

Cryptocurrency​

Initial support for cryptocurrency transactions has begun, but implementation is still ongoing. Below are the changes introduced so far, with further updates planned for upcoming releases. All modifications are backward-compatible.

• Update: A new cryptoTokenStandard parameter has been added to the order object in the Create Order endpoint and to the payout in the Create Payout Request , required if the currency is set to a cryptocurrency. This allows specifying the blockchain standard for crypto payments, such as ERC20.
• Update: The amount and currency fields in order -> cost object were modified to support cryptocurrency transactions, including the addition of decimal precision requirements for crypto and the need to specify cryptoTokenStandard in the Create Order endpoint and in payout -> cost in the Create Payout Request .
• Update: The customer data container now allows customer details (firstName, lastName, middleName, phone, and email) from the order request to be automatically used on the payment page without re-entry, governed by the Use customer data as payer information setting. This behavior applies across all orders created using the Create Order endpoint.

Payouts​

• New fields: Added ipAddress, beneficiaryName, and beneficiarySurname to RecipientPersonalData for enhanced payer identification in the Create Payout Request endpoint.
• Update: Added RUT to RecipientDocuments to support Chilean taxpayer identification in the Create Payout Request endpoint.

General​

• New feature: A new status need_action has been added to the status model for both payments and payouts. This status indicates that further action is required to complete the transaction. More details can be found in the Order Actions and Conditions and Payout Scenarios sections.

Orders​

• New feature: A new provider object has been added to the payments array in the response of the Retrieve Order Details endpoint and the Order Status Callback, which includes the payment provider's code.

Payouts​

• New feature: A new status object has been added to the payoutTransactions array in both the Retrieve Payout Status and Payout Callback endpoints. This object contains:

  • status: The current state of the payout, with possible values: in_progress, completed, cancelled, failed, and the new need_action.
  • details: Nullable object providing additional error details if the payout fails, including:
    • errorId: Unique error identifier.
    • providerMessage: Error message from the payment provider.
    • code: Internal error code for categorizing the error.

• New feature: A new status object has been added to the payoutTransactions array in both the Retrieve Payout Status and Payout Callback endpoints to enhance payout status reporting. It includes the current state of the payout and detailed error information if the payout fails.

Payouts​

• Bug fix: The Callback Payout now adheres to the documentation correctly. Previously, the callback was not matching the described behavior in the docs.
• Bug fix: Resolved an issue where the Create Payout Request was returning an error for a valid request in some scenarios.

Orders​

• Update: The default cancellation time for orders has been reduced to 15 minutes. Refer to the timeLimit parameter in the Create Order endpoint for more details.

  • If no active transaction is initiated by the payer within the first 15 minutes, the order will be automatically cancelled with the status cancelled.
  • If a transaction is initiated within this window, the order will remain active for an additional week. However, if a final successful status is not received from the payment provider within this extended period, the order will be cancelled.

• Bug fix: Fixed an issue where customer details in a previous order were sometimes overwritten by updated data for the same customerId from a new order. Now, customer details always reflect the information provided at the time of the order's creation, even if they were changed in subsequent orders for the same customerId. This applies to both the Retrieve Order Details endpoint and the Callback.

Orders​

Enhancements​

• New Parameter: Added transactionId field to the payments object in both the Retrieve Order Details API response and the Order Status Callback. This new field allows merchants to track the unique identifier for each transaction associated with an order, improving traceability and reconciliation of payments.

Payouts​

Enhancements​

• Time-To-Live (TTL): For all payouts, a TTL of 1 week has been introduced, starting from the moment the payout is created. For more details, please refer to the Create Payout Request Documentation.

Orders​

Enhancements​

• New Feature: Introduced the ability to assign and use aliases for payment configurations. Merchants can now specify a paymentSettingsAlias in the order creation endpoint to control which payment configuration is used for processing the order. This feature is particularly useful for merchants who need to manage multiple configurations with the same provider. To learn more about configuring and using aliases, please refer to the Alias Documentation.

Payouts​

Enhancements​

• New Feature: Similar to the enhancements for orders, the alias feature has also been extended to payouts. Merchants can now specify a paymentSettingsAlias in the payout creation endpoint. This allows for precise control over which payment configuration is used for payouts. To learn more about configuring and using aliases, please refer to the Alias Documentation.

Bug Fixes​

Fix: Resolved an issue where payouts could not be created if the DataEntryMode was not specified during payout creation, when only one DataEntryMode was available for the payment method. Now, the DataEntryMode is only required when there are multiple DataEntryMode available in the Retrieve Payout Methods endpoint response. If only one DataEntryMode is provided, it will be automatically applied, and no manual input is necessary.

Payouts​

Enhancements​

• Update: The response structure of the Retrieve Payout Status endpoint has been expanded. This includes additional fields that provide more detailed information about the payout process. Backward compatibility with the previous response format has been maintained, ensuring existing integrations continue to function without disruption.

• Update: New values have been added to the transferType. The transferType can now include the following values:

  • virtual_account
  • khipu
  • giropay
  • eps
  • open_finance

Breaking Changes​