Initiate sale

Introduction

Initiate sale is initiated through HTTPS POST request by using URLs and the parameters.

To initiate sale, Connecting Party’s app sends {accessToken} with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random {nonce} and encrypted {signature}.

In response Connecting Party’s server also provides information about invoice in Connecting Party’s system and endpoint in Billblend.

API URLs

Connecting Party Server
https://proxy.connectingpartyserver.com/sale/initiate-sale

Request Parameters

Parameter Name	Description	Value
consumer		`Necessity`: Required`Type`: Object
consumer.device		`Necessity`: Required`Type`: Object
consumer.device.serialNumber	Consumer’s device serial number.	`Necessity`: Required`Type`: String`Length`: 1-50
transaction		`Necessity`: Required`Type`: Object
transaction.amountCentis	Transaction amount, 1.00 EUR = 100 centis.	`Necessity`: Required`Type`: Integer
transaction.currency	Upper case letters (ISO 4217 alpha code).	`Necessity`: Required`Type`: String`Length`: 3
session		`Necessity`: Required`Type`: Object
session.accessToken	Access token key received in Optional consumer authentication.	`Necessity`: Required`Type`: String`Length`: 32-128
consumer.device.imei	Consumer’s device international mobile equipment identity.	`Necessity`: Optional`Type`: String`Length`: 14-16
location		`Necessity`: Optional`Type`: Object
location.lat	The latitude specified in the range of -90.0 through +90.0, both inclusive.	`Necessity`: Optional`Type`: Double
location.lng	The longitude specified in the range -180.0 through +180.0, both inclusive.	`Necessity`: Optional`Type`: Double
consumer.ipAddresses	Consumer’s IP addresses.	`Necessity`: Optional`Type`: List
consumer.ipAddresses[]	Consumer’s IP address.	`Necessity`: Optional`Type`: String`Length`: 7-15

Success Response Parameters

Parameter Name	Description	Value
endpointId	Entry point identifier for sale transaction.	`Necessity`: Required`Type`: String
invoiceId	Transfer transaction identifier.	`Necessity`: Required`Type`: String
session		`Necessity`: Required`Type`: Object
session.nonce	Unique random string generated by Connecting Party’s server.	`Necessity`: Required`Type`: String
session.signature	Checksum generated by hmac-sha1 (see Signature computation) from the concatenation of the accessToken, consumer.device.serialNumber, endpointId, session.nonce, invoiceId, transaction.amountCentis and the transaction.currency.	`Necessity`: Required`Type`: String

Fail Response Parameters

Parameter Name	Description	Value
error		`Type`: Object
error.cause	Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`.	`Type`: Enum
error.code	The unique error code.	`Type`: String
error.message	Description of the error.	`Type`: String

Request Example

{
  "consumer": {
    "device": {
      "imei": "string",
      "serialNumber": "string"
    },
    "ipAddresses": ["string"]
  },
  "location": {
    "lat": "double",
    "lng": "double"
  },
  "session": {
    "accessToken": "string"
  },
  "transaction": {
    "amountCentis": "integer",
    "currency": "string"
  }
}

Success Response Example

{
  "endpointId": "string",
  "invoiceId": "string",
  "session": {
    "nonce": "string",
    "signature": "string"
  }
}

Fail Response Example

{
  "error": {
    "cause": "enum",
    "code": "string",
    "message": "string"
  }
}