Perform validation

Introduction

Perform validation is initiated through HTTPS POST request by using URLs and the parameters.
Connecting Party’s app sends cardholder, device, session data and other parameters straight to Billblend to check the card for being valid.
A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.

API URLs

Integration

Production

https://sandbox.billblend.com/checkout/dapi/v1/verification/{endpointId}/{invoiceId}

https://pay.billblend.com/checkout/dapi/v1/verification/{endpointId}/{invoiceId}

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

consumer.email

Сonsumer’s email address.

Necessity: Required
Type: String
Length: 3-128

session

Necessity: Required
Type: Object

session.accessToken

Access token key received in Optional consumer authentication.

Necessity: Required
Type: String
Length: 32-128

session.nonce

Value received in Initial verification response.

Necessity: Required
Type: String
Length: 32-128

session.signature

Value received in Initial verification response.

Necessity: Required
Type: String
Length: 32-128

sourceCard

Necessity: Required
Type: Object

sourceCard.expiry

Necessity: Required
Type: Object

sourceCard.expiry.month

Source Card expiration month.

Necessity: Required
Type: Integer
Length: 2

sourceCard.expiry.year

Source Card expiration year.

Necessity: Required
Type: Integer
Length: 4

sourceCard.holder

Necessity: Required
Type: Object

sourceCard.holder.firstName

Cardholder’s first name.

Necessity: Required
Type: String
Length: 1-50

sourceCard.holder.lastName

Cardholder’s last name.

Necessity: Required
Type: String
Length: 1-50

sourceCard.holder.printedName

Cardholder’s printed name (first and last name together). May be used instead of firstName + lastName.

Necessity: Required
Type: String
Length: 1-50

sourceCard.number

Source card number (PAN).

Necessity: Required
Type: String
Length: 9-19

sourceCard.securityCode

Source card security code (CVV).

Necessity: Required
Type: String
Length: 3-4

transaction

Necessity: Required
Type: Object

transaction.currency

Upper case letters (ISO 4217 alpha code).

Necessity: Required
Type: String
Length: 3

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

billing

Necessity: Optional
Type: Object

billing.address

Necessity: Optional
Type: Object

billing.address.city

City name.

Necessity: Optional
Type: String
Length: 1-100

billing.address.country

ISO alpha3 country code.

Necessity: Optional
Type: String
Length: 3

billing.address.postcodeZip

ZIP post code

Necessity: Optional
Type: String
Length: 1-10

billing.address.state

State is used if present. For example, Los Angeles is in CA state.

Necessity: Optional
Type: String
Length: 2-3

billing.address.street

Street is used for district names and street names.

Necessity: Optional
Type: String
Length: 1-50

billing.address.street2

Street 2 is used for long addresses. Usually it contains apartment and building №.

Necessity: Optional
Type: String
Length: 1-50

billing.phone

Customer’s contact phone number.

Necessity: Optional
Type: String
Length: 1-20

consumer.birthDay

Сonsumer’s birth day in “ddMMyyyy” format.

Necessity: Optional
Type: String
Length: 8

consumer.device.imei

Сonsumer’s device international mobile equipment identity.

Necessity: Optional
Type: String
Length: 14-16

consumer.ipAddresses

Сonsumer’s IP addresses.

Necessity: Optional
Type: List

consumer.ipAddresses[]

Сonsumer’s IP address.

Necessity: Optional
Type: String
Length: 7-15

order

Necessity: Optional
Type: Object

order.description

Brief transaction description. May be mandatory for certain Acquirer Banks.

Necessity: Optional
Type: String
Length: 128

order.siteUrl

URL of website associated with the transaction.

Necessity: Optional
Type: String
Length: 128

order.purpose

May be used for better transaction control or additional checks.

Necessity: Optional
Type: String
Length: 128

Success Response Parameters

Parameter Name

Description

Value

invoiceId

Verification transaction identifier.

Type: String

session

Type: Object

session.token

The session token of verification transaction.

Type: String

Fail Response Parameters

Parameter Name

Description

Value

error

Type: Object

error.cause

Cause of the error. Possible values: INVALID_REQUEST, INVALID_CONFIGURATION, INTERNAL_ERROR, PROCESSING_FAILED.

Type: Enum

error.code

The unique error code.

Type: String

error.message

Description of the error.

Type: String

invoiceId

Verification transaction identifier.

Type: String

Request Example

{
  "billing": {
    "address": {
      "city": "string",
      "country": "string",
      "postcodeZip": "string",
      "state": "string",
      "street": "string",
      "street2": "string"
    },
    "phone": "string"
  },
  "consumer": {
    "birthDay": "string",
    "device": {
      "imei": "string",
      "serialNumber": "string"
    },
    "email": "string",
    "ipAddresses": ["string"]
  },
  "location": {
    "lat": "double",
    "lng": "double"
  },
  "order": {
    "description": "string",
    "siteUrl": "string",
    "purpose": "string"
  },
  "session": {
    "accessToken": "string",
    "nonce": "string",
    "signature": "string"
  },
  "sourceCard": {
    "expiry": {
      "month": "integer",
      "year": "integer"
    },
    "holder":{
      "firstName": "string",
      "lastName": "string"
    },
    "number": "string",
    "securityCode": "string"
  },
  "transaction": {
    "currency": "string"
  }
}

Success Response Example

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

Fail Response Example

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

Request Builder

For integration purposes use Billblend test scenarios to generate random card numbers.
Parameters with light red background are mandatory.

Endpoint Id
Invoice Id

Generated by Merchant's server in "Initiate verification"

Device serial number
Device imei
E-mail
Birthday
Ip Address
accessToken

Generated by Merchant's server in "Consumer authentication"

nonce

Generated by Merchant's server in "Initiate verification"

signature

Generated by Merchant's server in "Initiate verification"

Card number
Security Code (cvv)
Card expiry month
Card expiry year
First name
Last name
Currency

ISO 4217 alpha three-letter code

Loc. Latitude
Loc. Longitude
City
Country
ZIP Postcode
State
Street
Street2
Phone
Order description
Order site Url