Create customer contract

JSON API v3

POST /api/v3/projects/{projectId}/contracts

Initiates binding of a customer (typically mobile phone number) for repeat payments within the project.

v4 signature payload: {merchant_contract_id}{customerPayload}{pin_code}{client_ip}

Request parameters

Field	Type	Required	Description
`projectId`	integer (int32)	yes

Request body

Field	Type	Required	Description
`client_ip`	string	—
`customer`	object	—	Polymorphic customer block. The actual subset of fields depends on `type`: - `mobile_phone`: `msisdn`, `email` - `bank_card`: `source`, `country`, `merchant_customer_id`, `email`, and — on the PCI DSS contour host only — `bank_card` with the card details - `undefined_bank_card`: same fields as `bank_card`, minus the card details Choosing between the two card types. They are different payment routes, so the type is always stated explicitly — it is never inferred from other fields: - `undefined_bank_card` — the payer enters the card on the payment page opened by `authorization.url`. The card is not bound, contracts are not supported. - `bank_card` — the card is bound to a contract and can be charged again later. Requires approved bank card settings for the project and the payer’s country; on the PCI DSS contour the card details are sent with the request.
`customer.type`	`mobile_phone` · `bank_card` · `undefined_bank_card`	—
`customer.msisdn`	string	—	Customer’s MSISDN in international E.164 format (no `+`). Required for `mobile_phone`.
`customer.email`	string (email)	—	Customer’s email
`customer.country`	string	—	Country code (ISO 3166-1 alpha-2). Required for `bank_card`.
`customer.network`	object	—
`customer.network.id`	integer (int32)	—	Network ID (see operators reference)
`customer.network.name`	string	—
`customer.operator`	object	—
`customer.operator.id`	integer (int32)	—	Operator ID (see operators reference)
`customer.operator.name`	string	—
`customer.source`	string	—	Source name in the merchant’s system (unique per partner). Required for `bank_card`.
`customer.merchant_customer_id`	string	—	Unique customer ID in the merchant’s system. Required for `bank_card`.
`customer.bank_card`	object	—
`merchant_contract_id`	string	—	Contract ID in the merchant’s system. Contract is created by the key customer + merchant_contract_id.

Request example — Mobile phone (DCB)


{
  "client_ip": "10.20.30.40",
  "customer": {
    "type": "mobile_phone",
    "msisdn": "79600000000"
  },
  "merchant_contract_id": "1234567890"
}

Request example — Bank card with card details (PCI DSS contour host only)


{
  "client_ip": "10.20.30.40",
  "customer": {
    "type": "bank_card",
    "source": "my_app",
    "country": "RU",
    "merchant_customer_id": "client_12345",
    "email": "test@test.com",
    "bank_card": {
      "pan": "4111111111111111",
      "expiration_month": "12",
      "expiration_year": "2030",
      "security_code": "123",
      "cardholder": "IVAN IVANOV"
    }
  },
  "merchant_contract_id": "1234567890"
}

Request example — Contracts_Create / duplicate (HTTP 409)


{
  "client_ip": "127.0.0.1",
  "customer": {
    "type": "bank_card",
    "source": "app",
    "country": "RU",
    "merchant_customer_id": "CUSTOMER-000000001",
    "email": "test@test.com",
    "bank_card": {
      "pan": "1111222233334444",
      "expiration_month": "12",
      "expiration_year": "2030",
      "security_code": "123",
      "cardholder": "IVAN IVANOV"
    }
  },
  "contract": {
    "merchant_contract_id": "CONTRACT-000000001"
  }
}

Request example — Contracts_Create / mobile_phone (HTTP 201)


{
  "merchant_contract_id": "CONTRACT-000000001",
  "customer": {
    "type": "mobile_phone",
    "msisdn": "79600000000"
  },
  "client_ip": "127.0.0.1"
}

Response example


{
  "success": true,
  "data": {
    "contract_id": "0d0f3c58-9b1e-4a77-9a0c-000000000002",
    "authorization_type": "SMS_PIN",
    "expires_at": "2026-09-21T12:00:00Z",
    "merchant_contract_id": "CONTRACT-000000001",
    "customer": {
      "type": "mobile_phone",
      "msisdn": "79600000000"
    }
  }
}

Response codes

