Guides
Start typing to search…

FAQ

This page will help you find quick answers and solutions to common questions about integrating with our services.

⚠️

Important

This section is under active development, its content and structure are subject to change.

Introduction

Welcome to the FAQ section of the Merchant API Hub, designed to address common questions and provide quick solutions for merchants integrating with our services. Organized by topic, this section covers a wide range of inquiries, from initial setup and payment processing to troubleshooting.

Please note that the FAQ section is under active development, and its structure and contents are subject to change.

Currently, the FAQ section covers questions in the following categories:

Payment statuses and error codes

This subsection provides quick answers to common issues by detailing API response codes and payment statuses.

How do I check the status of a payment?

Click to see the solution To check the status of a payment, you need to use the Deal info method in our Merchant API. However, we recommend subscribing to a webhook for real-time status updates.

What does the "Expired" status mean?

Click to see the solution

This status indicates that the transaction was not processed within the specified time-to-live (TTL), which is usually 24 hours. Note that "Expired" is not a final status, as the transaction can still transition to any final status.

Why is "Completed" considered a successful payment status?

Click to see the solution "Completed" status indicates a successful payment.

What fields are included in the response to a payment status request?

Click to see the solution For payment status processing, it is recommended to use webhooks. The primary fields to focus on are:

  • \_id
  • status.name

What should I do if I receive error status codes (4XX or 5XX) during transactions?

Click to see the solution
  • 5XX errors (on your side): These errors occur on the merchant's side, and you should not retry the request but send the transaction through cascading processes.
  • 429 errors (rate limit or account block): Retry the request after some time.
  • 4XX errors: Send the transaction through cascading processes.
  • 5XX errors (on our side): Send the transaction through cascading processes.

Should I request the status of a transaction if I receive 4xx or 5xx status codes in response?

Click to see the solution If you receive a 4xx or 5xx status code, the transaction will not be created. Additionally, the invoiceId parameter is idempotent, meaning you cannot create multiple requests with the same invoiceId, which helps prevent duplicate payments.

Why does a deal have a status of "new" in production but "queued" in the sandbox?

Click to see the solution The "new" status appears in production when a trader matching the currency is available and displays the deal with a status of "new." The trader must manually accept the deal.

Should I consider the payment as "not created" if I receive a "VALIDATION_ERROR" with the message "Validation parameters error"?

Click to see the solution Yes, the payment is considered created only if an ID is returned. Transactions with HTTP status codes 4xx or 5xx indicate that the payment was not created.

Why do I receive an "ERROR_CREDENTIALS_NOT_FOUND" message when requesting payment credentials?

Click to see the solution This behavior is normal. It takes some time to retrieve the payment credentials, sometimes up to a second. The flow is to create the deal first and then continue querying the credentials until you receive a 200 status.

Why am I getting a 401 ("Unauthorized") error when querying a deal status?

Click to see the solution The 401 error indicates that you need to add the "reports" role to the account. Ensure the account has the necessary permissions.

Why do I get an "ERROR_ACCESS_TOKEN_INVALID" error when sending a token refresh request?

Click to see the solution This error typically means that you did not pass a token in the request. During a token refresh, the lifespan of the current access token is not checked, so ensure you are passing the correct token.

Payment setup and configuration

This subsection provides quick answers and guidance on setting up and customizing payment options.

How do I create a payment?

Click to see the solution To create a payment, use the Create deposit deal method. Here are some key parameters:

  • invoiceId (optional): Your unique payment ID for quick identification.
  • clientId (required): A unique, anonymized client ID used for traffic segmentation, which affects the quality of the channel.
  • bankId (optional): Required in some countries to specify the requesting bank's details.
  • trusted: Indicates the quality of traffic (primary/secondary).

Is it mandatory to provide the account_owner field for payments via the Faster Payments System (FPS/СБП)?

Click to see the solution The account_owner field is required for recipient validation. If you cannot provide it, you'll need to agree on a refusal flow with us.

Do I need to include the x-digest parameter in the request headers for RSA-marked requests?

Click to see the solution Yes, you should include the x-digest parameter in the headers for RSA-marked requests.

How do I provide a callback URL in the request?

Click to see the solution The callback URL is configured in the project settings within the merchant's personal account dashboard.

How should I construct the signature string for an FPS payout request?

Click to see the solution To construct the signature string for an FPS payout request:

  1. Unwind the fields: 
    [  
  { "amount": 1000 },  
  { "currencyTo": "USD" },  
  { "baseCurrency": "fiat" },  
  { "feesStrategy": "add" },  
  { "account_number": "+91 (234) 333-555-12" },  
  { "account_owner": "Hello Name" },  
  { "bankId": "100000000111" },  
  { "type": "fps" }  
]
  2. Then sort the fields alphabetically: 
    [  
  { "account_number": "+91 (234) 333-555-12" },  
  { "account_owner": "Hello Name" },  
  { "amount": 1000 },  
  { "bankId": "100000000111" },  
  { "baseCurrency": "fiat" },  
  { "currencyTo": "USD" },  
  { "feesStrategy": "add" },  
  { "type": "fps" }  
]
  3. After that, join the values into a single string: 
    +91 (234) 333-555-12Hello Name1000100000000111fiatUSDaddfps

Can I send the NSPK bank ID instead of the bankId parameter?

Click to see the solution Yes, you can send the NSPK bank ID instead of bankId.

Do I still need to generate x-digest and x-signature for the Create deposit deal request?

Click to see the solution No, you do not need to generate these for the deposit request.

What values should I specify for the parameters used in the RSA requests?

Click to see the solution
  • trusted: This marks secondary traffic.
  • ttl: The time period during which the transaction remains valid (how long we will attempt the transaction, e.g., if there were insufficient funds at the time of creation).
  • account_iban: The IBAN of the account.
  • fiatLiquidity: Used for fiat liquidity coverage, applicable in special cases.
  • feesStrategy: Specifies who pays the commission: The client or the merchant.

Is a dot (.) used as the decimal separator for amounts?

Click to see the solution Yes, use a dot (.) as the decimal separator for amounts.

What does the trusted field represent, and should I set it to true or false?

Click to see the solution The trusted field indicates the quality of traffic (primary or secondary). If you are using primary traffic, you don't need to set this field.

Should recipient.type be set to phone for FPS payouts, and is the phone parameter required?

Click to see the solution Please verify your integration for FPS payouts. The recipient.type should be set to fps instead of phone. While phone is still an acceptable parameter to use, it prevents the trader from seeing the recipient's bank.

Authentication and key management

This subsection provides essential information on managing access keys and ensuring secure authentication practices.

Testing and sandbox environment

This subsection offers guidance on using the sandbox environment for safe and effective testing of API functionalities.

Transaction details and parameters

This subsection explains the specific transaction fields and parameters needed to streamline payment processing.

Feature and service availability

This subsection outlines the supported features and services to help optimize integration planning.

Examples and sample requests

This subsection provides practical request examples to assist with implementing and testing API calls effectively.

Updated 8 months ago