Linking Payee Accounts APIs

Business Logic

This API includes the following processing logic:

Idempotent Check -- If the account number is already linked with the given customer, the API returns the existing link information. Otherwise, it creates a new record.
- Note: For an external card, an Idempotent check is performed based on Program Code, Customer Token, Account Number, Expiry Month, or Expiry Year.
- For a GreenDot account, an Idempotent check is performed based on Program Code, Customer Token, or Account Token.
Checking Eligibility
- We verify that the target card BIN is eligible for a Fast Funds transfer, using the MasterCard send or Visa Direct gateways, depending on the partner configuration.
- Note: Card will be eligible for fund transfer if receiving eligibility = true and funds availability = IMMEDIATE.
Database Encryption Levels -- These include:
- AccountNumber
- ExpiryMonth
- ExpiryYear
Status
- Link Profile status is InActive upon creating a link for the first time. After creating a successful first transfer, the link status changes to Active.
- Validation can occur on the Expiry month and year while creating/updating the link information.

Link Account

This API is used to create a debit card DPAN or FPAN, or Bank Account and routing number, to link to a customer for receiving funds as a payee or sending funds as a sender.

Syntax/URL

POST /programs/{programCode}/customers/{customerToken}/paymentInstruments

Request

Link Account Request Parameters

Field Name	DataType	Description	Format	Values Allowed	Required	BaaS Requirement
FirstName	String	Account holder’s First name	Min 1 character Max 35 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No	Must be 1 - 35 characters long. Cannot be more than 35 characters
MiddleName	String	Account holder’s Middle name	Min 2 characters Max 35 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No	Must be 2 - 35 characters long. Cannot be more than 35 characters
LastName	String	Account holder’s Last name	Min 1 character Max 35 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No	Must be 2 - 35 characters long. Cannot be more than 35 characters
CardAccount	Card	Card to receive or used to send fund			No
BankAccount	Bank	Bank to receive or used to send fund			No
HandleAccount	Handle	Used to receive funds. Does not result in an encrypted link, rather is tied to this customer profile.			No
NickName	String	The nickname to associate with the link.	Max 35 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No
PayName	String	PayName for partner			No
Address	Address	Address of account holder			No

Card Request Parameters

Field Name	DataType	Description	Format	Values Allowed	Required
AccountNumber	String	PAN number, DPAN or FPAN	Should be 16 digits	0-9	yes
ExpiryMonth	String	MM (01 for Jan, 12 for Dec).	should be 1 to 12	0-9	yes
ExpiryYear	String	YYYY (e.g.: 2016).	should be 4 digits	0-9	yes
Last4PAN	String	last 4 digits of FPAN	should be 4 digits	0-9	no

Bank Account Request Parameters

Field Name	DataType	Description	Format	Values Allowed	Required	BaaS Requirement
ABARoutingNumber	String	Bank Routing number	Should be 9 digits	0-9	yes
AccountNumber	String	Bank Account number	Should be 5-17digits and char and '-'	0-9 "^[A-Z0-9-]+$	yes	5-17
AccountType	String	Bank account type	Char	a-z, A-Z	yes	"checking" or "saving"

Payname or Handle Request Parameters

Field Name	DataType	Description	Format	Required
Email	string	pay to email	email	yes
PhoneNumber	string	pay to phone	phone number	yes

Address Request Parameters

Field Name	DataType	Description	Format	Values Allowed	Required
AddressLine1	String	Address Line 1	Max 255 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No
AddressLine2	String	Address Line 2	Max 255 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No
City	String	City name	Max 50 characters	a-z, A-Z, 0-9, hyphen(-), space, period(.), slash(/), questionMark(?), colon(:), opening paranthesis, closing paranthesis, comma(,), apostrophe('), Plus(+)	No
State	String	Abbreviation of the State (e.g. CA, OH).	should be 2 characters	A-Z, a-z	No
Country	String	ISO 3166-1 alpha-3 Country Code (e.g. USA).	should be 3 characters	A-Z, a-z	No
ZipCode	String	Postal code of the address.	max 5 characters min 5 characters	0-9	No

Request Body

{
  "firstName": "string",
  "lastName": "string",
  "middleName": "string",
   "nickName": "string",
   "PayName": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "country":"string",
    "zipCode": "string"
  },
  "cardAccount":{
  "accountNumber": "string",
  "expiryMonth": "string",
  "expiryYear": "string",
  "last4PAN": "string"
  },
  "bankAccount":{
   "ABARoutingNumber": "string",
   "AccountNumber": "string",
   "BankAccountType": "string"
  },
  "handleAccount":{
    "email": "string",
    "phoneNumber": "string"
  }
}

Fields encrypted request

{
  "salt": "eb6c967d-765a-4b18-9a6e-d4eb4df69efa",
 "encryptedData": {
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExwDdXm5e3P9+/nTAFW5Y+WJahmHhtbRlGwpmtoEJyiQCqBtC8NhQVsIVIq874XwY+8Yzk8LFCcdvoHn4zFwjMA==",
        "publicKeyHash": "PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
        "data": "DfAHBPjSNYP6umhaD9R0K4rNoQZpe/gWjwZs52o="
      }
  }

Response

Response Body

{
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "Success",
    }
  ],
 "customer": {
    "customeToken": "950e4868-9f51-4a08-96a7-fcad96c4458e",   
    "status": "verified"
  },  
  "paymentInstrument": {
    "paymentInstrumentId": "07ea72d8-d4c0-4a2f-a854-8e59b3a7d5e8",
    "status": "InActive",
    "fundsAvailability": "IMMEDIATE",
  }
}

Check Bin Eligibility

API to get Eligibility of Bin.

Syntax / URL

POST /v1/programs/{programCode}/binEligibility

Request

Request Header

Field	Required (Y/N/C)	Description	Format	Values Allowed
ProgramCode	Y	Partner program code	string	a-z, <glossary:A-Z>, hyphen, underscore, 0-9

Request Parameters

Field Name	DataType	Description	Format	Values Allowed	Required	Requirement
Bins	Bin	List of Bin	string	0-9	yes	N/A
Bin	String	Bin	string	0-9	yes	Must be 1 - 8 characters long.

Request Body

{
  "Bins":[
  {
    "Bin":"12345678"
  }
  ] 
}

HTTP Status Codes

HTTP Status Code	Response Message
200	Success
500	Server Error

Response

Response Parameters

Response

Field	Description	Format	Values Allowed
BinEligibleList	list of BinEligible	BinEligible

BinEligible object

Field	Description	Format	Values Allowed
Bin	Bin number	string	a-z, A-Z (Length should be either 6 or 8 )
BinStatus	status of bin	string	a-z, A-Z
bank		string	a-z, A-Z
association		string	a-z, A-Z
Program		string	a-z, A-Z

BinStatus

BinStatus	Description
Eligible	the bin number is available
Ineligible	the bin number is not available
Invalid	the bin number is not valid

Response Body

{
  "bins": [
    {
      "bin": "12345678",
      "binStatus":"Eligible",
      "bank": "Chase Bank",
      "program": "Debit",
      "association":  "Visa"
    }
  ],
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "string"
    }
  ]
}