Skip to main content

Transfer Money V2

The Unified Payment API serves as a single entry point for initiating real-time and fallback payments through multiple supported networks, including FedNow, TCH, and ACH. It abstracts the complexity of routing logic and network compatibility checks, allowing clients (such as mobile / middleware systems) to initiate payments with minimal integration effort.

Key Features:

  • Unified interface for multi-rail payments (FedNow, TCH, ACH)

  • Automatic routing based on beneficiary bank support

  • Built-in fallback mechanism if real-time networks are unavailable

Typical Use Case:

Client system (Mobile / Middleware) send a payment request to the XD Ledger via this API. The ledger then parses the request, determines the optimal payment rail, and processes the transaction end-to-end.

Payment Process Flow​

Payment Process Flow

  1. Middleware Initiates Payment

    • Middleware → XD Ledger: Initiates payment via Unified Payment API

  2. XD Ledger Parses the Payload

    • XD Ledger: Extracts Debtor and Creditor info from payload

  3. Parallel Account Check

    • XD Ledger → FedNow Connector: Check if creditor supports FedNow
    • XD Ledger → TCH Connector: Check if creditor supports TCH

  4. Beneficiary Bank Response

    • FedNow Connector ↔ Beneficiary Bank: Does account support FedNow?
    • TCH Connector ↔ Beneficiary Bank: Does account support TCH?
    • FedNow Connector → XD Ledger: Response - Supported / Not Supported
    • TCH Connector → XD Ledger: Response - Supported / Not Supported

  5. Determine Routing Logic

    • XD Ledger:
      • If Both Supported → Use system default (e.g., prefer FedNow or TCH)
      • If One Supported → Use that one
      • If None Supported → Check 'Payment_FALL_BACK' setting in XD Ledger
        • Use Fed Connector (ACH) if fallback is ACH (default)
        • Use FedNow Connector or TCH Connector if fallback is changed by Admin

  6. Payment Processing

    • XD Ledger → appropriate Connector (FedNow / TCH / ACH) for payment
    • Connector processes payment and sends it to the Beneficiary Bank

Method: POST​

{{URL}}/jsonrpc

Headers​

NameValue
Content-Typeapplication/json
CredentialBasic c3VwcG9ydCsxQG5ldHN5cy1pbmMuY29tOjM5ZDYxOGJkNTVmN5NWQxY2RlNDE5
Signature{{signature}}

Example​

Payload Parameters
ParameterDescription
method

Mandatory		String
Method Name must be "TransactionService.Transfermoneyv2"
id

Optional		String
Unique identifier for the request.
Supported Value : Random & Alphanumeric
Sample Value : "1"
payloadObject
Root Object containing the payment instruction details.
purpose

Optional		String
Describes the purpose of the transaction.
Supported Value : Random & Alphanumeric
reference

Mandatory		String
Unique transaction reference.
Supported Value : Random & Alphanumeric
transactionAmountObject
Object containing amount and currency.
amount

Mandatory		String
Transaction amount as a String
Sample Value : "100"
currency

Mandatory		String
Currency code must be "USD".
creditorObject
Creditor (receiver) details.
userType

Optional		String
Type of user
Constant Value : "INDIVIDUAL / BUSINESS"
identification

Optional		String
Unique identifier of the creditor.
identificationType

Optional		String
Type of ID
Constant Value : " SSN / TIN"
firstName

Mandatory		String
First name of the creditor.
Supported Value : Random & Alphanumeric
middleName

Optional		String
Middle name of the creditor.
Supported Value : Random & Alphanumeric
lastName

Optional		String
Last name of the creditor.
Supported Value : Random & Alphanumeric
creditorAccountObject
Creditor’s bank account information.
identification

Mandatory		String
Creditor’s account number.
identificationType

Mandatory		String
Account identification type
Sample Value : "ACCOUNT_NUMBER"
identificationType2

Mandatory		String
(Optional) Account type
Sample Value : " CHECKING / SAVINGS"
institutionObject
Bank institution details for creditor.
institution.name