Code	Description
`201`	Contract created
`400`	Validation or business request error
`401`	Authentication failed (missing/invalid signature or timestamp)
`403`	Project access denied or IP not whitelisted
`409`	Contract already exists or contract draft already exists
`422`	Business validation error
`500`	Unexpected platform error
`503`	Service temporarily unavailable

XML API v2.9

POST /API/XML/InvoiceManagementService.ashx

Creates a contract (subscription) for a customer. XML request type: <CreateCustomerContractRequest>.

Initiating a payment authorization process by Merchant for client MSISDN. After creation, the Platform will send an SMS with a PIN code for user authorization (depending on settings).

HTTP Headers:

Callisto-Protocol-Version: 2
SignatureVersion: 3

Card-on-file / custom form scenario (spec EN 2.7). The contract can also be created for a bank card customer: <BankCardCustomer> (Source, Country, MerchantCustomerId, Email) with the full <BankCard> block inside (PAN, ExpirationMonth, ExpirationYear, SecurityCode, Cardholder) plus MerchantContractID. Headers in this scenario: SignatureVersion: 4, Callisto-Protocol-Version: 2. The response returns ContractID, AuthorizationType: SKIP (no PIN confirmation, unlike the mobile phone flow) and the contract ExpirationTimeUtc. Under such a contract all payments are processed without additional authorization — charges go through the regular CreateInvoice with the same <BankCardCustomer> and <CustomerContractInfo> (MerchantContractID; CreateIfNotExists may create the contract together with the invoice).

Two hard conditions from the spec: the merchant handling raw card data must be PCI DSS certified (otherwise use the “Payment via Bank Payment Form” scenario), and the presence of the BankCard block is governed by the integration type and the individual requirements of the acquirer — it is enabled per partner.

Sandbox emulation (v2.64.0): the scenario is fully emulated. BankCardCustomer with a BankCard block returns the spec response (ContractID, SKIP, contract ExpirationTimeUtc); without the block the request falls back to the default stub. Sandbox rules: only test card numbers starting with 1111 are accepted (e.g. 1111222233334444) — never send real card data; reserved endings 0001–0005 make subsequent charges fail. Repeated binding of an active MerchantContractID returns 230 with the existing ContractID in ResultDescription. Charges via CreateInvoice + MerchantContractID return the CustomerContractInfo block and an AuthorizationInfo/AuthorizationUrl pointing at a 3-D Secure confirmation page (any 4-digit code) — the card form itself stays on the merchant side. Card data is never stored (only the last 4 digits of PAN) and is masked in the request log (v2.62.1). Sandbox contracts are purged with the regular retention window, not the 2-year spec lifetime.

Project setting card_3ds_enabled (v2.65.0). In production the 3-D Secure challenge is enabled per integration, so the sandbox makes it a project setting (managed by the sandbox administrators, on by default). With 3-D Secure off a charge by contract is settled inside the CreateInvoice response: there is no AuthorizationInfo block (no payment link at all), AuthorizationType is SKIP, and InvoiceStatus/PaymentStatus already carry the outcome (Processed/PAID, or Cancelled/NOT_PAID for a reserved card ending). The payment-form scenario (no contract) is unaffected — the card form is always shown, only the confirmation page is skipped.

Request parameters

Field	Type	Required	Description
`Callisto-Protocol-Version`	`2`	yes	Protocol version
`SignatureVersion`	integer (int32, default `1`)	—	Signature version number

Request body

