Instant Issue Funding

Introduction

The submitAnonymousInstantIssueFunding call is used to fund and register a physical instant issue open loop card.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitAnonymousInstantIssueFunding→ Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter.

URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitAnonymousInstantIssueFunding

Instant Issue Funding Request

To send the request to fund and register the anonymous instant issue card the following values must be sent in the request header:

Parameter

Description

Type

Required

Default Value

merchantId

The Merchant ID (MID) is a string identifier, provided to you by your account manager that varies based on the product type you are ordering.

String

Yes

None

requestId

A unique identifier for each order provided by you (the caller).

String

Yes

None

millisecondsToWait

Provide a value between 0 - 30000 to indicate how long your application or service will wait for a response. Once this time is exceeded the request will become asynchronous.

Integer

No

2000

In our example we sent the following values in the header:

merchantId: 1234
requestId: 20210526T135001
millisecondsToWait: 30000

In the body of the POST request you will need to send all the information needed to complete the funding and registration for each card.

Attribute

Description

Type

Required

Allowed Values

clientProgramNumber

The client program number for the client program you are placing your order under.

Integer

Yes

Must be a valid client program number / quote number assigned to you.

paymentType

Must be a valid client program number / quote number assigned to you.

String

No

DRAW_DOWN

poNumber

PO numbers must be 50 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space, period and hyphen.

orderDetails

The cards you wish to fund and register

Object

Yes

Providing the Order Details

Here you will pass the required information for all the cards you would like to fund and register.

Parameter

Description

Type

Required

Example

amount

The value the card should be loaded with.

Number

Yes

Digits 0-9 and period.

May not contain symbols and may have up to two digits after the decimal separator.

Example: 225.50

recipient

Information about the recipient for this gift card. This is the information used for registering the card.

Object

Yes

Valid Recipient Object.

Providing the Recipient Information

The information you provide in the recipient object will be registered to the card.

Attribute

Description

Type

Required

Allowed Values

proxyNumber

The proxy number for the card that needs to be funded and registered.

String

Yes

A valid proxy number issued by Blackhawk Network.

firstName

First name of the recipient, this must be 25 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

lastName

Last name of the recipient, this must be 25 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

email

The email address of the individual recipient. Must be 50 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), period and hyphen.
Format: Must have an @ symbol and at least one period.

phoneNumber

Recipient phone number.
Formatting:
(1) Include numbers only, no spaces, hyphens or parenthesis.
(2) Must be 10 digits.
(3) For North American phone numbers do not include the leading "1".

String

No

Digits 0-9

address

Specifies the physical address of the recipient.

Object

Yes

Valid Address Object.

Specifying the Recipient Address

You need to provide the physical address for each card holder.

Attribute

Description

Type

Required

Allowed Values

line1

First line of the recipient's address. This must be 35 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), and apostrophe.

line2

Second line of the recipient's address. This must be 35 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), and apostrophe.

city

City must be 35 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe.

region

Address region must be a valid 2-character uppercase abbreviation for a U.S. state or a Canadian province or contain an international region less than 36 characters.

String

Yes

A valid 2-character uppercase abbreviation for a U.S. state or a Canadian province or contain an international region less than 36 characters.

postalCode

Postal code must be 10 characters or less.

String

Yes

Digits 0-9 and alpha (a-z, A-Z).

For US addresses this must include the five digit US ZIP Code only.

postalCodeExt

Postal code extension must be 4 characters or less.

String

No

Digits 0-9

country

Country must be the 3 alphabetic ISO code corresponding to the country.

String

Yes

Three character alphabetic ISO code corresponding to the country.

For example the JSON might look like this:

"address": {
    "line1": "700 State Highway 121 Byp",
    "line2": "Ste. 200",
    "city": "Lewisville",
    "region": "TX",
    "postalCode": "75067",
    "country": "USA"
}

Combining that with the rest of the recipient information gives the following JSON:

"recipient": {
    "proxyNumber": "1234567890123456789",
    "firstName": "Michael",
    "lastName": "Mouse",
    "address": {
        "line1": "700 State Highway 121 Byp",
        "line2": "Ste. 200",
        "city": "Lewisville",
        "region": "TX",
        "postalCode": "75067",
        "country": "USA"
    },
    "phoneNumber": "1231231234",
    "email": "[email protected]"
}

Combining that with the order line item information gives:

"orderDetails": [{
    "recipient": {
        "proxyNumber": "1234567890123456789",
        "firstName": "Michael",
        "lastName": "Mouse",
        "address": {
            "line1": "700 State Highway 121 Byp",
            "line2": "Ste. 200",
            "city": "Lewisville",
            "region": "TX",
            "postalCode": "75067",
            "country": "USA"
        },
        "phoneNumber": "1231231234",
        "email": "[email protected]"
    },
    "amount": "25"
}

You can fund and register multiple cards at once by including multiple line items in the orderDetails object.

"orderDetails": [{
    "recipient": {
        "proxyNumber": "1234567890123456789",
        "firstName": "Michael",
        "lastName": "Mouse",
        "address": {
            "line1": "700 State Highway 121 Byp",
            "line2": "Ste. 200",
            "city": "Lewisville",
            "region": "TX",
            "postalCode": "75067",
            "country": "USA"
        },
        "phoneNumber": "1231231234",
        "email": "[email protected]"
    },
    "amount": "25"
},
{
    "recipient": {
        "proxyNumber": "1234567890123456000",
        "firstName": "Daffy",
        "lastName": "Duck",
        "address": {
            "line1": "4444 Centerville Rd",
            "line2": "",
            "city": "White Bear Lake",
            "region": "MN",
            "postalCode": "55127",
            "country": "USA"
        },
        "phoneNumber": "1231231234",
        "email": "[email protected]"
    },
    "amount": "25"
}]

Submitting the Order

Now you have all the components constructed you can place the funding and registration order using the JSON assembled above.

Here is the final JSON we will be submitting in the order request:

{
    "clientProgramNumber": "43287998",
    "paymentType" : "DRAW_DOWN",
    "orderDetails": [{
        "recipient": {
            "proxyNumber": "1234567890123456789",
            "firstName": "Michael",
            "lastName": "Mouse",
            "address": {
                "line1": "700 State Highway 121 Byp",
                "line2": "Ste. 200",
                "city": "Lewisville",
                "region": "TX",
                "postalCode": "75067",
                "country": "USA"
            },
            "phoneNumber": "1231231234",
            "email": "[email protected]"
        },
        "amount": "25"
    },
    {
        "recipient": {
            "proxyNumber": "1234567890123456000",
            "firstName": "Daffy",
            "lastName": "Duck",
            "address": {
                "line1": "4444 Centerville Rd",
                "line2": "",
                "city": "White Bear Lake",
                "region": "MN",
                "postalCode": "55127",
                "country": "USA"
            },
            "phoneNumber": "1231231234",
            "email": "[email protected]"
        },
        "amount": "25"
    }]
}

After submitting our request we will receive one of the following HTTP responses:

HTTP Status Code

Meaning

Notes

201

Operation Complete

If isCompleted is not equal to "true" and percentComplete is not 100 the order has not completed.

202

Operation is in Process

If isCompleted is not equal to "true" and percentComplete is not 100 the order has not completed.

4XX

Invalid Request

Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly.

5XX

System Error

Blackhawk Network encountered an internal error.

Success

If the response was successful the following JSON will be returned:

{
    "transactionID": "435LYTF8GAS6NCB3R9TLCXWY30",
    "isCompleted": true,
    "percentComplete": 100,
    "success": true,
    "orderNumber": "401087290"
}

Failure

If the response was not successful an error response object will be returned. The card(s) have not been funded or registered. Review the error response to determine the corrections that are needed.


Did this page help you?