Optional		String
Name of the bank
Sample Value : "JP MORGAN CHASE"
institution.identification

Mandatory		String
Institution identifier
Sample Value : ABA routing number
institution.identificationType

Optional		String
Type of institution ID
Sample Value : "ABA"
debtorPostalAddressObject
Postal address of the debtor (sender).
addressType

Optional		String
Address type.
Supported Value : Random & Alphanumeric
Sample Value : "HOUSE"
addressLine1

Optional		String
First line of the address.
addressLine2

Optional		String
Second line of the address.
city

Optional		String
City name
Sample Value : "Seattle"
state

Optional		String
State code
Sample Value : "WA"
zipCode

Optional		String
ZIP or postal code.
countryCode

Optional		String
Country code (ISO 3166, e.g., "840" for USA).
nationality

Optional		String
Nationality (ISO 3166 alpha-2, e.g., "US").
debtorContactObject
Contact details of the debtor.
primaryEmail

Optional		String
Email address of the debtor.
primaryPhone

Optional		String
Phone number of the debtor.
debtorAccountObject
Debtor’s bank account details.
identification

Mandatory		String
Account number of the debtor.
identificationType

Mandatory		String
Identification type
Sample Value : "ACCOUNT_NUMBER"
institutionObject
Institution details of the debtor’s bank.
institution.name

Optional		String
Name of the bank
Sample Value : "FinWise BANK"
institution.identification

Mandatory		String
Institution ID
Sample Value : ABA number
institution.identificationType

Mandatory		String
Institution ID type
Sample Value : "ABA"
apiObject
API credentials and metadata.
credential

Mandatory		String 
{"<Username>:<apiKey>"}
as Base64 encoded value to be provided
signature

Mandatory		String
Signature String for authentication.
apiKey

Optional		String
API key used for the transaction.
keyId

Mandatory		String
Identifier of the key used.

curl --location 'https://plus.netxd.com/pl/jsonrpc' \
--header 'Content-Type: application/json' \
--data-raw '{"method":"TransactionService.Transfermoneyv2","id":"1","params":{"payload":{"purpose":"wages of June month included with loan repayment","reference":"REF-00001104","transactionAmount":{"amount":"100","currency":"USD"},"creditor":{"userType":"INDIVIDUAL","identification":"478541254","identificationType":"SSN","firstName":"Bishnu","middleName":"Parikh","lastName":"Shah"},"creditorAccount":{"identification":"857444440002","identificationType":"ACCOUNT_NUMBER","identificationType2":"CHECKING","institution":{"name":"JP MORGAN CHASE","identification":"011002550","identificationType":"ABA"}},"debtorPostalAddress":{"addressType":"HOUSE","addressLine1":"1st Ave","addressLine2":"238 Stuyvesant 14th St","city":"Seattle","state":"NY","zipCode":"45210","countryCode":"088","nationality":"USA"},"debtorContact":{"primaryEmail":"bishnuparsh@yahoo.com","primaryPhone":"+1-9876543456"},"debtorAccount":{"identification":"200515264448391","identificationType":"ACCOUNT_NUMBER","institution":{"name":"FinWise BANK","identification":"124303298","identificationType":"ABA"}}},"api":{"credential":"Basic bmF2eWEubitlbXBAbmV0eGQuY29tOmY1OWIwY2NlOTU4ZTQ1YTc4MGVhZWIzYWVjOWVjZDAx","signature":"MEQCIAbpxHpdOyBEVlmxPYv7m4Z1OvWJJYw7g7u3GE3T9nmvAiBjKHckSvb1M6O4t7FeWsn2z9Y3dMeYn3HyX/k28ek/Dw==","apiKey":"f59b0cce958e45a780eaeb3aec9ecd01","keyId":"348076"}}}'


Request Body​

