1. Home
  2. RTF V2 API

RTF V2 API

Last updated: April 20th, 2022

Description

The FV’s RTF service allows you to receive transaction feed. It provides a near real-time vision into the transactions processed by FV. This information can be used for reporting, analytics, and dashboards.

Request Parameters

Y = Required, Y* = Conditional, X = Required when block is present and N = Optional

ClientId and ClientSecret *

A username and password that is valid to be sent in the HTTP Authorization header via “Basic” authorization in each request our system makes.

Property Description Required Type
RTFID

Unique business rule for the data set

Example: RTRule50474

 Y

String, 30
RTFBatchID

Unique batch id generated for each response

Example: 23424

 Y Int
RTFBatchSize

Number of transactions for the batch

Example: 16

 Y

String, 32
RTFBatchTimeStamp

Date time of the batch

 Y

DateTime
RTFReferenceNumber

Unique ID for every transaction from the batch

Example: 07c3e2f4-d726-4e55-b860-2b4ab9243535

 Y

String, 40
TransactionList Array
 .  TokenID

16 - 22 digit Unique Token for the registration. Either Token, or Account number is mandatory

Example: 12345678912345

 Y

String, 22

 .  AccountNumber

Firstview's internal accountnumber

Example: 2000000212140

 N

String, 19

 .  CardNumberlast4

Last four digits of the debit card if applicable

Example: 7187

 N

String, 4
 .  ProductID

Program ID. Firstview internal.

Example: 50475

 Y

Int
 .  ProductName

Program name. Firstview internal

Example: FirstviewTestProduct

 Y

String, 100
 .  StoreID

Store ID. Firstview internal

Example: 63435

 N

String, 5
 .  StoreName

Name of the store. Firstview internal

Example: FirstViewTestStore

 N

String, 100
 .  TokenIDRef

Token of account where claim/payment was justifying the load

Example: 12345678912233

 N

String, 22

 .  TranID

Transaction ID

Example: 1055450477

 Y

Decimal (19,0)

 .  TranLifeCycleUniqueID

Transaction lifecycle id throughout the life of the transaction, including preauth, auth and a reversal

Example: 1055450477

 N

Decimal (19,0)

 .  TranRef

Originator's tran id for any generated transactions. Ex - If the original transaction triggers any fee then system creates an independent fee transaction while stamping TranID of the original transaction in this field

 Y*

Decimal (19,0)

 .  TranRevTgt

Original transaction id for reversals.

 Y*

Decimal (19,0)

 .  TranSource

Transaction module details. (Pre-Authorization, Authorization, API, ACH, Check, Nonmonetary, Aged-Preauthorization,PullPay,PushPay)

Example: NonMonetary

 Y

String, 32

 .  TranTime

Transaction date time

Example: 5/9/2013 23:00:00

 Y

DateTime
 .  TransmissionDateTime

Local date time during the transaction

Example: 5/9/2013 23:00:00

 Y

DateTime
 .  TranStatus

Describes whether the transaction is successful or not

Example: Transaction posted successfully

 Y

String, 55

 .  TranAmount

Transaction Amount

Example: $4.95

 Y

Money

 .  TranCodeInternal

Not Applicable

Example: 2010

 N

String, 8

 .  TranCodeExternal

Transaction code external - shared with the client

Example: 10

 Y

String, 20

 .  TranDescription

Transaction description

Example: 10 = Membership Fee

 N

String, 100

 .  TranIndicator

Describes whether transaction is a Debit, or Credit

Example: Debit

 N

String, 6

 .  CardBalance

Card balance after the transaction

Example: $206.12

 N

Money

 .  OutstgAuthAmount

Auth holding amount after the transaction. Available only on pre-auth transactions.

Example: $0

 N

Money

 .  AvailableBalance

Available balance on the card. Available balance - current balance – outstgauthamount

Example: $206.12

 N

Money

 .  DebitCard

Object

 . .  MessageTypeIdentifier

Indicates whether transaction is a pre-auth, auth or reversal. Available in network transactions. 0100,0120,0121 are pre-authorizations. 0200,0220,0221 authorizations & 0420,0421 represent the reversals

 N

String, 6

 . .  ResponseCode

Transaction response code. Available only on n/w transactions.

N

String, 3

 . .  PinExist

Indicator whether the transaction is pin based. Applicable for n/w transactions. (Yes, or No)

Example: No

 N

String, 3

 . .  MerchantType MCC. Merchant category code. Available only on n/w transactions. N

String, 4
 . .  MerchantName Merchant name where the transaction happened N

