Redeem Value

Introduction

This API Operation is used to redeem an account with given amount.

Method

Service Name

Service Type

POST

accountProcessing/v1/redeem

Synchronous

URI: https://api.blackhawknetwork.com/accountProcessing/v1/redeem

Request Header Attributes

Note that the attributes requestorId, requestId, and previousAttempts 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

Description

accountId

GUID

Y

The internal identifier of the account

amount

Big Decimal

Y

Amount to redeem

currency

String

Y

Currency for transaction

transactionTime

Date String

N

Date of the transaction

retrievalReferenceNumber

String

N

Retrieval reference number

storeNumber

String

N

Store number

terminalNumber

String

N

Terminal number

baseTransactionId

String

N

Transaction ID used to correlate multiple transactions

taxAmount

Big Decimal

N

Tax amount

transactionFee

Big Decimal

N

Transaction fee

messageReasonCode

messageReasonCode

N

The reason code

transactionDescription

String

N

Description of the transaction. A bill payee name that's passed to replace the merchant name/location in Blackhawk Network. Maximum of 40 alphanumeric characters

MessageReasonCode

Enumeration values: PHONE_TOP_UP, PURCHASE_DIGITAL_ACCOUNT, BILL_PAYMENT_IMMEDIATE_DELIVERY, BILL_PAYMENT_REGULAR_MAIL_DELIVERY, BILL_PAYMENT_EXPEDITED_MAIL_DELIVERY, MERCHANDISE_RETURN

Response Elements

Name

Type

Descriptipon

accountTransaction

accountTransaction

Account transaction response object

Error Codes

HTTP Status Code

Error Code

Description

400

accounts.maxsize.exceeded

Number of accounts in the request exceeded the maximum allowed

400

accounts.minsize.exceeded

Number of accounts in the request below minimum required

400

amount.null

Amount is null in the request

400

amount.negative

Amount is negative in the request

400

retrievalReferenceNumber.invalid

Retrieval reference number in the request is invalid

400

storeNumber.invalid

Store number in the request is invalid

400

terminalNumber.invalid

Terminal number in the request is invalid

400

account.redeem.values.request.accounts.different.productlineids

Accounts in redeem values belong to different product lines

409

productline.not.found

Product line not found in the system

409

product.not.found

Product ID associated to the product line is not found in the system

409

productLine.setup.not.complete

The product line passed in the request is not set up completely for a balance inquiry

409

account.does.not.exist

No account found for account ID

504

provider.transaction.timeout

Underlying systems not responding

Sample Request and Response

POST /accountProcessing/v1/redeem HTTP/1.1
User-Agent: curl/7.23.1 (x86_64-pc-win32) libcurl/7.23.1
Host: api.blackhawknetwork.com
Accept: */*
requestorId: YKGVJGPTWC7TPWGPA3KJ2FX01R
Content-Type: application/json; charset=UTF-8
Content-Length: 117
{
   "accountId":"FAXF46GSGX3VTP34Y28YXRBWL4",
   "amount":"10.00",
   "currency":"USD",
   "taxAmount":"0.09",
   "transactionFee":"1.11",
   "messageReasonCode":BILL_PAYMENT_IMMEDIATE_DELIVERY",

   "transactionDescription":"some_bill_payee_name"

}
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Date: Wed, 12 Sep 2012 22:38:51 GMT
Content-Type: application/json
Content-Length: 220
{
   "transactionId":"4J8R86RWKGT34DWLNF8XJ6LB7M",
   "accountId":"https://api.blackhawknetwork.com/accountProcessing/v1/getAccount?accountId=FAXF46GSGX3VTP34Y28YXRBWL4",
   "timestamp":"2012-08-29T14:14:41.070+0000",
   "description":"Balance available",
   "requestedAmount":10.00,
   "approvedAmount":10,
   "resultingBalance":0.00,
   "currency":"USD",
   "authorizationCode":"000012",
   "transactionStatus":"APPROVED",
   "transactionType":" REDEMPTION "
}

Did this page help you?