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.

Create Transfer

Create a transfer API to unify customer creation, account linking, setup linkage, and transfer in one.

Syntax / URL

POST /programs/{programCode}/transfers

Request

Request Parameters

Field	DataType	Description	Required
transferIdentifier	GUID	If the transaction is initiated through the Transfers API, the transferIdentifier that uniquely identifies the initiating transfer is included.	yes
transferType	TransferType	Two new transfer types to be added for Harmony: InPerson P2P (enables no linked target identifier to be provided, only allows transferendpointtype to be “card” Visa+Send (enables a Visa+ payname link to be in the target identifier field). Routes to Fiserv endpoint for Harmony program code. existing Transfer type “PartnerP2P” should be used for remote / offline P2P between two Samsung Wallet users	yes
partnerReferenceData	string	Optional. When a valid disbursementExternal is processed, the partner can optionally provide information in the partnerReferenceData field which can be matched to the funding transfer request along with the corresponding transaction. Upon request, the partnerReferenceData can be included in the settlement report. Note: Including the partnerReferenceData field in the request enables the partner to cross reference the report information with internal records.	no
Initiator	string	This field contains the ID of the funding source account.	no
transferRoute	TransferRoute	Contains the information for a POST Transfer call involving a new source and target.	yes
fraudData	FraudData	Additional information for dealing with charge backs. The following data field are now identified and confirmed with Harmony and Fraud teams to be passed in this field: - "PIN" or "FINGERPRINT" as String - Samsung wallet creation date - Device Hardware ID - Last 4 digits of the phone number. - UTC Timestamp of the last spend date with this card in the wallet (sender) - UTC Timestamp of the Card provisioning on the Wallet	no

Elements in FraudData

Field	DataType	Description	Required
AuthenticationType	string	Type of the Authentication user did in device to initiate the transfer. "PIN" or "FINGERPRINT" as String As of now, only these values are allowed: “PIN” ”FINGERPRINT”	no
WalletCreationDate	DateTime	Samsung wallet creation date DateTime in UTC format when the transaction Wallet was created	no
DeviceID	string	Device Hardware ID	no
Last4Phone	string	last 4 digits of the phone number	no
LastSpendDate	DateTime	UTC Timestamp of the last spend date with this card in the wallet (sender)	no
CardProvisioningDate	DateTime	UTC Timestamp of the Card provisioning in the Wallet	Note: one of these needed: TargetTransferEndpoint.identifier, or encryptedGFTProfile, or encryptedCustomer

TransferRoute

Field Name	DataType	Description	Required
transactionAmount	string	Contains the amount to transfer.	yes
transactionDescription	string	Description display in both source and target transaction history	no
sourceTransferEndpoint	TransferEndpoint	Represents the source of the funds. Will be the cardlink to the preferred debit card in the Samsung wallet.	no
targetTransferEndpoint	TransferEndpoint	Represents the target of the funds. Will be DPAN data or linked account ID for Samsung P2P or remotely P2P	no
eCommTransactionIdentifier	string	This is an option field where partner will pass it to us to relate to Fiserv to send to Visa/MC. In case of P2P or Remote P2P this will be passed from Samsung.	Conditional
encryptedCardAuthenticationData	encryptedCardAuthenticationData	Whenever Sender value is DPAN then cryptogram value will be passed in this encrypted format and is Mandatory.	Conditional

TransferEndpoint

Field Name	DataType	Description	Required
transferEndpointType	TransferEndpointType	Represents the target type of the funds transfer.	Yes
Identifier	GUID	Target linked account ID if a linked account, or blank and replaced with card data blob for in-person P2P with the target DPAN/FPAN and expiration date	Conditional
currency	Only USDis supported at this time.		Yes
encryptedPaymentInstrument	encrypted card data. See PaymentInstrument		No
encryptedCustomer	encrypted user data. See Customer		No

TransferType
InPersonP2P

TransferEndpointType	P2P Type
Card	P2P Target
Account	P2P Source

FraudData

"fraudData": {    
    "authenticationType": "PIN",    
    "walletCreationDate": "2024-11-21T07:40:55.543Z",    
    "deviceID": "string",    
    "last4Phone": "string",    
    "lastSpendDate": "2024-11-21T07:40:55.543Z",    
    "cardProvisioningDate": "2024-11-21T07:40:55.543Z"  
}

CardAuthenticationData

Field Name	DataType	Description	Format	Values Allowed	Required	Notes
cardHolderAuthenticationVerification	String	This is the cryptogram value which is generated based on Fiserv specification related to MasterCard/Visa.	28 characters	Base64 encrypted string	Conditional	If the Value of the card passed in Transfer is the DPAN then this is Mandatory. Example Plain text value before encryption as in the Transfer API payload under encryptedCardAuthenticationData "cardAuthenticationData": { "cardHolderAuthenticationVerification": "AAABBJg0VhI0VniQEjRWAAAAAAA="},

Example of request of Harmony in-person P2P mobile phone tap to Transfer

 
{
  "transferIdentifier": "27e91d46-d103-4f26-a4a8-2d823fcf2523",
  "transferType": "InPersonP2P",
  "initiator": "", -- customer token, PIID 
  "partnerReferenceData": "",
  "transferRoute": {
    "transactionAmount": "99",
    "transactionDescription": "Samsung P2P",
    "sourceTransferEndpoint": {
      "transferEndPointType": "account",
      "identifier": "e4b06240-b719-4c76-87c3-961f515e33eb",  -- Samsung source linked DPAN ID in Wallet
      "currency": "USD",
      "ecommTransactionIndicator": "07",
      "encryptedCardAuthenticationData": {
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExwDdXm5e3P9+/nTAFW5Y+WJahmHhtbRlGwpmtoEJyiQCqBtC8NhQVsIVIq874XwY+8Yzk8LFCcdvoHn4zFwjMA==",
        "publicKeyHash": "PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
        "data": "DfAHBPjSNYP6umhaD9R0K4rNoQZpe/gWjwZs52o="
        }
    }
    "targetTransferEndpoint": {
      "transferEndPointType": "card",
      "identifier": "",  --- this is empty for mobile tap pay transfer
      "currency": "USD",
      "encryptedpaymentInstrument": {
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExwDdXm5e3P9+/nTAFW5Y+WJahmHhtbRlGwpmtoEJyiQCqBtC8NhQVsIVIq874XwY+8Yzk8LFCcdvoHn4zFwjMA==",
        "publicKeyHash": "PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
        "data": "DfAHBPjSNYP6umhaD9R0K4rNoQZpe/gWjwZs52o="
      }      
   }, 
    "fraudData": {    
    "authenticationType": "PIN",    
    "walletCreationDate": "2024-11-21T07:40:55.543Z",    
    "deviceID": "string",    
    "last4Phone": "string",    
    "lastSpendDate": "2024-11-21T07:40:55.543Z",    
    "cardProvisioningDate": "2024-11-21T07:40:55.543Z"  
   }
}

Example of request of Samsung mobile phone remotely P2P Transfer

 
{
  "transferIdentifier": "27e91d46-d103-4f26-a4a8-2d823fcf2523",
  "transferType": "PartnerP2P",
  "initiator": "", -- customer token, PIID 
  "partnerReferenceData": "",
  "transferRoute": {
    "transactionAmount": "99",
    "transactionDescription": "Samsung P2P",
    "sourceTransferEndpoint": {
      "transferEndPointType": "account",
      "identifier": "e4b06240-b719-4c76-87c3-961f515e33eb",  -- source linked DPAN ID in sending profile Samsung Wallet
      "currency": "USD",
      "ecommTransactionIndicator": "07",
      "encryptedCardAuthenticationData": {
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExwDdXm5e3P9+/nTAFW5Y+WJahmHhtbRlGwpmtoEJyiQCqBtC8NhQVsIVIq874XwY+8Yzk8LFCcdvoHn4zFwjMA==",
        "publicKeyHash": "PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
        "data": "DfAHBPjSNYP6umhaD9R0K4rNoQZpe/gWjwZs52o="
      }
    }
    "targetTransferEndpoint": {
      "transferEndPointType": "account",
      "identifier": "9efce52b-ccf6-4944-bdad-30dd9f41c900",  --- The cardlink of the receiving DPAN ID in receiving profile Samsung Wallet
      "currency": "USD"
     
   }, 
  "fraudData": {
   "authenticationType": "FINGERPRINT",    
    "walletCreationDate": "2024-11-21T07:40:55.543Z",    
    "deviceID": "string",    
    "last4Phone": "string",    
    "lastSpendDate": "2024-11-21T07:40:55.543Z",    
    "cardProvisioningDate": "2024-11-21T07:40:55.543Z"  
    }
}

Response

Response Code

HttpCode: 201

TransferStatus
Pending
Completed
Failed
Declined
Authorized
Voided

Transfer Statuses

Transfer StatusReason	TransferStatus	Http Verb
88	Declined	Post, Get
91	Declined	Post, Get
89	Declined	Post, Get
8	Declined	Post, Get
105	Declined	Post, Get
106 AFTAuthorizedOCTCompleted	Authorized	Post, Get
93	Declined	Post, Get
87	Declined	Post, Get
82	Declined	Post, Get
12	Declined	Post, Get
10	Declined	Post, Get
85	Declined	Post, Get
11	Declined	Post, Get
4	Declined	Post, Get
3	Pending	Post, Get
15 SystemError	Failed	Post, Get
107 TimeoutReversed	Pending(Declined)	Post, Get
22 TransactionDeclined	Declined(Void)	Post, Get
21 TransactionFailed	Failed	Post, Get
104		Post, Get
2 TransferCompleted	Completed	Post, Get
94 TransferVoided	Declined	Post, Get
98 TransferVoidFailed	Declined	Post, Get

Sender

Field Name	DataType	Description	Required
identifier	string	Sender’s customerToken	no
linkId	string	Sender’s linked account id	no
last4PAN	string		no
bank	string		no
association	string		no

Receiver

Field Name	DataType	Description	Required
identifier	string	If DPAN passed has a PPID (Samsung Profile ID), then this is looked up and provided back in this field	no
last4PAN	string		no
bank	string		no
association	string		no
payName	string		no
program	string	“Debit”, “Credit”	no
identifier	string
linkId	string

Completed Transfer response example

HttpCode: 201

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, 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"
    }
  ]
}