Netspend Disbursement & Payroll


Netspend allows partners to manage their payroll program in real-time. Including employee enrollment, real-time identity verification, linking physical cards to accounts, account status checks, and real-time funding/withdrawals.


API Authentication

All API end-points require an authentication header to included with the request.  See API Authentication


Echo



This command is used to verify connectivity and proper operation of the web server. You can also use this command to measure networking performance by creating an embedded timestamp.

Note: Unlike other commands, the echo command does not have nested parameters. Instead, it just contains a body of text.

-

End-PointMethodContent-Type
/api/v1/netspend/echoPOSTapplication/json

Request

Field

TypeRequiredDescription
textString(100)YText to echo back.

-

Example
{ "text": "Hello World!" }

Response

TypeDescription
String(100)

Text passed in to service.

-

Response
{
	"Hello World!" 
}


Account Status Inquiry



This web service method retrieves the current status information of a cardholder’s account based on the cardholder’s account cash number.

-

End-PointMethodContent-Type
/api/v1/netspend/accountStatusInquiryPOSTapplication/json

Request

FieldTypeRequiredDescription
txRefString(100)YGlobally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.
cashNumberString(10)YA 10-digit customer account number.
locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.

-

Example
{
	"txRef": "0123456789-987456521",
	"cashNumber": "1234567890",
	"locationId": "0123"
}

Response

Field

TypeDescription
txRefString(100)Globally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.
cashNumberString(10)A 10-digit customer account number.
bankString(100)

The bank associated with the account.

routingNumberString(9)

Routing Number.

bankAccountNumberString(30)

The bank account number.

accountBrandString(100)

Brand. (ACE Elite, All-Access, NetSpend, Paypal Prepaid, etc)

tenureInt

