Real Time Payments: Initiate payments (pain.001)
This tutorial describes how you can make Real Time Payments (RTP) payments with the Payments Hub API and accompanies the header information found in the Customer Credit Transfer Initiation POST message tutorial
For this tutorial, consider a scenario where a customer in the USA wants to make one or more payments to several beneficiaries, for example, a payroll wanting to make their payroll payments. The customer is sending money from their US bank account to one or more other US bank accounts. If the customer has enough funds in their account, the Payments Hub API can be used to transfer the money to the other account. This tutorial describes how you can first submit the RTP payment using the ISO pain.001 message.
Request body
The request must include a JSON payload object in the request body. The JSON payload is a pain.001 ISO message with the cstmrCdtTrfInitn root element, and it contains the request details for submitting a payment.
The following table only provides information about some especially important fields. For details on all the required and optional message fields, see Message field definition for pain.001
Table: Submit the payment - Relevant request body elements.
Message field | Description | Data type | Required/ Optional |
grpHdr.nbOfTxs | Number of transactions within the message. Value: 1 | Integer | Required |
grpHdr.initgPty.nm | Name of the payment initiating party (debtor or a party acting on behalf of the debtor) | String | Required |
grpHdr.msgId | Message ID, which must uniquely identify each request you send. This ID is used internally for idempotency of the API. | String | Required |
grpHdr.creDtTm | Date and time of the payment request | String | Required |
pmtInf.pmtInfId | Unique identification of the payment information group within the request | String | Required |
pmtInf.pmtMtd | Payment method to be used. The value is TRF. | String | Required |
pmtInf.btchBookg | Whether a single entry per individual transaction or a batch entry for the sum of the amounts of all transactions within the group is requested. The value is false. | Boolean | Optional |
pmtInf.reqdExctnDt | Date when the initiating party wants the clearing agent to process the payment | String | Required |
pmtInf.pmtTpInf.svcLvl.prtry | Proprietary service level. The value is FP. | String | Required |
pmtInf .dbtr .dbtrAcct .dbtrAgt | Data structures containing the details for the debtor, the debtor’s account, and the debtor’s agent. You must provide either the LEI or the date and place of birth in the dbtr structure. | Object | Required |
pmtInf.cdtTrfTxInf.pmtId.endToEndId | End-to-end ID, which can be used to track the transaction between payment systems. | String | Required |
pmtInf.cdtTrfTxInf.pmtTpInf. svcLvl.cd | Service level for RTP, the value is always ‘SDVA’ | String | Optional |
pmtInf.cdtTrfTxInf.pmtTpInf.lclInstrm.prtry | Local Instrument value for RTP, the value is always ‘STANDARD’ | String | Required |
pmtInf.cdtTrfTxInf.pmtTpInf. ctgyPurp.prtry | Category Purpose value for RTP, the value is always ‘BUSINESS’ | String | Required |
pmtInf.cdtTrfTxInf.amt | Data structure containing the amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. The currency must be USD and the amount must be a positive value greater than zero. | Object | Required |
pmtInf.cdtTrfTxInf .cdtr .cdtrAcct .cdtrAgt | Data structures containing the details for the creditor, the creditor’s account, and the creditor’s agent. You must provide either the LEI or the date and place of birth in the cdtr structure. | Object | Required |
pmtInf.cdtTrfTxInf.rmtInf | Data structure containing remittance details, either in unstructured or structured form | Object | Optional |
pmtInf.cdtTrfTxInf.splmtryData | Additional information that cannot be captured in the structured elements and/or any other | Object | Optional |
Example request body:
{
"document": {
"cstmrCdtTrfInitn": {
"grpHdr": {
"msgId": "PAY12345678",
"creDtTm": "2024-03-08T18:04:25.000Z"
"nbOfTxs": 1,
"initgPty": {
"nm": "HOOPY PAYROLL"
}
},
"pmtInf": [
{
"pmtInfId": "RTP-PAY-11223344",
"pmtMtd": "TRF",
"reqdExctnDt": {
"dtTm": "2024-03-08"
},
"dbtrAcct": {
"id": {
"othr": {
"id": "9013498108"
}
},
"nm": "THE VERY BIG CORPORATION OF AMERICA"
},
"dbtr": {
"id": {
"orgId": {
"LEI": "ABX123456789"
}
},
"nm": "THE VERY BIG CORPORATION OF AMERICA",
"pstlAdr": {
"twnNm": "Buffalo",
"pstCd": "12345",
"ctrySubDvsn": "New York",
"ctry": "US",
"strtNm": "Main Street"
}
},
"dbtrAgt": {
"finInstnId": {
"clrSysMmbId": {
"clrSysId": {
"cd": "USABA"
},
"mmbId": "112233441"
}
}
},
"chrgBr": "SLEV",
"cdtTrfTxInf": [
{
"pmtId": {
"endToEndId": "PAYMENT1001"
},
"pmtTpInf": {
"svcLvl": [
{
"cd": "SDVA"
}
],
"lclInstrm": {
"prtry": "STANDARD"
},
"ctgyPurp": {
"prtry": "BUSINESS"
}
},
"amt": {
"instdAmt": {
"value": 220.26,
"ccy": "USD"
}
},
"cdtrAcct": {
"id": {
"othr": {
"id": "987654321"
}
},
"nm": "Mr Jesse James"
},
"cdtrAgt": {
"finInstnId": {
"clrSysMmbId": {
"clrSysId": {
"cd": "USABA"
},
"mmbId": "123456789"
}
}
},
"cdtr": {
"id": {
"prvtId": {
"dtAndPlcOfBirth": {
"cityOfBirth": "Kearney",
"birthDt": "1847-09-05",
"ctryOfBirth": "US"
}
}
},
"nm": "Mr Jesse James",
"pstlAdr": {
"twnNm": "Dorchester",
"pstCd": "98765",
"ctrySubDvsn": "Massachusetts",
"ctry": "US",
"strtNm": "Fricano Road"
}
},
"rmtInf": {
"ustrd": [
"Payroll Oct"
]
}
}
]
}
]
}
}
}