Initiate transfer

Introduction

Initiate transfer is initiated through HTTPS POST request by using URLs and the parameters.
To initiate funds transfer, 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.
The Connecting Party’s server may also respond with the transaction’s commission.

API URLs

Connecting Party Server

https://proxy.connectingpartyserver.com/transfer/initiate-transfer

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.

Type: Double

location.lng

The longitude specified in the range -180.0 through +180.0, both inclusive.

Type: Double

consumer.ipAddresses

Consumer’s IP addresses.

Type: List

consumer.ipAddresses[]

Consumer’s IP address.

Necessity: Optional
Type: String
Length: 7-15

fromBin

Source of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission.

Necessity: Optional
Type: String
Length: 6

toBin

Destination of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission.

Necessity: Optional
Type: String
Length: 6

Success Response Parameters

Parameter Name

Description

Value

endpointId

Entry point identifier for transfer 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

rates

Necessity: Optional
Type: Object

rates.min

Possible minimum commission amount.

Necessity: Optional
Type: String

rates.max

Possible maximum commission amount.

Necessity: Optional
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",
  "rates": {
    "min": "string",
    "max": "string"
  },
  "session": {
    "nonce": "string",
    "signature": "string"
  }
}

Fail Response Example

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