Skip to main content
POST
/
invoice
/
hold
Funds hold (two-stage payments)
curl --request POST \
  --url https://api.m4solutions.io/gateway/v1/invoice/hold \
  --header 'Content-Type: application/json' \
  --data '
{
  "shop_id": 1520,
  "shop_order_id": "5b0efa8a-153b-4421-abac-2aba4d772a86",
  "amount": "6320.91",
  "currency": 840,
  "payway": "card_payway_usd",
  "client_ip": "192.168.1.1",
  "description": "Payment for shop_id=1520",
  "failed_url": "https://your-domain.com/status/failed/",
  "success_url": "https://your-domain.com/status/success/",
  "callback_url": "https://your-domain.com/status/callback/",
  "callback_rejected_url": "https://your-domain.com/status/rejected/",
  "expires_at": "2026-06-01T00:00:00Z",
  "issue_payment_token": false,
  "client_info": {
    "browser_accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
    "browser_java_enabled": false,
    "browser_javascript_enabled": true,
    "browser_language": "en",
    "browser_color_depth": "24",
    "browser_screen_height": "800",
    "browser_screen_width": "480",
    "browser_tz": "-120",
    "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Safari/605.1.15",
    "challenge_window_size": "05"
  }
}
'
{
  "result": true,
  "message": "Ok",
  "error_code": 0,
  "data": {
    "data": {
      "MD": "38e3244e2bcc4ed7a29aaa886a0e5374",
      "PaReq": "YPhfxL294rkdSCu7zBd6yArmgEuNhyuhCC6UNeNoql9OmgYbGcAQHkNxwZ6x0j2kLdoGytuJ9GfwxxkGLzZp5VdlQfhDd5QSK9XE68IrmgBJ1DxSsozMvGC9zGAxm2rDYqcA5HYuCQ66ocOw7P5sKQZphxm2DqoYBwji9zInFRIaTabC4UXzCjWbWT5NNpmz0ULXiOBmX6JB9BpP85UCrwWPC8Ee97gX7KRyOfZoe5Z65aKF7WLNFS5L3VffcV0YVyLKe2dXgrs3fACGrVM7dZmDFB7NiJL0yqgv5oYPjDSniZAkrlbShjILNLspVdzLwRKygvLOfEhhKvqmnoOTkNw4qfvgj4inrHnR3EcO3CozcdFh6T23sA7uP7LLZ3cHfAayfw9VpssdfeKorwajz2XdOOIrl45cXKnNLVEivyFbbUJF8wUq8bkkZXyTQGCKhqB819w2MuFu",
      "TermUrl": "https://card-api-test.example.com/v1/invoice/finish3ds/38e3244e2bcc4ed7a29aaa886a0e5374"
    },
    "id": 340198,
    "method": "POST",
    "url": "https://example.checkout.com/form/",
    "payment_token": {
      "token": "980fba62-94d9-4489-bf4c-75b43eecf134",
      "status": "SUCCESS",
      "expires_at": "2026-10-21T16:48:22",
      "account": "412103XXXXXX7701",
      "card_info": {
        "issuing_country": "GBR",
        "issuing_bank": "Example Bank",
        "payment_system": "VISA",
        "funding_source": "DEBIT",
        "payment_system_product": "GOLD"
      }
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.m4psp.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
sign
string
requestBody
required

Every API request must be signed so that we can identify your account.

The signature is transferred in the request body through the sign parameter, for example:

{
    "shop_id": 1520,
    "shop_order_id" : "5b0efa8a-153b-4421-abac-2aba4d772a86",
    "amout": "6320.91",
    "currency": 840,
    "payway": "card_invoice_usd",
    "description": "Payment for shop_id=1520",
    "sign": "77a6f7a30876d480d4e771d08cb83800dd5cb874664c77e515ffc052b20293c6"
}
All further request examples do not include the "sign" parameter, nevertheless your real requests must include it in the request body where required.

Signature line is generated according to the following algorithm: all request parameters involved in signature generation are ordered in the alphabetical order of keys, the values are concatenated with a colon (":") and the account secret key is added at the end (without the: sign), a sha256 hash is generated from the resulting line and its hex representation is passed in the sign request parameter.

Example of signature generation for a method invoice/create:

  1. Determining the list of parameters. It looks as follows for the method in consideration:

Fields involved in request signature generation:

  • shop_id
  • shop_order_id
  • amount
  • currency
  • payway
  1. Let's sort keys in alphabetical sequence:

"amount", "currency", "payway", "shop_id", "shop_order_id"

  1. The line for generating the SHA256 hash will be as follows:

"6320.91:840:card_invoice_usd:1520:5b0efa8a-153b-4421-abac-2aba4d772a86account-secret-key"

Where account-secret-key is the secret identification key for your account. You can request a key from the support service.

  1. Let's get a hash expression of the generated line using Python code:
>>> string_to_sign = '6320.91:840:card_invoice_usd:1520:5b0efa8a-153b-4421-abac-2aba4d772a86account-secret-key'
>>> import hashlib
>>> sign = hashlib.sha256(string_to_sign.encode()).hexdigest()
>>> print(sign)
'77a6f7a30876d480d4e771d08cb83800dd5cb874664c77e515ffc052b20293c6'
You can check whether you have generated the signature correctly using the service https://www.xorbin.com/tools/sha256-hash-calculator.

Body

application/json
​
shop_id
integer
required

Unique shop identifier in the M4 system.

Example:

1520

​
shop_order_id
string
required

Order ID in your system. Must be unique for each new invoice.

Maximum string length: 255
Example:

"5b0efa8a-153b-4421-abac-2aba4d772a86"

​
amount
string
required

Amount received or withdrawn. Example: "227.34"

Example:

"6320.91"

​
currency
number
required

Numeric currency identifier in accordance with ISO 4217. Example: 840

Example:

840

​
payway
string
required

Payment way for payment. Invoice currency depends on the specified payment way.

There are two ways to get a list of all payment directions available to the shop:

  • Execute API request "Receiving payment methods for input" shop_input_config/shop.
  • Request register from the support service.
Maximum string length: 150
Pattern: ^[A-Za-z_,\[\]]+$
Example:

"card_payway_usd"

​
client_ip
string<IPv4>
required

Payer IP address

Example:

"192.168.1.1"

​
description
string

Optional payment description.

Maximum string length: 255
Example:

"Payment for shop_id=1520"

​
failed_url
string<uri>

URL where the payer will be redirected after unsuccessful invoice payment.

Example:

"https://your-domain.com/status/failed/"

​
success_url
string<uri>

URL where the payer will be redirected after successful invoice payment.

Example:

"https://your-domain.com/status/success/"

​
callback_url
string<uri>

URL where the notification about successful payment will be sent.

Example:

"https://your-domain.com/status/callback/"

​
callback_rejected_url
string<uri>

URL where the notification about unsuccessful payment will be sent.

Example:

"https://your-domain.com/status/rejected/"

​
expires_at
string<date-time>

Invoice expiration date in ISO 8601 format. If invoice is not paid until this date, subsequent invoice payment will not be possible.

Example:

"2026-06-01T00:00:00Z"

​
card
object

Bank card details should be sent when:

  • You have a PCI DSS certificate
  • You do not need a page on the M4 side to get card details from the buyer

In case the payment way to the cards is used and the card data is not transmitted, the response to the request will contain a link to redirect the buyer to enter the card details. Also, method, url and data will be filled in if the user needs to be redirected to pass the 3DSecure check.

​
issue_payment_token
boolean

This parameter is used to generate a payment token. More details invoice/recurrent

Example:

false

​
client_info
object

Payer browser information.

See Payer Browser Authentication for 3D Secure for the details of the data gathering.

Response

200 - application/json
​
result
boolean
required

Boolean value, in case of successful response it will be true, in case of error – false

Example:

true

​
message
string
required

A textual description of the error, in case of success - simply Ok

Example:

"Ok"

​
error_code
number
required

If this value is greater than 0, then the request ended with an error. Description of error codes

Example:

0

​
data
Invoice payment form · object
required