String, 25
 . .  MerchantCity Merchant City where the transaction happened N

String, 13
 . .  MerchantState Merchant State where the transaction happened N

String, 3
 . .  MerchantCountry Merchant Country where the transaction happened/td> N

String, 3
 . .  CardAcceptorIdCode Card Acceptor Id Code N

String, 15
 . .  CardAcceptorTerminalID Terminal ID N

String, 15
 . .  RetrievalReferenceNumber Retrieval Reference Number N

String, 12
 . .  SystemTraceAuditNumber SystemTraceAuditNumber N

String, 6
 . .  TranRequestedAmount Transaction original amount, available only on partially approved transactions N

Money
 . .  TranCardExpDate Card expiration date entered when the transaction is initiated (MMYYYY) N

String, 6
 . .  MerchantID Merchant ID N

String, 15
 . Check object
 . .  CheckNumber Check Number N

String, 32
 . .  CheckMemo Memo on the check N

String, 64
 . .  CheckRef1 CheckRef1 N

String, 32
 . .  CheckRef2 CheckRef2 N

String, 32
 . .  CheckRef3 CheckRef3 N

String, 32
 . .  CheckRef4 CheckRef4 N

String, 32
 . ACH object
 . .  ReceipientID Unique ID of recipient Bank. Mandatory when the Token has more than one Recipient DDAs registered Y* String, 10
 . .  TraceNumber Federal Reserve/NACHA Trace number Y* String, 32
 .  HealthCare object
 . .  MemberID Member ID N

String, 16
 . .  ProcessID Process ID N

String, 16
 . .  GroupID Group ID N

String, 16
 . .  SubscriberID Subscriber ID N

String, 16
 . .  PolicyID Policy ID N

String, 16
 . .  PlanType

Plan Type

 N

String, 2
 . .  PhycisianID Physician ID N

String, 16
 . SiteInfo object
 . .  NPI Site NPI (Populate if applicable) N

String, 16
 . ProviderInfo object
 . . ProviderNPI Provider NPI(Populate if applicable) N

String, 16
 . . FirstName Provider First Name(Populate if applicable) N

String, 32
 . . LastName Provider Last Name(Populate if applicable) N

String, 32
 . GeneralInfo object
 . . NDC National Drug Code N

String, 50
 . ClaimsInfo object
 . . BIN Rx BIN number N

String, 32
 . . PCN Processor control number N

String, 32
 . . ClaimNumber Claim Number - Unique Number for the claim N

String, 50
 . . GroupNumber Alternate group number N

String, 25
 . . RxNumber Rx Number N

String, 50
 . . RxDate Rx Date N

DateTime
 . . NDC National Drug Code N

String, 50
 . . MetricQuantity MetricQuantity N

Decimal
 . . DaysSupply Days Supply N

Numeric
 . . PrimaryCopayAmount Patient out of pocket amount N

Decimal
 . . PrimaryAmountPaid Primary payer amount paid N

Decimal
 . . PatientNumber Member number N

String, 50
 . . PatientDOB Patient date-of-birth. N

DateTime
 . . OtherCoverageCode Other Coverage Code (00,01,02,03,04,08) N

String, 22
Reserved object
 .  ReservedField1 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField2 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField3 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField4 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField5 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField6 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField7 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField8 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField9 Reserved for future use. Currently no business logic attached N String, 50
 .  ReservedField10 Reserved for future use. Currently no business logic attached N String, 50

Return Values

Response Handling

The response code sent by the client’s application back to RTF is significant. This code determines how RTF System will proceed with the current message delivery attempt. Our system can perform TWO different functions based on this code: purge the message marking it successful, purge the message marking it as a permanent error, Consult the details below regarding response code actions

  • Code 2xx - Any 200-level response code is a successful response code. The RTF system will consider the record successfully delivered and log any response data returned.

  • Code 200 - OK This response is preferred to indicate success and includes any data to be logged in the response body

  • Code 4xx and 5xx - Any 400-level or 500-level response code will be considered a temporary failure. Any data in the response body will be logged for future reference.
Property Description Type
Status Example: true or false String
Result Object
 .  RTFID

Unique business rule for the data set

Example: RTRule50474

String, 30
 .  RTFBatchID

Unique batch id generated for each response

Example: 23424

 Int
 .  RTFBatchSize

Number of transactions for the batch

Example: 16

String, 32
 .  RTFBatchTimeStamp

Date time of the batch

DateTime
 .  RTFReferenceNumber

