How to initiate an instant payment

You can initiate an instant payment using the simple instructions shown below. Finzly has exposed a single payment API that supports the initiation of various types of payments, both Domestic and International, using the speed preference. If a user would like to initiate an instant payment request, they can choose the speed name as "instant". The payment hub applies the smart-routing rules to process and instantly settle the payment via FedNow or RTP payment network.

Scenario 1: Execute an instant payment request [Sender and Receiver set up on Finzly]

POST /payments/creditrequest

HTTP Method: POST

Prepare the instant payment request by providing the simple payment instructions such as sender ID, receiver ID, payment amount, notes and set the speed as "Instant".

Copy
Copied
{
	"externalReferenceId": "paymentref100",
	"paymentAmount": 100,
	"paymentCurrency": "USD",
	"speed": "Instant",
	"paymentNotes": "Notes",
	"sender": {
		"accountUID": "58"
	},
	"receiver": {
		"accountUID": "29"
	}
}

Scenario 2: Execute an instant payment request [Sender and Receiver are not setup on Finzly]

POST /payments/creditrequest

HTTP Method: POST

Prepare the instant payment request by providing the following payment instructions such as sender details, receiver details, payment amount, notes and set the speed as "Instant".

Copy
Copied
{
	"externalReferenceId": "paymentref101",
	"paymentAmount": 100,
	"paymentCurrency": "USD",
	"speed": "Instant",
	"paymentNotes": "Notes",
	"sender": {
		"accountNumber": "112266",
        "accountType": "Deposit",
        "subAccountType": "Checking or Saving",
        "name": "Sender Name",
        "bankIdType": "NID",
        "bankId": "Bank routing number",
        "entityType": "Consumer or Corporate",
        "address": {
            "addressLine1": "Sender Address 1",
            "addressLine2": "Sender Address 2",
            "city": "Sender City Name",
            "state": "Sender State Name",
            "postalCode": "Sender Postal Code",
            "countryCode": "Country Code"
        },
        "phone": "Phone Number (if any)",
        "email": "Email Address (if any)"
	},
	"receiver": {
		"accountNumber": "Receiver account number",
        "accountType": "Deposit",
        "subAccountType": "Checking or Savings",
        "name": "Receiver Name",
        "accountCurrency": "USD",
        "address": {
            "addressLine1": "Receiver Address 1",
            "addressLine2": "Receiver Address 2",
            "city": "Receiver City Name",
            "state": "Receiver State Name",
            "postalCode": "Receiver Postal Code",
            "countryCode": "Country Code"
        },
        "phone": "Phone Number (if any)",
        "email": "Email Address (if any)"
        "bank": {
            "name": "Bank Name",
            "countryCode": "US",
            "bankIdType": "NID",
            "bankId": "Routing Number",
			"address": {
				"addressLine1": "Receiver Address 1",
				"addressLine2": "Receiver Address 2",
				"city": "Receiver City Name",
				"state": "Receiver State Name",
				"postalCode": "Receiver Postal Code",
				"countryCode": "Country Code"
			}
        }
	}
}

Payment Speed Details

The user can define the speed of money movement as part of their preference to execute the payment. The cost of the payment depends on the sponsor bank, while the speed is setup using different parameters that correspond to different payment rails that determine how quickly money can be moved.

Speed Speed Description
Instant RTP or FedNow based upon the smart routing rules configuration

>> Identify the sender unique identifier value (accountUID)

Execute the below API to get the accountUID (Unique Identifier) associated with the sender bank account number.

GET - {{URL}}/customers/{{customerUID}}/accounts?accountNumber={{accountNumber}}

Where:

  • customer_UID: This is the unique ID associated with customer.
  • account_Number: This is the sender (funding) bank account number.

JSON Response

Copy
Copied
{
    "status": "Success",
    "data": {
        "accountUID": 58,
        "name": "Test DDA Account 1",
        "accountNumber": "****0001",
        "fboAccountNumber": "",
        "type": "DEPOSIT",
        "subType": "CHECKING",
        "systemOfRecords": "Other Core",
        "balanceType": "Available", ...
    }
}

Note: Use the "accountUID" attribute value for the sender accountUID.

>> Identify the receiver unique identifier value (accountUID)

Execute the below API to get the contactUID (Unique Identifier) associated with the contact/beneficiary/receiver bank account.

GET - {{URL}}/customers/{{customerUID}}/contacts?accountNumber={{accountNumber}}&page=1&records=1

Where:

  • customer_UID: This is the unique ID associated with the customer.
  • account_Number: This is the account number.
  • page: Number of page needed from the search query.
  • records: Number of records needed on a page.

Receiver Account Response:

Copy
Copied
{
    "status": "Success",
    "code": null,
    "message": null,
    "pagination": {
        "totalRecords": 1,
        "returnedRecords": 1,
        "pageReturned": 0,
        "pageSize": 1
    },
    "data": [
        {
            "contactUID": "29",
            "templateName": "John Electric",
            "name": "John Electric LLC",
            "phoneNumber": "23499089727",
            "email": "john1201@gmail.com"
			....
        }
    ]
}

Note: Use the "contactUID" attribute value for the receiver accountUID.

>> Get the auth access token using the "API key" and "API secret" provided by the financial institution

[POST /auth/realms/{{TENANT-CODE}}/protocol/openid-connect/token/)]

Auth Request

Copy
Copied
curl -X POST [URL] 
-H "Content-Type: application/x-www-form-urlencoded" 
-H 'Authorization: Basic [Base64(apikey:apisecert)]' 
-d 'grant_type=client_credentials'

Auth Response

Copy
Copied
{
 "access_token": "",
 "expires_in": 14400,
 "refresh_expires_in": 1800,
 "refresh_token":"",
 "token_type": "bearer",
}

Note: Use access_token to call Finzly Connect APIs.