Initiate verification

Introduction

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

To initiate card verification, Connecting Party’s app sends {accessToken} with other device parameters to Connecting Party’s server. These parameters are used to start a session with unique random {nonce} and encrypted {signature}. In response Connecting Party’s server also provides information about {invoiceId} in Connecting Party’s system and {endpointId} in Billblend.

API URLs

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

Request Parameters

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

Success Response Parameters

Parameter Name	Description	Value
endpointId	Entry point identifier for verification transaction.	Type: String
invoiceId	Verification transaction identifier.	Type: String
session		Type: Object
session.nonce	Unique random string generated by Connecting Party’s server.	Type: String
session.signature	Checksum generated by hmac-sha1 (see Signature computation) from the concatenation of accessToken, consumer.device.serialNumber, endpointId, session.nonce, invoiceId and transaction.currency.	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": {
    "currency": "string"
  }
}

Success Response Example

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

Fail Response Example

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