Generate eGift
Introduction
This operation generates an eGift for any given product configuration. The generateEGift
operation creates an account and wraps it in an eGift object, returning the fully initialized, newly created eGift. It can't be used to send an eGift.
IMPORTANT
Once an eGift is created using a
generateEGift
call, the results of the call include the information used to activate eGifts using the Blackhawk eGift application.
This method is used to generate an EGift for the given product configuration.
Method | Service Name | Service Type |
---|---|---|
POST | eGiftProcessing/v1/generateEGift | Synchronous |
- Post-Production URI:
https://api.certification.blackhawknetwork.com/eGiftProcessing/v1/generateEGift
- Production URI:
https://api.blackhawknetwork.com/eGiftProcessing/v1/generateEGift
Request Header Attributes
All of these header attributes are optional; however, the best practice is to pass the ones marked as required on every request.
Name | Type | Length | Required | Description |
---|---|---|---|---|
requestorId | GUID | 26 | N | The internal identifier for the person making the request. If absent, certificateId would be used by default. |
requestId | String | 50 | Y | The unique identifier of the request. |
contractId | String | 11 | Y | The contract id of the client (aka Merchant ID, MID) |
Request Elements
Name | Type | Length | Required | Description |
---|---|---|---|---|
giftFrom | String | 255 for single byte Char 75 for multi byte Char | N | EGift sender details. |
giftTo | String | 255 for single byte Char 75 for multi byte Char | N | EGift receiver details. |
giftMessage | String | 255 for single byte Char 75 for multi byte Char | N | Gift Message |
giftAmount | Big Decimal | Y | The amount associated with the eGift | |
purchaserId | URI | 255 | N | A reference to the URI of the person who is purchasing the EGift. |
recipientId | URI | 255 | N | A reference to the URI for the recipient person. |
retrievalReferenceNumber | Integer | 12 | Y | Retrieval Reference Number for the EGIFT transaction. To support downstream processing of this value, we require that this field contain only numeric values prefixed with 0’s to complete full length of 12. A unique value per transaction. |
messageReasonCode | String | 99 | N | |
productConfigurationId | GUID | 26 | C | Unique product ConfigurationId that identifies which card is ordered Either upc or productConfigurationId should be provided |
upc | String | 12 | C | BHN product UPC. Default IID must be set up for UPC if upc will be used for product info in request. Either upc or productConfigurationId should be provided |
notes | String | 255 | N | Any notes associated with the last update of the entity |
securityQuestions | String | 75 (db column length 255 for hashed value | N | Security Question and answers tied to eGift |
correlationId | GUID | 26 | N | Correlation id used to correlate the transactions |
analyzeRisk | Boolean | C | Flag to check any fraud activity involved in this EGift transaction. | |
Entity | N | EGiftDetails | ||
Map<String,String> | C | RiskAttributes. Required for Compliance | ||
purchaserInfo | Y | Information regarding Person Purchasing Card
| ||
recipientInfo | User | N | Information regarding Person Receiving Card |
Entity Attribute
Name | Type | Max Length | Required | Description |
---|---|---|---|---|
Name | String | 255 | N | The attribute namePossible allowed UMS values are,"UMS.62.5" for External Order Id (Length cannot exceed 30) "UMS.62.14" for External PO Number (Length cannot exceed 50)"UMS.62.16" for skuId (Length cannot exceed 48) - Restricted-Do not use unless authorization provided by BHN"UMS 62.21" for customerIdentfier (Length cannot exceed 99) "BHNOrderId" (UMS62.4) Internal Customer Id (Length not to exceed 30 characters) - Restricted-Do not use unless authorization provided by BHN"BHNPoNumber (UMS 62.13) Internal Customer PO (Length not to exceed 50 characters) - Restricted-Do not use unless authorization provided by BHN"BHNOrderLineItemId" and "ExternalOrderLineItemId" are also allowed to pass to accountProcessing and persist in account DB (Length cannot exceed 30) |
type | String | 255 | N | This attribute type (String). |
value | String | 255 | N | The attribute value |
Risk Attributes
To leverage BHN's Risk Service for eGift issuance, partner can specify additional optional data points that will be used to analyze the risk involved, and optionally notify or reject the eGift issuance.
To enable risk value added service, DP must first elect to define risk rules. Please reach out to your BHN representative.
Name | Type | Max Length | Required | Description |
---|---|---|---|---|
bhnrisk.user.id | String | C | Unique identifier of the person in the source system | |
bhnrisk.user.emailAddress | String | C | Email Address of the user | |
bhnrisk.correlationId | String | Y | Identifier field which could be used for RRN (retrieval reference number). This field will support velocity rule creation to limit number of transactions allowed per correlation ID in certain time frame to control unexpected fraud attacks. | |
bhnrisk.deviceId | String | C | Key will be the RiskProvider and the value will be the sessionid/blackbox based on the provider. | |
bhnrisk.ipAddress | String | C | IP Address for the transaction | |
bhnrisk.orderId | String | C | A unique identifier for the order | |
bhnrisk.tenderType | String | C | Method used for payment (CREDIT_CARD, DEBIT_CARD, REWARDS_BALANCE, PAYPAL, MASTERPASS, AMEX_CHECKOUT, APPLE_PAY, ANDROID_PAY, VISA_CHECKOUT) |
Best practices
Do not send an empty value or null values. Either a value should be sent or do not send the empty attribute.
User
Name | Type | Max Length | Mandatory | Description |
---|---|---|---|---|
firstName | String | 100 | N | First Name of Person |
lastName | String | 100 | N | Last Name of Person |
addressLine1 | String | 255 | N | Address Line 1 |
addressLine2 | String | 255 | N | Address Line 2 |
city | String | 100 | N | City |
state | String | 100 | Y | State or Province (Required for Purchaser Info)
|
postalCode | String | 10 | C | Postal Code |
countryCode | String | 10 | Y | Country Code (Required for Purchaser Info in ISO 3166 alpha 3 format) |
phoneNumber | String | 20 | N | Phone Number |
emailAddress | String | 100 | N | Email Address |
eGift Redemption Security Questions
Upon viewing the eGift, the user will be prompted with security questions via BHN's eGift presentment application (https://egift.blackhawknetwork.com.)
To enable security questions value added service, DP must first elect to define gift failure action (NO_ACTION, void). Default is NO_ACTION. Please reach out to your BHN representative.
- NO_ACTION: System will continue to prompt user up-to 3 times (per session), randomly selecting 1 or more security questions. No limit. If failed to answer the security questions, eGift shows a generic "Failed Challenge Message". User is allowed to retry by creating a new session.
- VOID: System will continue to prompt user up-to 3 times (per session), randomly selecting 1 or more security questions. If failed to answer the security questions, eGift is voided. Once voided, there is no recovery.
WARNING
There is no option to reset security questions. As a distribution partner It is recommended you persist secret questions and answer to service your customers.
Failed Challenge Message
Your eGift cannot be viewed at this time
The maximum number of attempts has been reached. The resulting action taken against this eGift entity is configurable by each distribution partner intending to utilize the challenge question module. Please reload this eGift to attempt the challenge questions again.
Response Elements
Name | Type | Description |
---|---|---|
eGift | eGift | The fully initialized newly created eGift |
eGift Object
Name | Type | Required | Length | Description |
---|---|---|---|---|
entityId | URI | N | 255 | A reference to the URI for the eGift.For Void eGift, the string at the end of this value should be used to obtain the eGiftId . |
creatorId | String | N | 255 | A reference to the URI for the person that created the entity |
updaterId | String | N | 255 | A reference to the URI for the person that last updated the entity |
createdTimestamp | Date | N | Date and time (UTC) at which the entity got created | |
updatedTimestamp | Date | N | Date and time (UTC) at which the entity was last updated | |
notes | notes | N | 255 | Any notes associated with the last update of the entity |
giftFrom | String | N | 255 | EGift sender email address |
giftTo | String | N | 255 | EGift sender email address |
giftMessage | String | N | 255 | Gift Message |
recipientId | String | N | 255 | A reference to the URI for the recipient person |
accountId | URI | N | 255 | A reference to the URI for the account associated with the EGift |
productConfigurationId | String | Y | 255 | A reference to the URI for the product configuration entity associated with the EGift |
upc | String | Y | ||
giftAmount | String | Y | 255 | The amount associated with the eGift |
giftCurrency | String | Y | 3 | The 3 letter representation of the currency assocated with the eGift amount. eg: USD |
isVoid | Boolean | N | Boolean to indicate whether the eGift is voided or not. Accepted values are true/false | |
offerDetails | OfferDetails | N | The offer details associated with the eGift. | |
purchaserId | String | N | 255 | A reference to the URI for the eGift purchaser |
retrievalReferenceNumber | String | N | 12 | Retrieval Reference Number for the EGIFT transaction. It must be 12 alpha-numeric characters. |
status | Enum | N | 12 | Status of the eGift. |
suspended | Boolean | N | Boolean to indicate if the eGift is suspended. | |
accountNumber | String | N | Card Information Account Set up needed to provide card information in the response. Please reach out to BHN Account Manager for account set up. | |
delayDisplayTill | Date | N | Date and time (UTC) after which the EGift can be displayed to the customer. This value is calculated based on the delayDisplay value passed in the client during the EGift creation. | |
transactionId | String | Y | A unique value assigned by the BHN Transaction System that can be used for Settlement. | |
eGiftDetails | Entity | N | EGiftDetails |
OfferDetails
Name | Type | Required | Length | Description |
---|---|---|---|---|
offerDefinitionId | URI | Y | 255 | A reference to the URI for the eGift |
offerInstanceId | URI | Y | 255 | A reference to the URI for the person that created the entity |
offerAmount | String | Y | 255 | Amount associated with the offer. |
offerCurrency | String | Y | The 3 letter representation of the currency associated with the offer amount. eg: USD |
eGiftDetails
Name | Type | Required | Length | Description |
---|---|---|---|---|
additionalAttributes | List | N | The list of Entity Attribute of the EGift |
Entity Attribute
Name | Type | Required | Length | Description |
---|---|---|---|---|
name | String | N | 255 | The attribute name |
type | String | N | 255 | This attribute type |
value | String | N | 255 | The attribute value |
Error Codes
HTTP Status Code | Error Code | Description |
---|---|---|
400 | egiftprocessing.giftAmount.null | The gift amount is missing in the request |
400 | egiftprocessing.giftAmount.null | The product configuration id is missing in the request |
400 | egiftprocessing.retrievalReferenceNumber.invalid | retrievalReferenceNumber is invalid. It needs to have exactly 12 numeric characters |
400 | egiftprocessing.invalid.contract.id | The contractId passed in the header is invalid. It should not be more than 11 characters in length. |
400 | egiftprocessing.delayDisplay.invalid | The value of delayDisplay passed in the request is invalid. It should not be more than 5 digits in length. |
403 | egiftprocessing.risk.decision.denied | The eGift cannot be generated because of possible fraudulent activity: Risk decision: |
409 | egiftprocessing.risk.service.exception | There was a system error in calling risk processing service. |
409 | egiftprocessing.product.not.found | The productConfigurationId is not set up correctly. It does not have a parent product |
409 | egiftprocessing.account.creation.failed.merchant.data.absent | The client is not on-boarded completely. Merchant information is missing |
409 | egiftprocessing.account.creation.failed.product.not.in.productcatalog | The given productConfigurationId does not belong to any product in the client's product catalog. Client cannot use this productConfigurationId to generate an egift. |
409 | egiftprocessing.account.creation.failed.productline.not.found | The productConfigurationId is not set up correctly. It does not have a parent productLine. |
409 | egiftprocessing.account.creation.failed.transaction.cannot.process | The transaction could not be processed by the provider |
409 | egiftprocessing.account.creation.failed.general.decline | The transaction was declined by the provider |
409 | egiftprocessing.account.creation.failed.card.not.found | The transaction was not fulfilled since the system could get a card |
409 | egiftprocessing.account.creation.failed.invalid.merchant | The client is not authorized to make this transaction. |
409 | egiftprocessing.account.creation.failed.invalid.transaction | The transaction was rejected by the provider indicating it as invalid |
409 | egiftprocessing.account.creation.failed.invalid.amount | The amount passed in the request is not a valid amount for the product. Check baseValueAmount and maxValueAmount of the product to know the amount range |
409 | egiftprocessing.account.creation.failed.exceeds.transaction.count.limit | The transaction was rejected by the provider indicating that the maximum number of transaction limit has reached |
409 | egiftprocessing.account.creation.failed.invalid.expiration.date | The system could not fetch a valid card |
409 | egiftprocessing.account.creation.failed.transaction.duplicate | The transaction was rejected by the provider indicating it as a Duplicate transaction |
409 | egiftprocessing.account.creation.failed.cannot.route.transaction | The provider had an error in completing the transaction. |
409 | egiftprocessing.account.creation.failed.account.inventory.unavailable | There was no inventory available in the system to generate an eGift for this productConfigurationId |
409 | egiftprocessing.account.creation.failed.product.setup.not.complete | The product is not set up correctly for creating the eGift. |
409 | egiftprocessing.account.creation.failed.ws.provider.invalid.status.code | There was an internal system error in creating a card for the eGift. |
409 | egiftprocessing.account.creation.failed.internal.process.exception | egiftprocessing.account.creation.failed.internal.process.exception |
500 | Internal Server Error | There was an internal system error in processing the request |
502 | There was a timeout in processing the request | |
503 | The service is temporarily unreachable | |
504 | provider.transaction.timeout | There was a timeout in processing the request from the provider side |
Sample Request and Response
{"giftTo":"From",
"giftFrom":"Me",
"giftAmount":"10.11",
"productConfigurationId":"S0SKAYP3QB5LG43KMH72J1WHX3",
"giftMessage" : "happy Birthday",
"analyzeRisk" : "false",
"riskAttributes": {
"bhnrisk.user.id": "vasuki01234",
"bhnrisk.user.emailAddress":"[email protected]",
"bhnrisk.correlationId" : "WP5H9NGGY0L28YKAJKHTJ2X4YB"
},
"purchaserInfo" : {
"firstName": "vasuki01234",
"lastName":"[email protected]",
"addressLine1" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"addressLine2" : "6220 Stoneridge mall rd",
"city" : "Pleasanton",
"state" : "CA",
"postalCode" :"97231",
"countryCode" : "USA",
"phoneNumber" : "28746187123 ",
"emailAddress" : "[email protected]"
},
"recipientInfo" : {
"firstName": "vasuki01234",
"lastName":"[email protected]",
"addressLine1" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"addressLine2" : "6220 Stoneridge mall rd",
"city" : "Pleasanton",
"state" : "CA",
"postalCode" :"97231",
"countryCode" : "USA",
"phoneNumber" : "28746187123 ",
"emailAddress" : "[email protected]"
},
"eGiftDetails" : {
"additionalAttributes" : [
{
"name" : "UMS.62.14",
"type" : "String",
"value" : "ExternalPONumber20191010"
} ,
{
"name" : "UMS.62.5",
"type" : "String",
"value" : "ExternalOrderId20191010"
},
{
"name" : "BHNOrderLineItemId",
"type" : "String",
"value" : "BHNOrderLineItemId20191010"
} ,
{
"name" : "UMS.62.16",
"type" : "String",
"value" : "ExternalSKU20191010"
},
{
"name" : "BHNOrderId",
"type" : "String",
"value" : "Testing-Prod"
},
{
"name" : "ExternalOrderLineItemId",
"type" : "String",
"value" : "BHNOrderId20191010"
},
{
"name" : "BHNPoNumber",
"type" : "String",
"value" : "Testing-Prod"
}
]}}
{
"giftTo":"giftTo",
"giftFrom":"giftFrom",
"giftMessage":"giftMessage",
"giftAmount":15.00,
"delayDisplay":10,
"purchaserId":"34LRDGQCG1F4NT6GG384ZMQJ14",
"retrievalReferenceNumber":"000000433012",
"productConfigurationId":"F46ZJQ81TAVSNSARNLJD49B7T0",
"notes":"Creating my first egift",
"analyzeRisk" : "false",
"productConfigurationId" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"securityQuestions":{
"What is your favorite car":"SUV",
"What is your favorite food":"burger ",
"What is your favorite place":"hawaii"
},
"riskAttributes": {
"bhnrisk.user.id": "abcd111",
"bhnrisk.user.emailAddress":"[email protected]",
"bhnrisk.user.correlationId" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"bhnrisk.deviceId":"234234235",
"bhnrisk.ipAddress":"324234235",
"bhnrisk.orderId":"WP5H9NGGY0L28YKAJKHTJ2X4YB",
"bhnrisk.tenderType":"ONLINE_BANKING"
},
"eGiftDetails" : {
"additionalAttributes" : [
{
"name" : "UMS.62.14",
"type" : "String",
"value" : "additionalAttributes012"
} ,
{
"name" : "UMS.62.5",
"type" : "String",
"value" : "additionalAttributes013"
},
{
"name" : "BHNOrderLineItemId",
"type" : "String",
"value" : "OrderId123"
} ,
{
"name" : "UMS.62.16",
"type" : "String",
"value" : "OrderIdValidation"
},
{
"name" : "BHNOrderId",
"type" : "String",
"value" : "OrderIdValidation"
}
]
}
}
}
HTTP/1.1 200 OK
Date: Fri, 08 Mar 2013 16:22:33 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 840
Connection: Keep-Alive
{
"entityId" : "https://apipp.blackhawknetwork.com/eGiftManagement/v1/eGift/MN1NFG1DV8AKA1LTFNBLJ417GH",
"creatorId" : "PDM4PDZ0PDNQBGWMVGMRVTK9DM",
"updaterId" : "PDM4PDZ0PDNQBGWMVGMRVTK9DM",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000",
"transactionId" : "DH3WJ9NX04N5K1QZV83F1T2XLW",
"giftFrom" : "Me",
"giftTo" : "From",
"giftMessage" : "happy Birthday",
"accountId" : "https://apipp.blackhawknetwork.com/accountProcessing/v1/getAccount?accountId=6TAFFN6SPA2AHNZ7BDYAWZZWLM",
"retrievalReferenceNumber" : "011014073946",
"productConfigurationId" : "S0SKAYP3QB5LG43KMH72J1WHX3",
"giftAmount" : 10.11,
"giftCurrency" : "USD",
"status" : "ACTIVATED",
"suspended" : false,
"riskScore" : -2,
"hasBeenViewed" : false,
"eGiftDetails" : {
"additionalAttributes" : [
{
"id" : "0RLQCGYSLTS7R42TGY1XC5VKF8",
"name" : "UMS.62.14",
"type" : "String",
"value" : "ExternalPONumber20191010",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "CBK86B1TDN9T0ZQHMDH69PFS5M",
"name" : "UMS.62.5",
"type" : "String",
"value" : "ExternalOrderId20191010",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "4WYWWPGDVAHQWX9DQVA63Z9NVC",
"name" : "BHNOrderLineItemId",
"type" : "String",
"value" : "BHNOrderLineItemId20191010",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "WTTJF78J6CQKWKMX2YXPYXLJ2R",
"name" : "UMS.62.16",
"type" : "String",
"value" : "ExternalSKU20191010",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "30VA6GDD4MNTVMCLDX7STWP3NW",
"name" : "BHNOrderId",
"type" : "String",
"value" : "Testing-Prod",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "G6J7JJW26WHWRV2344FK4A4ZM0",
"name" : "ExternalOrderLineItemId",
"type" : "String",
"value" : "BHNOrderId20191010",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
},
{
"id" : "M2ATATR9F4MR7QYL1RFF0C3SY0",
"name" : "BHNPoNumber",
"type" : "String",
"value" : "Testing-Prod",
"createdTimestamp" : "2021-03-24T21:39:24.730+0000",
"updatedTimestamp" : "2021-03-24T21:39:24.730+0000"
}
]
},
"upc" : "07675015370",
"purchaserInfo" : {
"firstName" : "vasuki01234",
"lastName" : "[email protected]",
"addressLine1" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"addressLine2" : "6220 Stoneridge mall rd",
"city" : "Pleasanton",
"state" : "CA",
"postalCode" : "97231",
"countryCode" : "USA",
"phoneNumber" : "28746187123 ",
"emailAddress" : "[email protected]"
},
"recipientInfo" : {
"firstName" : "vasuki01234",
"lastName" : "[email protected]",
"addressLine1" : "WP5H9NGGY0L28YKAJKHTJ2X4YB",
"addressLine2" : "6220 Stoneridge mall rd",
"city" : "Pleasanton",
"state" : "CA",
"postalCode" : "97231",
"countryCode" : "USA",
"phoneNumber" : "28746187123 ",
"emailAddress" : "[email protected]"
}
}
//Bad sample//
{
"giftTo": "",
"giftFrom": "",
"giftMessage": "",
"giftAmount": 15,
"productConfigurationId": "DTBYHMP9589GFL9W4BFRK25MJP",
"eGiftDetails": {
"additionalAttributes": [
{
"name": "UMS.62.5",
"type": "String",
"value": "PO3700001328_15_200"
},
{
"name": "UMS.62.14",
"type": "String",
"value": ""
},
{
"name": "BHNOrderLineItemId",
"type": "String",
"value": "01B5G7882Z1N77STXA4GTJBFT4"
},
{
"name": "BHNOrderId",
"type": "String",
"value": "GPB1FJ3QPAY72AK05R6JDBVTVH"
}
]
},
"analyzeRisk": false
}
Updated 4 days ago