Reloadable Card Orders

Introduction

Reloadable card ordering allows you to order one or many reloadable physical prepaid cards at the same time.

Ordering Reloadable Cards

You can order reloadable prepaid cards using the following ordering APIs:

When ordering reloadble cards, the recipient id becomes a required field. See Bulk Personalized Prepaid and Individual Personalized Prepaid for more information.

Adding Funds to Reloadable Cards

You can add funding to your reloadable cards using the SubmitFunding API.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitFunding → Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter.

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

HTTP Header

The parameters below can be included in the header of the request:

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 that is provided by you.
This identifier will be used during reconciliation.

The RequestId must be a unique value with a maximum of 50 characters.

String

Yes

None

millisecondsToWait

Provide a value between 0 and 30000 to indicate how long your application or service will wait for a response.

Once this time is exceeded, the request will become asynchronous.

The recommended value is 15000 (15 seconds).

Integer

No

2000

Your header may look similar to the following example:

Content-Type: application/json
merchantId: 60300004707
requestId: 2019-08-22T09:04:11-0600
millisecondsToWait: 30000

Body Parameters

The parameters below can be included in the body of the request:

Parameter

Description

Type

Required

Allowed Values

clientProgramNumber

The client program number supplied by your Account Manager for the program you are placing your order under.

Integer

Yes

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

financialAccountId

The financial account ID (FAID) specifies the financial account associated with your sub-organization to be used for the order.

When a value is provided for financialAccountId, the paymentType attribute is required.

A value for financialAccountId only needs to be provided when there are multiple financial accounts setup for a sub-organization. Your Implementation Project Manager or Account Manager will direct when you need to provide a value in this field.

String

No

Must match a valid financial account ID configured for your sub-organization.

poNumber

PO numbers must be 50 characters or less.

String

No

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

paymentType

The type of payment you wish to use.

Choose one the following values:

  • ACH_DEBIT
  • WIRE_TRANSER
  • DRAW_DOWN

Note: The payment type value provided must match one of the payment types setup on the client program you are placing an order in or your order request will be rejected.

String

No

thirdPartyInfo

Allows you to send end-client information needed for compliance with state and federal regulations.

See Providing the Third Party Information for more information about the parameters in thirdPartyInfo.

Array of objects

No

orderDetails

The products and quantities you wish to order.

See Providing the Order Details for more information about the parameters in orderDetails.

Array of objects

Yes

Providing the Third Party Information

Parameter

Description

Type

Required

Allowed Values

address

Specifies the delivery address for the recipient.

See Address Object for more information about the parameters in address.

Object

Yes

Valid Address Object.

taxId

A valid taxpayer identification number.

Must be a 9-digit number.

String

Yes

Address Object

Parameter

Description

Type

Required

Allowed Values

company

A name or description of the recipient company.

Must be 60 characters or less.

String

No

contact

A recipient contact name or information.

String

No

line1

The first 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.

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.

line3

Use this field to specify an "Attention To:" line. Must be 35 characters or less.

String

No

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

city

The recipient's city.

Must be 30 characters or less.

String

Yes

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

region

The recipient 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

The recipient 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

The recipient postal code extension must be 4 characters or less.

String

No

Digits 0-9

country

The recipient country must be the 3 character alphabetic ISO code corresponding to the country.

String

Yes

Three character alphabetic ISO code corresponding to the country.

With the third party information your JSON may look similar to the example:

"thirdPartyInfo": {
          "address": {
               "company": "Acme Inc. ",
               "contact": "Jane Smith",
               "line1": "300 Alphabet Drive",
               "line2": "string",
               "line3": "string",
               "city": "Detroit",
               "region": "MI",
               "postalCode": "40084",
               "postalCodeExt": "0001",
               "country": "USA"
          },
          "taxId": "123456789"
     }

Providing the Order Details

Parameter

Description

Type

Required

Allowed Values

clientRefId

Unique client reference to identify duplicates. Must be 30 characters or less.

String

No

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

recipient

Contains the id parameter.

The recipient id must be 30 characters or less.

Object

Yes

Valid Recipient Object

amount

Specify the value of the gift card.

Number

Yes

Digits 0-9 and period.

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

Example: 25.00

description

Must be 40 characters or less.

String

No

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

With the order details object, your JSON may look similar to the following example:

"orderDetails": [{
    "clientRefId": "3465125692",
    "recipient": {
        "id": "6582"
    },
    "amount": 50
}

Submitting the Request for Funding

You can now submit the request to fund the reloadable card.

Your final JSON may look similar to the following example, with all the parameters filled:

{
     "clientProgramNumber": 95000915,
     "financialAccountId": "12345",
     "poNumber": "123456123456",
     "orderDetails": [
          {
               "recipient": {
                    "id": "6582"
               },
               "additionalInfo": {
                    "info1": "string",
                    "info2": "string",
                    "info3": "string",
                    "info4": "string",
                    "info5": "string"
               },
               "clientRefId": "3465125692",
               "amount": 50,
               "description": "Reloadable cards"
          }
     ],
     "thirdPartyInfo": {
          "address": {
               "company": "Acme Inc. ",
               "contact": "Jane Smith",
               "line1": "300 Alphabet Drive",
               "line2": "string",
               "line3": "string",
               "city": "Detroit",
               "region": "MI",
               "postalCode": "40084",
               "postalCodeExt": "0001",
               "country": "USA"
          },
          "taxId": "123456789"
     }   
}

Responses

The API will return a response containing an HTTP status code in the header and a JSON object in the body. This response will tell us if the order was successful and if it has been completed or not.

The following table lists details about the possible responses for reloadable card orders:

HTTP Status Code

Description

Notes

201

Operation complete

The request has completed. In this case you will receive an order number.

202

Operation is in process

The request has not yet completed processing and you will not receive an order number.

Your funding request will continue to process asynchronously.

Please use the orderInfo API to check the status of your request.

400

Invalid request

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

If you have any questions reach out to your Account Manager.

409

Conflict

The requestId provided in the header is a duplicate. Each request requires a unique requestId.

5XX

System Error

Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information.

What to do if isCompleted is not true

This happens if the order is still processing and we have exceeded the millisecondsToWait value (or the maximum timeout of 30 seconds). In that case, the JSON in the response returned will indicate that the order has not yet completed and the current percent complete. For example we may see a response like this:

{
   "transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
   "isCompleted": false,
   "percentComplete": 66,
   "success": false
}

When this happens the transaction becomes asynchronous. We need to wait some time and then make an HTTP GET request to orderInfo to see if the order has completed processing.

Next Steps When the Order has Completed Processing

Assuming our order was placed successfully we receive the following JSON in the response:

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

This indicates the order request was successfully processed and the funds will be loaded onto the card.


Did this page help you?