{
    "method": "TransactionService.Transfermoneyv2",
    "id": "1",
    "params": {
        "payload": {
            "purpose": "Loan Account number - 011011258698745",
            "reference": "REF-00001104",
            "transactionAmount": {
                "amount": "100",
                "currency": "USD"
            },
            "creditor": {
                "userType": "INDIVIDUAL",
                "identification": "478541254",
                "identificationType": "SSN",
                "firstName": "Bishnu",
                "middleName": "Parikh",
                "lastName": "Shah"
            },
            "creditorAccount": {
                "identification": "857444440002",
                "identificationType": "ACCOUNT_NUMBER",
                "identificationType2": "CHECKING",
                "institution": {
                    "name": "JP MORGAN CHASE",
                    "identification": "011002550",
                    "identificationType": "ABA"
                }
            },
            "debtorPostalAddress": {
                "addressType": "HOUSE",
                "addressLine1": "1st Ave",
                "addressLine2": "238 Stuyvesant 14th St",
                "city": "Seattle",
                "state": "NY",
                "zipCode": "45210",
                "countryCode": "088",
                "nationality": "USA"
            },
            "debtorContact": {
                "primaryEmail": "abc@xyz.com",
                "primaryPhone": "+1-9876543456"
            },
            "debtorAccount": {
                "identification": "200515264448391",
                "identificationType": "ACCOUNT_NUMBER",
                "institution": {
                    "name": "FinWise BANK",
                    "identification": "124303298",
                    "identificationType": "ABA"
                }
            }
        },
        "api": {
            "credential": "Basic bmF2eWEubitlbXBAbmV0eGQuY29tOmY1OWIwY2NlOTU4ZTQ1YTc4MGVhZWIzYWVjOWVjZDAx",
            "signature": "MEQCIAbpxHpdOyBEVlmxPYv7m4Z1OvWJJYw7g7u3GE3T9nmvAiBjKHckSvb1M6O4t7FeWsn2z9Y3dMeYn3HyX/k28ek/Dw==",
            "apiKey": "f59b0cce958e45a780eaeb3aec9ecd01",
            "keyId": "348076"
        }
    }
}

Response: 200​

Example​

Payload Parameters
ParameterDescription
idString
Unique identifier of the API response.
Sample Value: "1"
jsonrpcString
JSON-RPC version used.
Sample Value: "2.0"
resultObject
Root Object containing transaction result details.
apiObject
Metadata about the processed API.
typeString
Type of transaction acknowledgment Sample Value: "CCT_OUT_ACK"
referenceString
Reference ID for the transaction.
dateTimeString
Date and time when the transaction was acknowledged. Format: YYYY-MM-DD HH:mm:ss.
accountObject
Account details of the sender (debtor).
accountIdString
Debtor’s account number.
balanceCentsInteger
Account balance in cents after the transaction.
holdBalanceCentsInteger
Funds on hold in cents.
statusString
Current status of the account
Sample Value: "ACTIVE"
transactionNumberString
Internal transaction tracking number.
transactionStatusString
Final status of the transaction
Sample Value: "COMPLETED"
transactionAmountCentsInteger
Transaction amount in cents.
originalRequestBase64String
Base64-encoded original request payload.
processIdString
Unique ID for tracking the transaction process.
supportedChannelString
Channel through which the transaction was processed
Sample Value: "FEDNOW".
transactionTypeString
Type of transaction
Sample Value: "CCT_OUT"

Response Body​


