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	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 "
}