Field	Type	Required	Description
`CreateCustomerContractRequest`	object	yes	The customer is a polymorphic element: exactly one of `MobilePhoneCustomer`, `BankCardCustomer`, `UndefinedBankCardCustomer` (the element name defines the subtype). There is no `CustomerInfo` wrapper in the request.
`CreateCustomerContractRequest.ProjectID`	integer (int32)	yes	Project ID in the Platform system. Assigned during project setup.
`CreateCustomerContractRequest.UndefinedMobilePhoneCustomer`	object	—	Platform customer type. The sandbox does not support it — use `MobilePhoneCustomer`.
`CreateCustomerContractRequest.UndefinedMobilePhoneCustomer.NetworkID`	integer (int32)	yes
`CreateCustomerContractRequest.UndefinedMobilePhoneCustomer.Email`	string	—
`CreateCustomerContractRequest.MobilePhoneCustomer`	object	—	Customer identification by mobile phone number. MSISDN is the primary identifier.
`CreateCustomerContractRequest.MobilePhoneCustomer.MSISDN`	string	yes	Client’s MSISDN (Mobile Subscriber Integrated Services Digital Number) in international format without ’+’ sign
`CreateCustomerContractRequest.MobilePhoneCustomer.Email`	string (email)	—	Client’s e-mail address
`CreateCustomerContractRequest.BankCardCustomer`	object	—	Customer identification by bank card. Used for card payment scenarios.
`CreateCustomerContractRequest.BankCardCustomer.Email`	string (email)	—	Client’s e-mail address
`CreateCustomerContractRequest.BankCardCustomer.Source`	string	yes	Source Name in Merchant’s system (unique for Partner Service). Should be a unique identifier (e.g. resource/brand name) guaranteeing global uniqueness for parameters source+MerchantCustomerId in all systems.
`CreateCustomerContractRequest.BankCardCustomer.Country`	string	yes	Country code (ISO 3166-1 alpha-2, lowercase)
`CreateCustomerContractRequest.BankCardCustomer.MerchantCustomerId`	string	yes	Customer ID in Merchant’s system (unique)
`CreateCustomerContractRequest.UndefinedBankCardCustomer`	object	—	Bank card customer identification without full data set. Used for initial card payment when card details are not yet known.
`CreateCustomerContractRequest.UndefinedBankCardCustomer.Source`	string	—	Source Name in Merchant’s system (unique for Partner Service). Should guarantee global uniqueness for parameters source+MerchantCustomerId.
`CreateCustomerContractRequest.UndefinedBankCardCustomer.Country`	string	yes	Country code (ISO 3166-1 alpha-2, lowercase)
`CreateCustomerContractRequest.UndefinedBankCardCustomer.MerchantCustomerId`	string	yes	Customer ID in Merchant’s system (unique)
`CreateCustomerContractRequest.UndefinedBankCardCustomer.Email`	string (email)	—	Client’s e-mail address
`CreateCustomerContractRequest.UndefinedCustomer`	object	—	Platform customer type. The sandbox does not support it — use `MobilePhoneCustomer`, `BankCardCustomer` or `UndefinedBankCardCustomer`.
`CreateCustomerContractRequest.UndefinedCustomer.Country`	string	—
`CreateCustomerContractRequest.UndefinedCustomer.Email`	string	—
`CreateCustomerContractRequest.ClientIP`	string	—	IP address from which the client makes the request. Mandatory by default (configurable in project settings).
`CreateCustomerContractRequest.CustomerContractInfo`	object	—	Contract creation parameters for CreateInvoice request.
`CreateCustomerContractRequest.CustomerContractInfo.MerchantContractID`	string	—	The ID of the contract in the Merchant’s system. If the value is set, a contract will be created using the MSISDN + MerchantContractID key. If not specified, only by MSISDN. Unique within a single MSISDN.
`CreateCustomerContractRequest.CustomerContractInfo.CreateIfNotExists`	boolean	—	If “true” and the project supports contract scheme, and user has no contract — a new contract will be created for the user.
`CreateCustomerContractRequest.AuthorizationInfo`	object	—	Authorization data — PIN code entered by the subscriber to confirm the payment or contract.
`CreateCustomerContractRequest.AuthorizationInfo.PinCode`	string	yes	PIN code entered by the subscriber to confirm the contract/invoice
`Header`	object	yes	Request header with authentication. Included in every API request.
`Header.Authentication`	object	yes	Request authentication data. All three fields are mandatory for every request.
`Header.Authentication.Login`	string	yes	Merchant Login assigned by the Platform
`Header.Authentication.NowUtc`	string	yes	Current UTC time in yyyyMMddHHmmss format. Must not differ from platform system time by more than 20 minutes.
`Header.Authentication.Signature`	string	yes	HMAC request signature. Calculated as: LOWERCASE(HMACSHA256(Password, Login + LOWERCASE(HMACSHA256(Password, NowUtc))))
`Header.RequestAttempt`	integer (int32)	—	Ordinal invoice request number (for idempotency). Starting from 0.
`Header.Gateway`	object	—	Platform service block in the request header. The sandbox does not read it: the block is ignored and affects neither the signature nor processing.
`Header.Gateway.Signature`	string	—
`Header.Gateway.ContractInfo`	object	—
`Header.Gateway.ContractInfo.DesiredExpirationTimeUtc`	string (date-time)	—

