Checking payment methods availability

The Monetix payment platform provides you with a variety of payment methods your customer can make a payment with. Although, sometimes some payment methods can be unavailable for payment processing because, for example, the payment amount your customer wants to pay or receive doesn't fit the payment amount limits allowed for the payment method or if the payment method itself is currently out of service.

You can check what payment methods are currently available to perform a payment with before you display them to your customer. It can help you avoid a potential payment decline if the payment amount is larger or smaller than the amount limit allowed for the payment method or if the payment method is temporarily not working.

To check payment methods availability, send a request to the Monetix payment platform by using the Gate API. See the information below to learn some details about how to send such a request and what data you will receive in the response.

Request

Here is some information that you need to create a request for checking payment methods availability.


HTTP request method	POST
Request body format	JSON
API endpoint	/v2/info/available_methods_for_merchant/list

Table 1. Request for checking payment methods availability
Object/Parameter		Description
project_id integer strictly required		Project ID you obtained from Monetix when integrating. Example: `123`
directions array strictly required		Pass in this array: `payin`—to get the list of available payment methods available for purchase `payout`—to get the list of available payment methods available for payout Example: `payin`
currency string optional		Code of the payment currency in the ISO-4217 alpha-3 format. Add this parameter to the request to get the list of payment methods available for this currency. Example: `USD`
amount integer optional		Payment amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes. Pass this parameter in the request together with the currency parameter to get the list of payment methods available for the amount and currency you specify in the request. Example: 10.00 `USD` must be sent as `1000`
show_unavailable_methods_by_rules boolean optional		Parameter that you can add to the request to also get a list of unavailable payment methods. If you add this parameter with the `true` value to your request, the response will contain arrays with payment methods unavailable because of: the payment method's operation schedule. The array will contain information about when the payment method resumes its work. the request amount being larger or smaller than the amount limit allowed for the payment method. The array will contain information about the payment method's amount limits. To receive a response with this information, you should also add the currency and amount parameters to your request. Example: `true`
is_enable_check_by_trusted_pm_user_rules boolean optional		Parameter that you can add to the request to get a response containing a list of payment methods to be shown to a trusted customer. If you add this parameter with the `true` value to your request, the payment platform will check whether a customer making a payment is a trusted one and, depending on the result, will send you a response containing a relevant list of payment methods. Pass this parameter in the request together with the customer_id parameter to get the list of payment methods available for a particular customer. Example: `true`
customer object optional	id string optional	Unique ID of the customer within your project. Pass this parameter in the request together with the is_enable_check_by_trusted_pm_user_rules parameter to get the list of payment methods available for a particular customer. Example: `customer_123`
payment_method string optional		Code of the payment method which availability you want to check. Use this parameter in the request if you want to check availability of a particular payment method. Parameter code is listed in the method parameter in the callback. Example: `example_method`
signature string strictly required		Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

Here is an example of a basic minimum of parameters that you need to add to the request for checking payment methods availability. The response to such a request will contain information about the available payment methods relevant to the project specified in the request.

Figure 1. Example of the data from a request for checking payment methods availability

 {
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

The following is an example of request parameters to check the availability of one particular payment method. The response to such a request will contain information about the payment method specified in the request.

Figure 2. Example of the data from a request for checking the availability of one particular payment method

{
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "payment_method": "example_method",
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

The example below has additional parameters in the request. The response to such a request will contain information about available payment methods, as well as the methods that are currently unavailable because of their operation schedule or the request amount not corresponding to the payment methods' amount limit. Moreover, the list of payment methods sent in the response will vary depending on whether the customer making a payment is a trusted one or not.

Figure 3. Example of the data from a request for checking payment methods availability containing additional parameters

{
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "currency": "RUB",
   "amount": 100000,
   "show_unavailable_methods_by_rules": true,
   "is_enable_check_by_trusted_pm_user_rules": true,
   "customer": {
      "id": "123"
   },
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

Response

The Monetix payment platform sends a response to the request for checking payment methods availability synchronously, i.e. within the same HTTP session. If your request is built correctly, the payment platform will respond with the HTTP 200 OK status code to it and the response will contain information about the payment methods available to perform a payment with.

Here is an example of the data that you can get in the response to your request for checking payment methods availability.

{
   "available_payment_methods_by_trusted_user_rules": {
      "RUB": [
         {
            "title": "method_1",
            "direction": "payin"
         },
         {
            "title": "method_2",
            "direction": "payin"
         }
      ]
   },
   "available_payment_methods": {
      "RUB": [
         {
            "title": "method_3",
            "direction": "payin",
            "limits": {
               "min_amount": 10000,
               "max_amount": 1000000
            }
         },
         {
            "title": "method_4",
            "direction": "payin",
            "limits": {
               "min_amount": 90000,
               "max_amount": 1000000
            }
         }
      ],
      "USD": [
         {
            "title": "method_5",
            "direction": "payin",
            "limits": {
               "min_amount": 10000,
               "max_amount": 1000000
            }
         }
      ]
   },
   "unavailable_payment_methods_by_limits": {
      "PHP": [
         {
            "title": "method_6",
            "direction": "payin",
            "min_amount": 10000,
            "max_amount": 560000,
            "currency": "PHP"
         }
      ]
   },
   "unavailable_payment_methods_by_schedule": {
      "PHP": [
         {
            "title": "method_7",
            "direction": "payin",
            "will_be_available": "13/10/2022 18:30 GMT+03:00"
         }
      ],
      "USD": [
         {
            "title": "method_8",
            "direction": "payin",
            "will_be_available": "11/11/2022 12:00 GMT +03:00"
         }
      ]
   }
}

If your request is incorrect or the payment platform can't process it, the response will contain:

the HTTP status code different from 200 OK
error request processing status
the description of the error

Listed below are the HTTP status codes that you can get in the response to the request for checking payment methods availability.

Table 2. Possible response codes
Code	Description
`200`	Success. The response contains information about available payment methods and their amount limits
`400`	Used in several cases: The request lacks some of the required parameters. Correct the request The payment method is not found. Make sure you sent the correct payment method's code and currency in your request
`403`	The request is prohibited due to the lack of permits, e.g. because it was sent from the IP address which is not included in the allowed IPs list. Contact the technical support team
`422`	Invalid JSON data. Correct the request
`500`	Internal server error. Resend the request