How to check available payment systems

Overview

Before creating a payment operation in Monetix, you can request which card payment systems (MPS) are available for the operation. This section explains how to submit a request for available payment systems, process the response, and extract information about available payment systems and operation limits. Examples of requests and responses are also provided.

You can request the following:

  • all the payment systems available in your project
  • payment systems available for operations with specific currency
  • payment systems available for operations with specific amount and currency

If your request does not include amount or currency, Monetix returns all the payment systems available in your project.

If your request includes payment.currency or payment.currency and payment.amount, Monetix returns only the payment systems that support operations with the specified parameters.

The request for available payment systems is executed synchronously. In other words, it completes within a single HTTP session, and Monetix responds to a well-formed request with HTTP response code 200 that contains available payment systems.

If your request is incorrect or issues occur while receiving or processing it, the response contains the following:

  • HTTP response code different from 200
  • request processing status error
  • description of the detected error

For more information about HTTP response codes, see Integration procedure. For more information about error codes used in the payment platform, see Operation statuses and response codes.

Request

Requests for available payment systems use the standard request format described in Integration procedure. The following information is required to create and send the request.

HTTP method POST
Request body format JSON
API endpoint
  • /v2/info/card/payin/list—for pay-in
  • /v2/info/card/payout/list—for payout
Full API endpoint specification /v2/info/card/{transactionType}/list
Table 1. Basic request parameters for all the available payment systems
Object/Parameter Description

general
object
required

project_id
integer
strictly required

 Project identifier obtained from Monetix during integration

signature
string
strictly required

 Signature created after you specify all the required parameters. For more information about signature generation, Signature generation and verification.

payment
object
optional

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 payment.currency parameter to get payment methods available for the amount and currency you specify in the request.

Example: 10.00 USD must be sent as 1000

currency
string
optional

 Code of the payment currency in the ISO-4217 alpha-3 format.

Add this parameter to the request to get payment methods available for this currency.

If the payment.amount parameter is provided, the payment.currency parameter is required.

Example: USD

Example request for all the available payment systems

The following example shows a request for all the payment systems available in the project and the corresponding response returned by Monetix.

Figure 1. Example request for all the available payment systems
{
    "general":{
       "project_id":50,
       "signature":"qflDO7yiPKCFTyqCAaT+...yf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}
Figure 2. Example response with all the available payment systems

The response contains the following:

  • 200 — response code indicating that the request was successfully accepted
  • available_ips_list — array of available card payment systems
  • limits — operation limits for the corresponding payment system. Each object in this array contains limits for a specific currency
HTTP/1.1 200 OK                          // Response status
...                                               // Header fields
{
  "available_ips_list": [
    {
      "name": "visa",                          // Card payment system name
      "limits": [
        {
          "currency": "USD",                   // Operation currency
          "min_amount": 1000,                  // Minimum operation amount
          "max_amount": 400000                 // Maximum operation amount
        },
        {
          "currency": "KZT"                    // Operation currency
        }
      ]
    },
    {
      "name": "maestro",
      "limits": [
        {
          "currency": "USD",
          "max_amount": 47000
        }
      ]
    },
    {
      "name": "mastercard",
      "limits": [
        {
          "currency": "USD",
          "min_amount": 500
        }
      ]
    }
  ]
}

Example request for all the available payment systems by currency

The following example shows a request where the operation currency is specified and the corresponding response returned by Monetix. The response includes only the payment systems that support transactions in the specified currency.

Figure 3. Example: Request body for all the available payment systems by currency
{
  "general": {
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+...yf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
  },
  "payment": {
    "currency": "USD"
  }
}
Figure 4. Example: Response with all the available payment systems by currency

The response contains the following:

  • 200 — response code indicating that the request was successfully accepted
  • available_ips_list — array of available card payment systems
  • limits — operation limits for the corresponding payment system. Each object in this array contains limits for a specific currency
HTTP/1.1 200 OK                          // Response status
...                                               // Header fields
{
  "available_ips_list": [
    {
      "name": "visa",                          // Card payment system name
      "limits": [
        {
          "currency": "USD"                    // Operation currency
        }
      ]
    }
  ]
}

Example request for all the available payment systems by amount and currency

The following example shows a request where the operation amount and currency are specified and the corresponding response returned by Monetix. The response contains only the payment systems that support operations with the specified parameters.

Figure 5. Example: Request body for all the available payment systems by amount and currency
{
  "general": {
    "project_id": 50,
    "signature": "qflDO7yiPKCFTyqCAaT+...yf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  }
}
Figure 6. Example: Response with all the available payment systems by amount and currency

The response contains the following:

  • 200 — response code indicating that the request was successfully accepted
  • available_ips_list — array of available card payment systems
  • limits — operation limits for the corresponding payment system. Each object in this array contains limits for a specific currency
HTTP/1.1 200 OK                          // Response status
...                                               // Header fields 
{
  "available_ips_list": [
    {
      "name": "visa",                          // Card payment system name
      "limits": [
        {
          "currency": "USD",                   // Operation currency
          "min_amount": 1000,                  // Minimum operation amount
          "max_amount": 400000                 // Maximum operation amount
        }
      ]
    },
    {
      "name": "maestro",
      "limits": [
        {
          "currency": "USD",
          "max_amount": 47000
        }
      ]
    },
    {
      "name": "mastercard",
      "limits": [
        {
          "currency": "USD",
          "min_amount": 500
        }
      ]
    }
  ]
}

Synchronous response

Responses to requests for all the available payment systems follow the standard response format described in Integration procedure.

A response to a successfully processed request contains a status line that includes the protocol version, for example HTTP/1.1, response code, and reason phrase, for example 200 OK. The response body contains the following:

  • available card payment systems
  • currencies supported for each payment system
  • operation limits for the corresponding payment systems (if configured)

The following section provides an example of an error response returned when the request cannot be processed.

Example: Error response to request

The following example shows a response to an incorrectly formed request where a required parameter is missing. Such an error may occur in the following cases:

  • the request does not match the expected structure
  • parameter payment.amount is passed but parameter payment.currency is not passed
  • the request signature is incorrect

The following is an example of a response to a malformed request that lacks required parameters. The response contains the following:

  • 400 Bad Request—response code with the cause description in response status line
  • error—status of the payment status request
  • 2004 and Required field not provided—error code and its description indicating that some parameters are missing from the request
Figure 7. Sample response to incorrect request 
HTTP/1.1 400 Bad Request                     // Response status line
            ...                                      // Header fields
{
   "status":"error",                             // Request processing status
   "code":"2004",                                // Request status code
   "message":"Required field not provided"       // Code explanation
}

Related links