Authorize contract with PIN

JSON API v3

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

Confirms a created contract using a PIN code sent to the customer via SMS.

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

Request parameters

Field	Type	Required	Description
`projectId`	integer (int32)	yes
`contractId`	string (uuid)	yes

Request body

Field	Type	Required	Description
`client_ip`	string	—
`pin_code`	string	—

Request example


{
  "pin_code": "1234"
}

Response example


{
  "success": true,
  "data": {
    "contract_id": "0d0f3c58-9b1e-4a77-9a0c-000000000002",
    "status": "active"
  }
}

Response codes

Code	Description
`200`	Contract authorized
`400`	Validation or business request error
`401`	Authentication failed (missing/invalid signature or timestamp)
`403`	Project access denied or IP not whitelisted
`404`	Contract not found
`422`	Business validation error
`500`	Unexpected platform error
`503`	Service temporarily unavailable

XML API v2.9

POST /API/XML/InvoiceManagementService.ashx

Authorizes a customer contract using a PIN code. XML request type: <AuthorizeCustomerContractRequest>.

After creating a contract, the Platform sends an SMS to MSISDN with a PIN code. The Merchant’s application should transfer this PIN code to authorize the contract. If the PIN code is correct, the contract becomes “alive” — until it expires, all subsequent payments will not require additional confirmations.

HTTP Headers:

Callisto-Protocol-Version: 2
SignatureVersion: 3

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
`AuthorizeCustomerContractRequest`	object	yes
`AuthorizeCustomerContractRequest.ProjectID`	integer (int32)	yes	Project ID in the Platform system. Assigned during project setup.
`AuthorizeCustomerContractRequest.ClientIP`	string	—	IP address from which the client makes the request. Mandatory by default (configurable in project settings).
`AuthorizeCustomerContractRequest.CustomerContractInfo`	object	yes	Customer contract reference for authorize/cancel operations.
`AuthorizeCustomerContractRequest.CustomerContractInfo.ContractID`	string (uuid)	yes	Unique Contract ID to be authorized or cancelled
`AuthorizeCustomerContractRequest.CustomerContractInfo.MerchantContractID`	string	—	The ID of the contract in the Merchant’s system
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedMobilePhoneCustomer`	object	—	Platform customer type. The sandbox does not support it — use `MobilePhoneCustomer`.
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedMobilePhoneCustomer.NetworkID`	integer (int32)	yes
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedMobilePhoneCustomer.Email`	string	—
`AuthorizeCustomerContractRequest.CustomerContractInfo.MobilePhoneCustomer`	object	—	Customer identification by mobile phone number. MSISDN is the primary identifier.
`AuthorizeCustomerContractRequest.CustomerContractInfo.MobilePhoneCustomer.MSISDN`	string	yes	Client’s MSISDN (Mobile Subscriber Integrated Services Digital Number) in international format without ’+’ sign
`AuthorizeCustomerContractRequest.CustomerContractInfo.MobilePhoneCustomer.Email`	string (email)	—	Client’s e-mail address
`AuthorizeCustomerContractRequest.CustomerContractInfo.BankCardCustomer`	object	—	Customer identification by bank card. Used for card payment scenarios.
`AuthorizeCustomerContractRequest.CustomerContractInfo.BankCardCustomer.Email`	string (email)	—	Client’s e-mail address
`AuthorizeCustomerContractRequest.CustomerContractInfo.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.
`AuthorizeCustomerContractRequest.CustomerContractInfo.BankCardCustomer.Country`	string	yes	Country code (ISO 3166-1 alpha-2, lowercase)
`AuthorizeCustomerContractRequest.CustomerContractInfo.BankCardCustomer.MerchantCustomerId`	string	yes	Customer ID in Merchant’s system (unique)
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedBankCardCustomer`	object	—	Bank card customer identification without full data set. Used for initial card payment when card details are not yet known.
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedBankCardCustomer.Source`	string	—	Source Name in Merchant’s system (unique for Partner Service). Should guarantee global uniqueness for parameters source+MerchantCustomerId.
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedBankCardCustomer.Country`	string	yes	Country code (ISO 3166-1 alpha-2, lowercase)
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedBankCardCustomer.MerchantCustomerId`	string	yes	Customer ID in Merchant’s system (unique)
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedBankCardCustomer.Email`	string (email)	—	Client’s e-mail address
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedCustomer`	object	—	Platform customer type. The sandbox does not support it — use `MobilePhoneCustomer`, `BankCardCustomer` or `UndefinedBankCardCustomer`.
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedCustomer.Country`	string	—
`AuthorizeCustomerContractRequest.CustomerContractInfo.UndefinedCustomer.Email`	string	—
`AuthorizeCustomerContractRequest.AuthorizeInfo`	object	yes	Authorization data — PIN code entered by the subscriber to confirm the payment or contract.
`AuthorizeCustomerContractRequest.AuthorizeInfo.PinCode`	string	yes	PIN code entered by the subscriber to confirm the contract/invoice
`AuthorizeCustomerContractRequest.TestInfo`	object	—	Test information for authorization
`AuthorizeCustomerContractRequest.TestInfo.SuccessAuthorizationResult`	boolean	yes
`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


<?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>
  <AuthorizeCustomerContractRequest>
          <ProjectID>1001</ProjectID>
          <ClientIP>127.0.0.1</ClientIP>
          <CustomerContractInfo>
            <ContractID>0d0f3c58-9b1e-4a77-9a0c-000000000002</ContractID>
          </CustomerContractInfo><AuthorizeInfo><PinCode>1234</PinCode></AuthorizeInfo>
        </AuthorizeCustomerContractRequest>
</Request>

Response example


<?xml version="1.0" encoding="utf-8"?>
<Response>
  <AuthorizeCustomerContractResponse />
  <ResultCode>0</ResultCode>
  <ResultDescription>OK</ResultDescription>
</Response>