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

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.
Use Person Management APIs to create purchaserId.

recipientId

URI

255

N

A reference to the URI for the recipient person.
Use Person Management APIs to create recipientId.

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

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.

eGiftDetails

Entity

N

EGiftDetails

riskAttributes

Map<String,String>

M

RiskAttributes. Required for Compliance

purchaserInfo

User

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 name

Possible 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

C

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

N

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

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
}

Did this page help you?