Initiate a payment via CHAPS (pain.001 v9)
This tutorial describes how you can make a CHAPS payment with the Payments Hub API and accompanies the header information found in the Customer Credit Transfer Initiation POST message tutorial
A payment instruction is a transaction sent by one agent (sender) to another agent (beneficiary) to perform a new payment transaction. A message is generated by the bank on behalf of its customer who wishes to make a transfer.
The request must include a JSON payload in the body of the request. The JSON payload is an ISO pain.001 v9 message with the root element CdtTrfTxInf and contains the details of the request to perform the transaction.
In this scenario, let's imagine an international company that has an account with bank A and wants to make a transfer to another company, bank B. This payment will be made through the CHAPS system using a pain.001 message, which will result in a subsequent pacs.009 message.
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: Order a payment with CHAPS – Required request headers.
Message field | Description | Data type | Required/ Optional |
|---|---|---|---|
grpHdr.msgId | Point to point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message. Usage: The instructing party has to make sure that MessageIdentification is unique per instructed party for a pre-agreed period. | String | Optional |
grpHdr.CreDtTm | Date and time at which the message was created. | Date | Optional |
grpHdr.NbOfTxs | Number of individual transactions contained in the message. | String | Required |
grpHdr.initgPty | Name or identification (BIC) of the entity initiating the message. | String | Required |
PmtInf.PmtInfId | Unique identifier, the value of the UID assigned by the default UI. | String | Required |
PmtInf.PmtMtd | Unique identifier for the CHAPS payment method. Fixed value: TRF | String | Required |
PmtInf.reqdExctnDt | Date requested for execution | String | Required |
CdtTrfTxInf.InstdAmt | Amount of money to be moved between the debtor and the creditor, in the transaction. | Numeric | Required |
TxInf.ChrgBr | Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Usage: The ChargeBearer applies to the return message, not to the original instruction. | String | Required |
PmtInf.dbtrAgt | Agent that receives payment instructions (often through a forwarding agent in complex situations) and executes the transfer of funds. | String | Required |
CdtTrfTxInf.cdtrAgt | Agent receiving the transfer of funds | String | Required |
Example request body:
"hubMessage": {
"messageType": "pain_001_v09",
"document": {
"cstmrCdtTrfInitn": {
"grpHdr": {
"nbOfTxs": "1",
"initgPty": {
"id": {
"orgId": {
"anyBIC": "ABBYGB3EXXX"
}
}
},
"msgId": "MSG-wvzwivttwu95i6du54ep04m5qfpxca4",
"creDtTm": "2025-05-14T15:29:09.099-05:00"
},
"pmtInf": [
{
"pmtInfId": "myPaymentUniqueIdAsSendingPartyMx35",
"dbtrAcct": {
"ccy": "USD",
"id": {
"othr": {
"id": "2313726918930535976"
}
}
},
"pmtMtd": "TRF",
"dbtr": {
"ctryOfRes": "US",
"nm": "John Doe",
"pstlAdr": {
"twnNm": "Boston",
"pstCd": "02134",
"ctrySubDvsn": "MA",
"ctry": "US",
"strtNm": "Macabeo Street",
"bldgNb": "345"
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "SVRNUS33XXX"
}
},
"nbOfTxs": "1",
"cdtTrfTxInf": [
{
"cdtr": {
"nm": "JUAN RICARDO GOEPFERT ZAMACONA",
"pstlAdr": {
"twnNm": "Ciudad de México",
"pstCd": "06020",
"ctrySubDvsn": "Ciudad de México",
"ctry": "MX",
"strtNm": "Justo Sierra ",
"bldgNb": "160"
}
},
"chrgBr": "DEBT",
"rmtInf": {
"ustrd": [
"Invoice540 exp. May 24th"
]
},
"splmtryData": [
{
"envlp": {
"any": {
"cdtr": {
"cdtrAddtlInf": "Informative"
},
"ref": {
"fxRef": "fxr_7812f1d6-09b6-4348-b170-4ba1761cab12"
},
"fx": {
"fxMrgn": 3.57,
"fxAmt": 357,
"fxCcy": "USD",
"fxQt": 18.81,
"fxCrrltnId": "0xd90juw-jll5-zjgq-3l9x-ggfozgpvg77w"
},
"fees": {
"feesAmt": 30,
"feesAmtCcy": "USD"
}
}
}
}
],
"amt": {
"instdAmt": {
"ccy": "MXN",
"value": 6426.59
}
},
"cdtrAcct": {
"id": {
"othr": {
"id": "014320568784120168"
}
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BMSXMXMMXXX"
}
},
"pmtTpInf": {
"instrPrty": "HIGH"
},
"pmtId": {
"instrId": "MSG-wvzwivttwu95i6du54ep04m5qfpxca4",
"endToEndId": "myEndToEndIdMax35001"
}
}
],
"reqdExctnDt": {
"dt": "2025-05-14"
},
"pmtTpInf": {
"svcLvl": [
{
"cd": "SDVA"
}
],
"instrPrty": "HIGH"
}
}
]
}
},
"client": {
"internalId": "2028",
"initiator": "pre-execution"
},
"flow": "emission"
},
"executionId": {
"paymentHubId": "49af7f67-ab7e-39b8-939d-5d1ce8726073",
"executionNumber": 0
}
},