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: 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.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 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"
  }
}