Unique ID for every transaction from the batch

Example: 07c3e2f4-d726-4e55-b860-2b4ab9243535

String, 40
 .  APIResponseCode Code:       Description
1             Success
2             Authentication failed
3             Access/Permission denied
6             Error while processing RTF request
7             Batch Transaction Count is zero

String, 2
 .  APIReasonDescription Code:       Description
1             Success
2             Authentication failed
3             Access/Permission denied
6             Error while processing RTF request
7             Batch Transaction Count is zero

String, 40
 .  error

short error message if any

Applicable only to APIResponseCode is 2 & 3

String, 30
 .  description

long error message if any

Applicable only to APIResponseCode is 2 & 3

String, 50

REST

Method: POST

Urls:

Production: TBD
SandBox: TBD

JSON Request:
{
    "RTFID": {},
    "RTFBatchID": {},
    "RTFBatchSize": {},
    "RTFBatchTimeStamp": {},
    "RTFReferenceNumber": {},
    "TransactionList": [
        {
            "TokenID": {},
            "AccountNumber": {},
            "CardNumberlast4": {},
            "ProductID": {},
            "ProductName": {},
            "StoreID": {},
            "StoreName": {},
            "TokenIDRef": {},
            "TranID": {},
            "TranLifeCycleUniqueID": {},
            "TranRef": {},
            "TranRevTgt": {},
            "TranSource": {},
            "TranTime": {},
            "TransmissionDateTime": {},
            "TranStatus": {},
            "TranAmount": {},
            "TrancodeInternal": {},
            "TranCodeExternal": {},
            "TranDescription": {},
            "TranIndicator": {},
            "CardBalance": {},
            "OutStgAuthAmount": {},
            "AvailableBalance": {},
            "DebitCard": {
                "MessageTypeIdentifier": {},
                "ResponseCode": {},
                "PinExist": {},
                "MerchantType": {},
                "MerchantName": {},
                "MerchantCity": {},
                "MerchantState": {},
                "MerchantCountry": {},
                "CardAcceptorIdCode": {},
                "CardAcceptorTerminalID": {},
                "RetrievalReferenceNumber": {},
                "SystemTraceAuditNumber": {},
                "TranRequestedAmount": {},
                "TranCardExpDate": {},
                "CardExpDate": {},
                "MerchantID": {}
            },
            "CHECK": {
                "CheckNumber": {},
                "CheckMemo": {},
                "CheckRef1": {},
                "CheckRef2": {},
                "CheckRef3": {},
                "CheckRef4": {}
            },
            "ACH": {
                "ReceipientID": {},
                "TraceNumber": {}
            },
            "Healthcare": {
                "MemberID": {},
                "ProcessID": {},
                "GroupID": {},
                "SubscriberID": {},
                "PolicyID": {},
                "PlanType": {},
                "PhycisianID": {},
                "SiteInfo": {
                    "NPI": {}
                },
                "ProviderInfo": {
                    "NPI": {},
                    "FirstName": {},
                    "LastName": {}
                },
                "GeneralInfo": {
                    "NDC": {}
                },
                "ClaimsInfo": {
                    "BIN": {},
                    "PCN": {},
                    "ClaimNumber": {},
                    "GroupNumber": {},
                    "RxNumber": {},
                    "RxDate": {},
                    "NDC": {},
                    "MetricQuantity": {},
                    "DaysSupply": {},
                    "PrimaryCopayAmount": {},
                    "PrimaryAmountPaid": {},
                    "PatientNumber": {},
                    "PatientDOB": {},
                    "OtherCoverageCode": {}
                }
            },
			"Reserved":{
				"Reservedfield1": {},
				"Reservedfield2": {},
				"Reservedfield3": {},
				"Reservedfield4": {},
				"Reservedfield5": {},
				"Reservedfield6": {},
				"Reservedfield7": {},
				"Reservedfield8": {},
				"Reservedfield9": {},
				"Reservedfield10": {},
			}
        }
    ]
}
Response:
For API Response Codes: 1,6 and 7
{
    "Status" :{},
	"Result": {
		"RTFID": {},
		"RTFBatchID": {},
		"RTFBatchSize": {},
		"RTFBatchTimeStamp": {},
		"RTFReferenceNumber": {},
		"APIResponseCode": {},
		"APIReasonDescription": {}
	}
}

For API Response Codes: 2 and 3
{
    "error" :{},
	"description": {}
}

Contact US

E-Mail:

info@fvfn.com

Address:

2000 Riveredge PKWY, Suite 580, Georgia - 30328