{
    "id": "1",
    "result": {
        "api": {
            "type": "CCT_OUT_ACK",
            "reference": "REF-00001105",
            "dateTime": "2025-05-27 16:06:30"
        },
        "account": {
            "accountId": "200515264448391",
            "balanceCents": 99850925,
            "holdBalanceCents": 1000,
            "status": "ACTIVE"
        },
        "transactionNumber": "QA00000001586007",
        "transactionStatus": "COMPLETED",
        "transactionAmountCents": 100,
        "originalRequestBase64": "eyJjaGFubmVsIjoiRkVEX05PVyIsInRyYW5zYWN0aW9uVHlwZSI6IkNDVF9PVVQiLCJyZWZlcmVuY2UiOiJSRUYtMDAwMDExMDUiLCJ0cmFuc2FjdGlvbkFtb3VudCI6eyJhbW91bnQiOiIxMDAiLCJjdXJyZW5jeSI6IlVTRCJ9LCJkZWJ0b3JQb3N0YWxBZGRyZXNzIjp7ImFkZHJlc3NUeXBlIjoiSE9VU0UiLCJhZGRyZXNzTGluZTEiOiIxc3QgQXZlIiwiYWRkcmVzc0xpbmUyIjoiMjM4IFN0dXl2ZXNhbnQgMTR0aCBTdCIsImNpdHkiOiJTZWF0dGxlIiwic3RhdGUiOiJOWSIsInppcENvZGUiOiI0NTIxMCIsImNvdW50cnlDb2RlIjoiMDg4In0sImRlYnRvckNvbnRhY3QiOnsicHJpbWFyeUVtYWlsIjoiYmlzaG51cGFyc2hAeWFob28uY29tIiwicHJpbWFyeVBob25lIjoiKzEtOTg3NjU0MzQ1NiJ9LCJkZWJ0b3JBY2NvdW50Ijp7ImlkZW50aWZpY2F0aW9uIjoiMjAwNTE1MjY0NDQ4MzkxIiwiaWRlbnRpZmljYXRpb25UeXBlIjoiQUNDT1VOVF9OVU1CRVIiLCJpbnN0aXR1dGlvbiI6eyJuYW1lIjoiRmluV2lzZSBCQU5LIiwiaWRlbnRpZmljYXRpb24iOiIxMjQzMDMyOTgiLCJpZGVudGlmaWNhdGlvblR5cGUiOiJBQkEifX0sImNyZWRpdG9yIjp7InVzZXJUeXBlIjoiSU5ESVZJRFVBTCIsImlkZW50aWZpY2F0aW9uIjoiNDc4NTQxMjU0IiwiaWRlbnRpZmljYXRpb25UeXBlIjoiU1NOIiwiZmlyc3ROYW1lIjoiQmlzaG51IiwibWlkZGxlTmFtZSI6IlBhcmlraCIsImxhc3ROYW1lIjoiU2hhaCJ9LCJjcmVkaXRvckFjY291bnQiOnsiaWRlbnRpZmljYXRpb24iOiI4NTc0NDQ0NDAwMDIiLCJpZGVudGlmaWNhdGlvblR5cGUiOiJBQ0NPVU5UX05VTUJFUiIsImlkZW50aWZpY2F0aW9uVHlwZTIiOiJDSEVDS0lORyIsImluc3RpdHV0aW9uIjp7Im5hbWUiOiJKUCBNT1JHQU4gQ0hBU0UiLCJpZGVudGlmaWNhdGlvbiI6IjAxMTAwMjU1MCIsImlkZW50aWZpY2F0aW9uVHlwZSI6IkFCQSJ9fSwicHVycG9zZSI6IndhZ2VzIG9mIEp1bmUgbW9udGggaW5jbHVkZWQgd2l0aCBsb2FuIHJlcGF5bWVudCJ9",
        "processId": "20250527751751IBVVEq237NxvZ4K",
        "supportedChannel": "FEDNOW",
        "transactionType": "CCT_OUT"
    },
    "jsonrpc": "2.0"
}

Error Codes​

