Sale card mapping notification

Introduction

Sale card mapping notification is initiated through HTTPS POST request by using URLs and the parameters.
Card mapping notification is used to allow Consumer credentials (phone, email, billing address, twitter name, etc) for mapping to card data. Card mappings can be used later in transfer or sale transactions instead of card numbers and other cardholder information. Billblend sends Sale card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - {serverCardId}.
Connecting Party’s server maps this {serverCardId} to {clientCardId}, created on its side. This {clientCardId} can then be mapped in Connecting Party’s app or on Connecting Party’s server to any Consumer’s data from the initial Perform sale request. This allows Connecting Party’s app to process sale or transfer transactions by Consumer’s email, phone number, etc.
{uniqueReferenceCardId} remains the same if Consumer makes another transaction with the same card number but different expiry date, for example. It can be used by Connecting Party for loyalty programs or fraud control.
Connecting Party’s app makes new sale requests using {clientCardId} instead of source card data. Billblend sends this {clientCardId} to Connecting Party’s server in “Check sale request” and gets mapped to it {serverCardId} in “Check sale response” from Connecting Party’s server, which is used to continue the processing of this transaction.
{serverCardId} of source or verified card can be used for new sale transactions and both as source or destination for new transfer transactions.

API URLs

Connecting Party Server

https://proxy.connectingpartyserver.com/sale/notification

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

session


Necessity: Required
Type: Object

session.accessToken

Consumer’s access token key.

Necessity: Required
Type: String
Length: 32-128

session.token

The session token of sale transaction.

Necessity: Required
Type: String
Length: 16-36

sourceCard

Necessity: Optional
Type: Object

sourceCard.bin

The Source card BIN.

Necessity: Optional
Type: Integer

sourceCard.reference

Necessity: Optional
Type: Object

sourceCard.reference.serverCardId

The Source card reference identifier (on server side).

Necessity: Optional
Type: String
Length: 1-64

sourceCard.reference.uniqueReferenceCardId

The Source card unique identifier (on server side).

Necessity: Optional
Type: Integer

Success Response Parameters

Parameter Name

Description

Value

invoiceId

Sale transaction identifier.

Type: String

session

Type: Object

session.checkSignature

Checksum generated by hmac-sha1 (see Signature computation) from the concatenation of session.nonce, endpointId and invoiceId.

Type: String

session.nonce

Unique random string generated by Connecting Party’s server.

Type: String

session.token

The session token of sale transaction.

Type: String

Fail Response Parameters

Parameter Name

Description

Value

error

Type: Object

error.cause

Сause 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

invoiceId

Sale transaction identifier.

Type: String

Request Example

{
  "consumer": {
    "device": {
      "serialNumber": "string"
    }
  },
  "session": {
    "accessToken": "string",
    "token":"string"
  },
  "sourceCard": {
    "bin": "integer",
    "reference": {
      "serverCardId": "string",
      "uniqueReferenceCardId": "integer"
    }
  }
}

Success Response Example

{
  "invoiceId": "string",
  "session": {
    "checkSignature": "string",
    "nonce": "string",
    "token": "string"
  }
}

Fail Response Example

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