Executing Transfers APIs

Create Transfer API

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

Example of request of Harmony Visa+:

{
  "transferId": "27e91d46-d103-4f26-a4a8-2d823fcf2523",
  "transferType": "SendVisa+",
  "initiator": "", -- customer token, PIID 
  "partnerReferenceData": "",
  "transferRoute": {
    "transactionAmount": "99",
    "transactionDescription": "SendVisa+",
    "sourceTransferEndpoint": {
      "transferEndPointType": "account",
      "identifier": "e4b06240-b719-4c76-87c3-961f515e33eb",  -- Samsung source linked DPAN ID in Wallet
      "currency": "USD"
    }
    "targetTransferEndpoint": {
      "transferEndPointType": "payname",
      "identifier": "johndoe.venmo" ()  -- This will be the receiver's payname, does not need to be encrypted.
      "currency": "USD",
      "PayName": "amy.gdc" -- if Payname is not PII data
   }, 
  "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"  
   }
}

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