Error Codes
CodeMessageRecommended Action
ACCOUNT_NOT_EXISTAccount doesn’t ExistPlease enter a valid Account Number
ACCOUNT_NOT_MATCH_WITH_CRJ_ACCOUNTCRJ account number does not match with parent account numberPlease review the Sub Account and Parent Account details
ACCOUNT_NOT_MATCHED_WITH_LEGALREPAccount not matched with legalrepLegalrep does not have access to this account. Please contact Support.
BAD_INPUTCreditorAccount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTCreditorAccount.Institution is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAccount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAccount.Institution is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAccount.Identification is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAccount.IdentificationType is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAccount.IdentificationValue is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTTransactionAmount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTAmount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTCurrency is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTDebtorAddress is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTFee Amount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTTax Amount is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTFee subsidiary source account doesn’t have sufficient balancePlease check the error message and fix the request payload
BAD_INPUTRequested is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTreferenceId is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTFor wire transfers, Amount field should not be more than 12 digitsPlease check the error message and fix the request payload
BAD_INPUTticketMemo is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTcreditDate is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTpayloadJson is invalid or missingPlease check the error message and fix the request payload
BAD_INPUTstatus is invalid or missingPlease check the error message and fix the request payload
CANNOT_PROCESS_TRANSACTIONTransaction cannot be processedTransaction Type is not supported. Please contact Support with the Error Message
DUPLICATE_REFERENCE_IDA request with Referenced already existsPlease use a unique referenceId
FED_NOW_PROFILE_SETTINGS_NOT_FOUNDFednow profile Settings not found for the AccountPlease reach out to Support and share this error message
IN_ACTIVE_CUSTOMERCustomer is not in active stateYour Customer Profile is "INACTIVE". Please contact Support
INSUFFICIENT_BALANCEInsufficient [balance] in account [acc no]Please review account limits or balances
INTERNAL_ERRORPlease contact the system administrator and try again laterTemporary error - Please try again later
INVALID_CURRENCYAccount Currency and Instructed Currency mismatchedPlease fix the Currency Code and Try again
INVALID_POSTED_DATEInvalid Posted Date. Must be RFC3339 FormatPlease fix the Posted Date Format and Try again
NOT_FOUND_ACCOUNTAccount not foundPlease fix the payload with the Correct Account Number
NOT_FOUND_APPLICATIONApplication not foundPlease fix the payload with the Correct Application ID
NOT_FOUND_CUSTOMERCustomer not foundPlease fix the payload with the Correct Customer ID
NOT_FOUND_INSTITUTIONInstitution not found in Network for Payment ChannelPlease fix the payload with the Correct Institution ID
NOT_FOUND_PROGRAMProgram not foundPlease fix the payload with the relevant Program Name
NOT_FOUND_PROGRAM_CHANNELProgram channel setting not foundPlease fix the payload with the Correct Program Channel
NOT_FOUND_TRANSACTIONTransaction not foundPlease fix the payload with the Correct Transaction ID
PER_DAY_MONEY_IN_LIMIT_BREACHEDper day money_in limit breachedPlease reach out to Support and share this error message
PER_DAY_MONEY_IN_LIMIT_BREACHED_FOR_RECEIVERper day money_in limit breached for receiverPlease review account limits or balances
PER_DAY_MONEY_OUT_LIMIT_BREACHEDper day money_out limit breachedPlease review account limits or balances
PER_DAY_TRANSACTION_LIMIT_BREACHEDper day transaction limit breachedPlease review account limits or balances
PER_MONTH_MONEY_IN_LIMIT_BREACHEDper month money_in limit breachedPlease review account limits or balances
PER_MONTH_MONEY_OUT_LIMIT_BREACHEDper month money_out limit breachedPlease review account limits or balances
PER_MONTH_TRANSACTION_LIMIT_BREACHEDper month transaction limit breachedPlease review account limits or balances
PER_YEAR_TRANSACTION_LIMIT_BREACHEDper year transaction limit breachedPlease review account limits or balances
RTP_PROFILE_SETTINGS_NOT_FOUNDRTP Profile Settings not found for the AccountPlease reach out to Support and share this error message
SUPPORTED_CHANNEL_UNAVAILABLESupported Channel is unavailablePlease reach out to Support and share this error message
TCH_REF_BALANCE_EXCEEDEDTransaction not supportedPlease review the request
TRANSACTION_NOT_FOUNDTransaction not foundPlease fix the payload with the correct Transaction ID
TXN_NOT_ALLOWED_FOR_NON_ADDRESSABLE_ACCNot allowed for non-addressablePlease verify if the request action is allowed or supported
WIRING_NOT_FOUNDWiring Instruction not foundPlease verify the request action is allowed or supported