(i.e. # days since account was activated)

availableBalanceInt

The account available balance in cents. (Ex: 1356 = $13.56)

accountTypeString(30)

The account types: GPR, PAYCARD, BUSINESS, AWARD, CDDA,
BUSINESS_SUB_ACCOUNT, SmartOne Disbursement

activatedBoolean(5)

The account activation status.

blockedBoolean(5)

The account block status.

firstNameString(100)

The account’s primary owner’s first name.

middleInitialString(1)

The account’s primary owner’s middle initial.

lastNameString(100)

The account’s primary owner’s last name.

originatorBoolean(40)

The account originating distributor.

employeeBoolean(5)

True if the cardholder is an employee of the requesting distributor, False otherwise.

-

Response
{
	"txRef": "0123456789-987456521",
	"cashNumber": "1234567890",
	"bank": "META",
	"routingNumber": "12550",
	"bankAccountNumber": "1234512345",
	"accountBrand": "Netspend",
	"tenure": 123,
	"availableBalance": 8008,
	"accountType": "GPR",
	"activated": false,
	"blocked": true,
	"firstName": "Alan",
	"middleInitial": "M",
	"lastName": "Turing",
	"originator": true,
	"employee": true
}


Create Account



This command is to be used to create a new account. Currently it can only be used to create an account for disbursement and paycards.

-

End-PointMethodContent-Type
/api/v1/netspend/createAccountPOSTapplication/json

Request

ParameterTypeRequiredDescription
requestInfo
txRefString(100)YGlobally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.
locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.
stationIdString(100)N

Station ID to identify the POS terminal origination. Null allowed.

tellerID

String(50)N

Teller ID for the particular teller/employee logged on at the partner.

customerInfo
firstNameString(100)Y

Cardholder’s first name.

middleInitialString(1)N

Cardholder’s middle initial.

lastNameString(100)Y

Cardholder’s last name.

dateOfBirthString(10)Y

Cardholder’s date of birth in. (Format: mm/dd/yyyy)

govtIdTypeIntN

Type of government ID. (2 = Social Security Number)

govtIdCountryCodeString(2)N

String representing country associated with govIdType.

govtIdValueString(50)N

The characters of the actual government ID.

streetAddressString(100)Y

Cardholder’s street address. No P.O. boxes.

aptSuiteString(100)N

Cardholder’s apartment number or suite number.

zipCodeString(5)Y

The cardholder’s address zip code. Can contain dash followed by last 4.

phoneNumber

String(100)N

Cardholders phone number. Recommended format is without any punctuation. 10 digits.

emailString(100)N

Cardholders email address.

shippingStreetAddress

String(100)N

Customer’s shipping street address. When blank, the address above is used for shipping. (Can be P.O. Box)

shippingAptSuite

String(100)N

Apt or Ste for customer’s shipping address. When shippingStreetAddress is blank, this must also be blank or an error is returned.

shippingZipCodeString(5)N

Customer’s shipping zip code. When shippingStreetAddress is blank, this must also be blank or an error is returned.

identityContextInfo
identityContextTypeString(2)N1 = Defined by Cash Number
2 = Defined by Pan
3 = Defined by Pseudo Pan
4 = Defined by Provided Context
identityContextValueString(30)N

Depends on the identityContextType. Either a key that we provide (Provided Context), the swiped PAN, the printed Pseudo Pan or Cash Number.

identityCheckTokenString(36)NToken from performIdentityCheck (optional if identityContextType and identityContextValue provided).
initialCardOrderInfo
orderCardBrandString(50)N

Field is nullable if initialCardInfo category is used.

embossingLine2String(21)N

This is used to add additional information to the card being printed.

initialCardInfo
initialCardTypeString(2)N

1 = Defined by Pan
2 = Defined by Pseudo Pan
3 = Defined by track2
4 = Defined by Cash Number

initialCardString(100)NRequired if initialCardType provided: ie PAN or Pseudo PAN
initialCardEncryptionTypeString(12)NMAGTEK_DUKPT if track 2 is encrypted using Magtek’s DUKPT algorithm.
initialCardKsnString(30)N

Key Serial Number for DUKPT decryption of track2. 

initialLoad
loadAmountIntNLoad amount in cents. (Ex: 1356 = $13.56)
loadTypeString(50)N

Type of load being distributed to card.
Can be one of the following: TIPS, REIMBURSEMENT, RELOAD, PAYROLL, PAYROLL ADVANCE, DEFAULT (if no type).

sourceOfFundsString(50)NIdentifies the source of funds.
Can be one of following: CASH, CHECK, CHECK_BUSINESS, CHECK_GOVBENEFITS, CHECK_INSURANCE, CHECK_IRA, CHECK_MONEYORDER, CHECK_OTHER, CHECK_PAYROLL, CHECK_PERSONAL, CHECK_TAXREFUND, CHECK_TRUST, EFILE, LOAN, LOAN_BANKED, LOAN_INSTALLMENT, LOAN_PAWN, LOAN_PAYDAY, LOAN_TITLE, LOAN_UNBANKED, IRAL, RAL, REFUND_TRANSFER

-

Example
{  
   "requestInfo":{  
      "txRef": "0123456789-987456521",
      "locationId": "0123",
      "stationId": "POS01",
      "tellerID": "Teller003"
   },
   "customerInfo":{  
      "firstName": "John",
      "middleInitial": "H",
      "lastName": "Galt",
      "dateOfBirth": "03/25/1981",
      "govtIdType": 2,
      "govtIdCountryCode": "Us",
      "govtIdValue": "123221234",
      "streetAddress": "123 Main Street",
      "aptSuite": "1300",
      "zipCode": "78701",
      "phoneNumber": "555123456",
      "email": "jgalt@email.com",
      "shippingStreetAddress": "PO Box 123",
      "shippingAptSuite": "675",
      "shippingZipCode": "78701"
   },
   "identityContextInfo":{  
      "identityContextType": "4",
      "identityContextValue": "209",
      "identityCheckToken": "AC15746E9ACDCE120000015A1CB4EE088001"
   },
   "initialCardInfo":{  
      "initialCardType": "1",
      "initialCard": "5189190000000000",
      "initialCardEncryptionType": "",
      "initialCardKsn": "950003000004E62001AB"
   },
   "initialCardOrderInfo":{  
      "orderCardBrand": "GOLD",
      "embossingLine2": "Thank you"
   },

   "initialLoad":{  
      "loadAmount": 1356,
      "loadType": "TIPS",
      "sourceOfFunds": "CASH"
   }
}

Response

FieldTypeDescription
txRefString(100)Globally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.
accountBalanceInt

The current account balance in cents. (Ex: 1356 = $13.56)

accountNumberString(100)

10-digit account number (also called cash number) and can also include a bank prefix.

orderStatusString(100)

This returns the status of a card order.

cipResponseCodesString(100)

A comma-separated string of return codes from the table listed below. Also used to indicate a CIP failure even if real-time CIP is not used to show CIP Failed indicating you can only load only ≤ $1000.00 per FinCen.

identityCheckTokenString(36)

Opaque token representing the results of this identity check
to be used later in commands requiring identity checks

Real-Time ID Check Return Codes

CodeTypeDescription
200CIP VerificationCIP Verification Succeeded
201CIP VerificationCIP Verification Failed
202CIP VerificationMissing Information [Conditionally approved]
203CIP VerificationMissing Information [Conditionally approved] – Manual review, pull missing information; submit to 3rd party check
204CIP VerificationMatch found in OFAC list
205CIP VerificationMatch found in Netspend Blacklist
206CIP VerificationBad Address
207CIP VerificationToo many cards for same ID
208CIP VerificationToo many secondary card owners on the account
209CIP VerificationInvalid Gov ID value
210CIP VerificationInvalid Gov ID Type
211CIP VerificationUnable to verify CIP
212-214CIP VerificationBad DOB, Must be over 18 for primary and secondary cards

-

Response
{
	"txRef": "0123456789-987456521",
	"accountBalance": 1356,
	"accountNumber": "1234567890",
	"orderStatus": "COMPLETE",
	"cipResponseCodes": "200",
	"identityCheckToken": ""
}



Retrieve Direct Deposit Information



This command is used to retrieve the ACH information needed for an account set up with direct deposit.

-

End-PointMethodContent-Type
/api/v1/netspend/getDirectDepositInfoPOSTapplication/json

Request

FieldTypeRequiredDescription
accountNumberString(20)YThe 16-digit PAN or, for existing accounts, the 10-digit account number/cash number. Field is nullable only when track2data is provided.
track2DataString(37)NTrack I or II data (as proof that the card was swiped). Field is nullable only when accountNumber is provided.
locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.

-

Example 1
{
	"accountNumber": "5189190000000000",
	"locationId": "0123"
}
Example 2
{
	"track2Data": "8D62CE262DCEA90EEA17C585616026D8DF9FAE279F74F61C6E4A22FD036BF36E8E3232E29D5C2D5B",
	"locationId": "0123"
}

Response

FieldTypeDescription
bankAccountNumberString(10)

10-digit account number (also called cash number) and can also include a bank prefix.

rdfiString(100)

Routing number.

-

Response
{
	"bankAccountNumber": "12550",
	"rdfi": "12550"
}


Loading Funds



This command is used to load additional funds to eligible card products and existing accounts. To add funds to a cardholder’s savings account, you can now transfer a portion of the load amount from the GPR card to the cardholder’s savings account. The response for loadFunds now also has savingsBalance, which can be printed on the cardholder’s receipt.  

-

End-PointMethodContent-Type
/api/v1/netspend/loadFundsPOSTapplication/json

Request

FieldTypeRequiredDescription
txRefString(100)Y

Globally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.

accountNumberString(20)YThe 16-digit PAN or, for existing accounts, the 10-digit account number/cash number. Field is nullable only when track2data is provided.
track2DataString(37)NTrack I or II data (as proof that the card was swiped). Field is nullable only when accountNumber is provided.
amountIntY

Load amount in cents. (Ex: 1356 = $13.56)

locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.
loadTypeStringNType of load being distributed to card. Can be one of the following: TIPS, REIMBURSEMENT, RELOAD, PAYROLL, PAYROLL ADVANCE (default if request doesn’t contain loadType)
  • Consult with OmniFund regarding the value needed here, if any.

-

Example 1
{
	"txRef": "0123456789-987456333",
	"accountNumber": "5189190000000000",
	"amount": 1356,
	"locationId": "0123"
}
Example 2
{
	"txRef": "0123456789-987456333",
	"track2Data": "8D62CE262DCEA90EEA17C585616026D8DF9FAE279F74F61C6E4A22FD036BF36E8E3232E29D5C2D5B ",
	"amount": 1757,
	"locationId": "0123"
}

Response

FieldTypeDescription
balanceInt

Card balance in cents. (Ex: 1356 = $13.56)

cashNumberString(10)

Customer account number.

savingsBalanceInt

If a non-zero savings transfer amount was requested, savings account balance in cents. (Ex: 1356 = $13.56)

-

Response
{
	"balance": 1356,
	"cashNumber": "1076459821",
	"savingsBalance": 1264
}


Perform Identity Check



This command performs an identity check to fulfill part of Customer Identity Program (CIP) requirements.

-

End-PointMethodContent-Type
/api/v1/netspend/performIdentityCheckPOSTapplication/json

Request

ParameterTypeRequiredDescription
requestInfo
txRefString(100)YGlobally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.
locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.
stationIdString(100)N

Station ID to identify the POS terminal origination. Null allowed.

tellerID

String(50)N

Teller ID for the particular teller/employee logged on at the partner.

customerInfo
firstNameString(100)Y

Cardholder’s first name.

middleInitialString(1)N

Cardholder’s middle initial.

lastNameString(100)Y

Cardholder’s last name.

dateOfBirthString(10)Y

Cardholder’s date of birth in. (Format: mm/dd/yyyy)

govtIdTypeIntY

Type of government ID (2 = Social Security Number)

govtIdCountryCodeString(2)Y

String representing country associated with govIdType.

govtIdValueString(50)Y

The characters of the actual government ID.

streetAddressString(100)Y

Cardholder’s street address. No P.O. boxes.

aptSuiteString(100)N

Cardholder’s apartment number or suite number.

zipCodeString(5)Y

The cardholder’s address zip code. Can contain dash followed by last 4.

identityContextInfo
identityContextTypeString(2)Y1 = Defined by Cash Number
2 = Defined by Pan
3 = Defined by Pseudo Pan
4 = Defined by Provided Context
identityContextValueString(30)Y

Depends on the identityContextType. Either a key that we provide (Provided Context), the swiped PAN, the printed Pseudo Pan or Cash Number.

-

Example
{  
   "requestInfo":{  
      "txRef": "0123456789-987456521",
      "locationId": "0123",
      "stationId": "POS01",
      "tellerID": "Teller003"
   },
   "customerInfo":{  
      "firstName": "John",
      "middleInitial": "H",
      "lastName": "Galt",
      "dateOfBirth": "03/25/1981",
      "govtIdType": 2,
      "govtIdCountryCode": "Us",
      "govtIdValue": "123221234",
      "streetAddress": "123 Main Street",
      "aptSuite": "1300",
      "zipCode": "78701"
   },
   "identityContextInfo":{  
      "identityContextType": "4",
      "identityContextValue": "209"
   }
}

Response

FieldTypeDescription
txRefString(100)

Globally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.

responseCodesString(100)

A comma-separated string of return codes from the table listed below. Also used to indicate failed CIP even if Real-Time CIP is not used to show CIP Failed indicating you need to load only ≤ $1000.00 per FinCen.

identityCheckTokenString(36)

Opaque token representing the results of this identity check
to be used later in commands requiring identity checks

-

Response
{
	"txRef": "0123456789-987456521",
	"responseCodes": "200",
	"identityCheckToken": "AC15746E9ACDCE120000015A1CB4EE088001"
}


Transaction Void



This command is used to void a previous card sale, load or withdrawal transaction. This command will reverse all financial transactions associated with previous command. 

With this command:

  • Voiding a card sale makes the card unusable (this is done to prevent fraud).
  • Voiding a void is not allowed.
  • Voiding a card sale that was followed by another load is not allowed – the load is voided first.
  • Voiding a load that was followed by another load IS allowed ONLY if the resulting balance does not become negative.
  • Cards sales can be voided within 1 hour of the sale.
  • Loads can be voided within 3 hours of the load.

-

End-PointMethodContent-Type
/api/v1/netspend/voidTransactionPOSTapplication/json

Request

FieldTypeRequiredDescription
txRefString(100)Y

Globally unique reference number provided by the partner to identify this transaction. It is recommended that the reference number include a timestamp in milliseconds.

originalTxRefString(100)Y

Original transaction reference identifying the card sale or load transaction to be voided.

locationIdString(100)YStore location ID to identify the sale location. Tracks POS origination.

-

Example
{
	"txRef": "0123456789-987456521",
	"originalTxRef": "0123456789-987456321",
	"locationId": "0123"
}

Response

FieldTypeDescription
balanceInt

Card balance in cents. (Ex: 1356 = $13.56)

cashNumberString(10)

Customer account number.

savingsBalanceInt

If a non-zero savings transfer amount was requested, savings account balance in cents. (Ex: 1356 = $13.56)

-

Response
{
	"balance": 1356,
	"cashNumber": "1076459821",
	"savingsBalance": 1264
}