Request example — Bank card binding (custom form, PCI DSS; SignatureVersion 4)


<?xml version="1.0" encoding="utf-8"?>
<Request>
  <Header>
    <Authentication>
      <Login>MerchantLogin</Login>
      <NowUtc>20260831200008</NowUtc>
      <Signature>9fdfa545c3f7ec17ce1a7746e0f78450aa11bc4de2f19c8be31e250398a25f48</Signature>
    </Authentication>
    <RequestAttempt>0</RequestAttempt>
  </Header>
  <CreateCustomerContractRequest>
    <ProjectID>1234</ProjectID>
    <ClientIP>10.20.30.40</ClientIP>
    <BankCardCustomer>
      <Source>source_name</Source>
      <Country>ru</Country>
      <MerchantCustomerId>client_id</MerchantCustomerId>
      <Email>test@test.com</Email>
      <BankCard>
        <PAN>1111222233334444</PAN>
        <ExpirationMonth>08</ExpirationMonth>
        <ExpirationYear>28</ExpirationYear>
        <SecurityCode>123</SecurityCode>
        <Cardholder>IVANOV IVAN</Cardholder>
      </BankCard>
    </BankCardCustomer>
    <CustomerContractInfo>
      <MerchantContractID>1234567890</MerchantContractID>
    </CustomerContractInfo>
  </CreateCustomerContractRequest>
</Request>

Request example — createCustomerContract / mobile_phone (HTTP 200)


<?xml version="1.0" encoding="utf-8"?>
<Request>
  <Header>
    <Authentication>
      <Login>demo_login</Login>
      <NowUtc>20260921120000</NowUtc>
      <Signature>0000000000000000000000000000000000000000000000000000000000000000</Signature>
      <SignatureVersion>3</SignatureVersion>
    </Authentication>
  </Header>
  <CreateCustomerContractRequest>
      <ProjectID>1001</ProjectID>
      <ClientIP>127.0.0.1</ClientIP>
      <MobilePhoneCustomer>
        <MSISDN>79600000000</MSISDN>
      </MobilePhoneCustomer>
      <CustomerContractInfo>
        <MerchantContractID>CONTRACT-000000001</MerchantContractID>
      </CustomerContractInfo>
    </CreateCustomerContractRequest>
</Request>

Response example — Bank card binding (custom form) — AuthorizationType SKIP


<?xml version="1.0" encoding="utf-8"?>
<Response>
  <CreateCustomerContractResponse>
    <BankCardCustomer>
      <Source>source_name</Source>
      <Country>ru</Country>
      <MerchantCustomerId>client_id</MerchantCustomerId>
      <Email>test@test.com</Email>
    </BankCardCustomer>
    <CustomerContractInfo>
      <ContractID>1c6495bb-0002-005f-f54e-d286731d55b9</ContractID>
      <AuthorizationType>SKIP</AuthorizationType>
      <ExpirationTimeUtc>27.04.2028 21:00:06</ExpirationTimeUtc>
      <MerchantContractID>1234567890</MerchantContractID>
    </CustomerContractInfo>
  </CreateCustomerContractResponse>
  <ResultCode>0</ResultCode>
  <ResultDescription>OK</ResultDescription>
</Response>

Response example — createCustomerContract / mobile_phone (HTTP 200)


<?xml version="1.0" encoding="utf-8"?>
<Response>
  <CreateCustomerContractResponse>
    <MobilePhoneCustomer>
      <MSISDN>79600000000</MSISDN>
      <Country>ru</Country>
      <NetworkID>7</NetworkID>
      <OperatorID>22</OperatorID>
    </MobilePhoneCustomer>
    <CustomerContractInfo>
      <ContractID>0d0f3c58-9b1e-4a77-9a0c-000000000002</ContractID>
      <AuthorizationType>SMS_PIN</AuthorizationType>
      <ExpirationTimeUtc>2026-09-21T12:00:00Z</ExpirationTimeUtc>
      <MerchantContractID>CONTRACT-000000001</MerchantContractID>
    </CustomerContractInfo>
  </CreateCustomerContractResponse>
  <ResultCode>0</ResultCode>
  <ResultDescription>OK</ResultDescription>
</Response>