Get Card Balance (Verify Account)

Introduction

This API Operation is used to verify a card number/pin and return an Account for the card if it is successfully verified.

Method

Service Name

Service Type

GET

accountProcessing/v1/verifyAccount

Synchronous

URI: https://api.blackhawknetwork.com/accountProcessing/v1/verifyAccount?accountNumber=<Account Number>&productLineId=<productLineIdValue>&accountType=<Account Type>&cvv2=<cvv2>&expirationDate=<Expiration Date>

Request Header Attributes

All three of these header attributes are optional, however, if a client wants idempotency support then they should specify all three on every request.

Name

Type

Required

Length

Description

requestorId

String

N

A value defined by the client application that can be used to uniquely identify that client application. If the client application does not specify a value, a globally unique identifier will be filled in automatically.

requestId

String

N

A value defined by the client application that can be used to uniquely identify that specific request from the client. This value should be set if the client application wants to take advantage of an idempotent operation on a service.

previousAttempts

Integer

N

The number of times this same request has been attempted unsuccessfully before. A value that is greater than zero will cause the service to view this request as a retry attempt and it will be treated idempotently.

Request Elements

Name

Type

Required

Length

Description

accountNumber

String

Y

Account Number of the account (Card Number/Phone Number)

productLineId

String

Y

Internal identifier of the product line

pin

String

C

Security pin of the account

accountType

AccountType

Y

Type of the account

cvv2

Integer

C

cvv2 code (For Open Loop / VPLN products)

expirationDate

Date

C

Expiration Date in MMYYYY format (For Open Loop / VPLN products)

C - Conditional. Product type will dictate if conditional values are needed.

AccountType

Enumeration values: CREDIT_CARD, GIFT_CARD, LOYALTY_CARD, PHONE_CARD

Response Elements

Name

Type

Description

account

AccountInformation

The requested account information

AccountInformation

Name

Type

Length

Description

entityId

URI

255

A reference to the URI for the account information

creatorId

URI

255

A reference to the URI for the person that created the entity

updaterId

URI

255

A reference to the URI for the person that last updated the entity

notes

String

255

Any notes associated with the last update of the entity

createdTimestamp

Date

The date and time (UTC) that the entity was created

updatedTimestamp

Date

The date and time (UTC) that the entity was last updated

type

AccountType

50

Type of Account

accountNumber

String

255

Account Number of the account (Card Number / Phone Number)

securityCode

String

255

Security Pin of an Account

productLineId

URI

26

Reference to the URI of the Product Line

productId

URI

255

Reference to the URI of the Product

balance

BigDecimal

(19,2)

Current Balance on the account

balanceAsOf

Date

Date and time for last successful balance inquiry.

isBalanceStale

Boolean

The flag to indicate whether the balance is stale (cached). If balance inquiry failed, will be true; if it succeeded, false.

currency

String

3

Account currency

activationAccountNumber

String

255

Number used to activate the account (card number or phone number)

activationAmount

BigDecimal

(19,2)

Amount on account while activating

activationTimestamp

Date

The date and time (UTC) when the account was activated

activationLocation

String

255

Location of activation

expirationDay

Integer

1 - 31

Expiration day of the account

expirationMonth

Integer

1 - 12

Expiration month of the account

expirationYear

Integer

Expiration year of the account

additionalRedemptionData

String

15

Additional redemption data for the account

status

AccountStatus

12

Status of the account

barCodeValue

String

255

BarCode value of the card

AccountStatus

NEW, ACTIVATED, CLOSED

Error Codes

HTTP Status Code

Error Code

Description

400

bhn.com.service.request.missing.parameter

Parameter missing in request

409

transaction.cannot.process,
invalid.merchant,
invalid.transaction,
invalid.expiration.date,
card.not.found,
invalid.phone.number,
invalid.pin,
card.expired,
exceeds.transaction.count.limit,
transaction.timeout,
cannot.route.transaction

Transaction status not in approved state

409

productline.not.found

Product line not found in the system

409

productLine.setup.not.complete

Internal BI systems are not configured for balance inquiry

409

cvv2.is.required

cvv2 is required for balance inquiry (Reserved for Future Release for Open Loop / VPLN products)

409

expirationDate.is.required

expirationDate is required for balance inquiry (Reserved for Future Release for Open Loop / VPLN products)

504

provider.transaction.timeout

Underlying systems not responding while refreshing the balance

Sample Request and Response

GET https://api.blackhawknetwork.com/accountProcessing/v1/verifyAccount?accountNumber=11213456789014&productLineId=GH72LJBSJVP8BG4YXX652P4KYC&accountType=GIFT_CARD&cvv2=123&expirationDate=012020
HTTP/1.1
Content-Type: application/json; charset=UTF-8
Accept: application/json; charset=UTF-8
Host: api.blackhawknetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2 (java 1.5)
HTTP/1.1 200 OK Server: Apache-Coyote/1.1
Date: Tue, 24 Sep 2013 20:20:56 GMT
Content-Type: application/json
Content-Length: 293
{
    "entityId": "ZGJ8P01VXL19D848K4TG79QKHC",
    "updatedTimestamp": "2013-09-24T19:22:13.753+0000",
    "type": "GIFT_CARD",
    "accountNumber": "11213456789014",
    "securityCode": "1234",
    "productLineId": "GH72LJBSJVP8BG4YXX652P4KYC",
    "balance": 25,
    "balanceAsOf": "2014-05-14",
    "isBalanceStale": false,
    "currency": "USD",
    "status": "ACTIVATED",
    "barCodeValue" : "6270672650222277"
}

Did this page help you?