Table of contents
In this document, find the APIs that aplonHUB exposes so that core banking (or other upstream systems) need to call in order to work with outgoing CBPR+ payments.
Description:
This API is used to initiate a Target2 customer credit transfer.
Method: PUT
Endpoint: /t2/rtgs/customer/credit/transfer
{ "chargeBearer": "string", "chargesInformation": [ { "agent": { "financialInstitutionIdentification": { "bicfi": "string", "lei": "string" } }, "amount": { "currencyCode": "string", "value": 0 } } ], "creditor": { "name": "string", "postalAddress": { "addressLine": [ "string" ], "buildingNumber": "string", "country": "string", "streetName": "string", "townName": "string" } }, "creditorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "creditorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "debtor": { "name": "string", "postalAddress": { "country": "string", "streetName": "string", "townName": "string", "postalCode" : "string" } }, "debtorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "debtorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "exchangeRate": 0, "instructedAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "instructedAmount": { "currencyCode": "string", "value": 0 }, "instructingAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "interbankSettlementAmount": { "currencyCode": "string", "value": 0 }, "interbankSettlementDate": "string", "paymentIdentification": { "clearingSystemReference": "string", "endToEndIdentification": "string", "instructionIdentification": "string", "uetr": "string" }, "remittanceInformation": { "unstructured": [ "string" ] }, "instructionForCreditorAgent": { "code": "PHOB", "instructionInformation": "string" }, "paymentTypeInformation": { "serviceLevel": { "code": "AAAA", "proprietary": "string" } }, "purpose": { "code": "string", "proprietary": "string" }, "settlementPriority": "NORM" } |
Fields | Instructions or allowed values |
---|---|
| One of For |
| For agent identification the |
| One of should be used |
| 11 digits BIC should be used |
| When postal code is present in debtor’s or creditor’s address, country and town name should be also present and address line is not allowed. |
Responses | |
---|---|
Code | Description |
200 | OK |
{ "status": "OK", "payload": 150, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field uetr. Valid format is [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab]{1}[0-9a-f]{3}-[0-9a-f]{12}." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_DATE", "errors": [ "Invalid interbankSettlementDate. Date /12/2021 cannot be formatted to dd/MM/yyyy." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_LENGTH", "errors": [ "Invalid length for field currencyCode. Field must be from 3 to 3 characters." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field exchangeRate. Valid format is ^[1-9]\\.\\d{1,10}$." ] } |
Failure Sample Responce
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "FATAL D00007 Invalid currency code or too many decimal digits." ] } |
Failure Sample Responce
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_VALUE", "errors": [ "Invalid value for field chargeBearer. Valid values are [DEBT, CRED, SHAR, SLEV]." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "ERROR null cvc-pattern-valid: Value 'TESTBIA' is not facet-valid with respect to pattern '[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}' for type 'BICFIDec2014Identifier'. null (null), ERROR null cvc-type.3.1.3: The value 'TESTBIA' of element 'BICFI' is not valid. null (null), FATAL D00001 Invalid FI BIC. /cdtTrfTxInf[0]/chrgsInf[0]/agt/finInstnId/BICFI (TESTBIA)" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "ERROR null cvc-pattern-valid: Value '88' is not facet-valid with respect to pattern '[A-Z0-9]{18,18}[0-9]{2,2}' for type 'LEIIdentifier'. null (null), ERROR null cvc-type.3.1.3: The value '88' of element 'LEI' is not valid. null (null)" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field bicfi. Valid format is [A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}." ] } |
Description:
This API is used to initiate a Target2 financial institution credit transfer.
Method: PUT
Endpoint: /t2/rtgs/fi/credit/transfer
{ "creditor": { "financialInstitutionIdentification": { "bicfi": "string" } }, "creditorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "creditorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "creditorAgentAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "debtor": { "financialInstitutionIdentification": { "bicfi": "string" } }, "debtorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "debtorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "debtorAgentAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "instructedAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "instructedAmount": { "currencyCode": "string", "value": 0 }, "instructingAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "interbankSettlementAmount": { "currencyCode": "string", "value": 0 }, "interbankSettlementDate": "string", "pacs009Type": "string", "paymentIdentification": { "clearingSystemReference": "string", "endToEndIdentification": "string", "instructionIdentification": "string", "uetr": "string" }, "remittanceInformation": { "unstructured": [ "string" ] }, "instructionForCreditorAgent": { "code": "PHOB", "instructionInformation": "string" }, "paymentTypeInformation": { "serviceLevel": { "code": "AAAA", "proprietary": "string" } }, "purpose": { "code": "string", "proprietary": "string" }, "settlementPriority": "NORM" "underlyingCustomerCreditTransfer": { "creditor": { "name": "string", "postalAddress": { "addressLine": [ "string" ], "buildingNumber": "string", "country": "string", "streetName": "string", "townName": "string" } }, "creditorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "creditorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "creditorAgentAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "debtor": { "name": "string", "postalAddress": { "addressLine": [ "string" ], "buildingNumber": "string", "country": "string", "streetName": "string", "townName": "string" } }, "debtorAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "debtorAgent": { "financialInstitutionIdentification": { "bicfi": "string" } }, "debtorAgentAccount": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "initiatingParty": { "name": "string" }, "instructedAmount": { "currencyCode": "string", "value": 0 }, "instructionForCreditorAgent": { "code": "string", "instructionInformation": "string" }, "instructionForNextAgent": { "code": "string", "instructionInformation": "string" }, "intermediaryAgent1": { "financialInstitutionIdentification": { "bicfi": "string" } }, "intermediaryAgent1Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "intermediaryAgent2": { "financialInstitutionIdentification": { "bicfi": "string" } }, "intermediaryAgent2Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "intermediaryAgent3": { "financialInstitutionIdentification": { "bicfi": "string" } }, "intermediaryAgent3Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "previousInstructingAgent1": { "financialInstitutionIdentification": { "bicfi": "string" } }, "previousInstructingAgent1Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "previousInstructingAgent2": { "financialInstitutionIdentification": { "bicfi": "string" } }, "previousInstructingAgent2Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "previousInstructingAgent3": { "financialInstitutionIdentification": { "bicfi": "string" } }, "previousInstructingAgent3Account": { "identification": { "iban": "string", "other": { "identification": "string", "schemeName": { "code": "string", "proprietary": "string" } } } }, "remittanceInformation": { "unstructured": [ "string" ] }, "ultimateCreditor": { "name": "string" }, "ultimateDebtor": { "name": "string" } } } |
Fields | Instructions or allowed values |
---|---|
| One of For |
| For agent identification the |
| 11 digits BIC should be used |
|
|
Responses | |
---|---|
Code | Description |
200 | OK |
{ "status": "OK", "payload": 150, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_LENGTH", "errors": [ "Invalid length for field currencyCode. Field must be from 3 to 3 characters." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field uetr. Valid format is [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab]{1}[0-9a-f]{3}-[0-9a-f]{12}." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field bicfi. Valid format is [A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_LENGTH", "errors": [ "Invalid length for field code. Field must be from 1 to 4 characters." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_FORMAT", "errors": [ "Invalid field format for field iban. Valid format is [A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": "INVALID_DATE", "errors": [ "Invalid interbankSettlementDate. Date string cannot be formatted to dd/MM/yyyy." ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "Invalid value of field interbankSettlementAmount." ] } |
Description:
This API is used to initiate a recall request for an outgoing Target2 credit transfer
Method: PUT
Endpoint: /t2/rtgs/recall/request
{ "actionUser": "string", "authUser": "string", "reasonCode": "string", "sepaTrnHedSn": 150 //outgoing pacs008 ID, "additionalInformation" : "string" //Allowed only for reasonCodes "FRAD", CUST", AM09", AC03", max length 105 characters } |
Responses | |
---|---|
Code | Description |
200 | OK |
Recall Request Reason Codes | |
---|---|
DUPL | Payment is a duplicate of another payment. |
CUTA | Cancellation requested because an investigation request has been received and noremediation is possible. |
UPAY | Payment is not justified. |
CUST | Cancellation requested by the debtor |
CURR | Currency of the payment is incorrect. |
AGNT | Agent in the payment workflow is incorrect |
TECH | Cancellation requested following technical problems resulting in an erroneous transaction. |
FRAD | Cancellation requested following a transaction that may have been originated fraudulently. The use of the "Fraudulent Origin" code should be governed by jurisdictions. |
COVR | Cover payments has either been returned or cancelled. |
AM09 | Amount of the payment is incorrect. |
NARR | Reason is provided as narrative information in the additional reason information. |
{ "status": "OK", "payload": 1, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "cancel.payment.invalid.reason.code" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "additional.info.required" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "cancel.payment.legalReason1.max.length" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "invalid.recall.request.reason.code" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "generate.cancel.payment.failed" ] } |
Description:
This API accepts an incoming recall request
Method: PUT
Endpoint: /t2/rtgs/recall/request/accept
{ "reasonCode": "string", "sepaTrnHedSn": 0, //incoming camt056 ID "charges" : 1.00, // in case the reasonCode is FOCR (Following Cancelation Request) you may want to add charges in the Payment Return message. "actionUser": null, "authUser": null } |
Return Reason Codes | |
---|---|
Code | Description |
AC01 | Format of the account number specified is not correct |
AC02 | Debtor account number invalid or missing |
AC03 | Wrong IBAN in SCT |
AC04 | Account number specified has been closed on the bank of account's books |
AC06 | Account specified is blocked, prohibiting posting of transactions against it |
AC07 | Creditor account number closed |
AC13 | Debtor account type is missing or invalid |
AC14 | An agent in the payment chain is invalid |
AC15 | Account details have changed |
AC16 | Account is in sequestration |
AC17 | Account is in liquidation |
AG01 | Transaction forbidden on this type of account (formerly NoAgreement) |
AG02 | Bank Operation code specified in the message is not valid for receiver |
AG07 | Debtor account cannot be debited for a generic reason |
AGNT | Agent in the payment workflow is incorrect |
AM01 | Specified message amount is equal to zero |
AM02 | Specific transaction/message amount is greater than allowed maximum |
AM03 | Specified message amount is an non processable currency outside of existing agreement |
AM04 | Amount of funds available to cover specified message amount is insufficient |
AM05 | Duplication |
AM06 | Specified transaction amount is less than agreed minimum |
AM07 | Amount specified in message has been blocked by regulatory authorities |
AM09 | Amount received is not the amount agreed or expected |
AM10 | Sum of instructed amounts does not equal the control sum |
ARDT | Already returned original SCT |
BE01 | Identification of end customer is not consistent with associated account number, organisation ID or private ID |
BE04 | Specification of creditor's address, which is required for payment, is missing/not correct (formerly IncorrectCreditorAddress) |
BE05 | Party who initiated the message is not recognised by the end customer |
BE06 | End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books |
BE07 | Specification of debtor's address, which is required for payment, is missing/not correct |
BE08 | Returned as a result of a bank error |
BE10 | Debtor country code is missing or invalid |
BE11 | Creditor country code is missing or invalid |
BE16 | Debtor or Ultimate Debtor identification code missing or invalid |
BE17 | Creditor or Ultimate Creditor identification code missing or invalid |
CN01 | Authorisation is cancelled |
CNOR | Creditor bank is not registered under this BIC in the CSM |
CNPC | Cash not picked up by Creditor or cash could not be delivered to Creditor |
CURR | Currency of the payment is incorrect |
CUST | Cancellation requested by the Debtor |
DNOR | Debtor bank is not registered under this BIC in the CSM |
DS28 | Return following technical problems resulting in erroneous transaction |
DT01 | Invalid date (eg, wrong settlement date) |
DT02 | Cheque has been issued but not deposited and is considered expired |
ED01 | Correspondent bank not possible |
ED03 | Balance of payments complementary info is requested |
ED05 | Settlement of the transaction has failed |
EMVL | The card payment is fraudulent and was not processed with EMV technology for an EMV card |
ERIN | The Extended Remittance Information (ERI) option is not supported |
FF03 | Payment Type Information is missing or invalid. Generic usage if cannot specify Service Level or Local Instrument code |
FF04 | Service Level code is missing or invalid |
FF05 | Local Instrument code is missing or invalid |
FF06 | Category Purpose code is missing or invalid |
FF07 | Purpose is missing or invalid |
FOCR | Return following a cancellation request |
FR01 | Returned as a result of fraud |
FRTR | Final response/tracking is recalled as mandate is cancelled |
G004 | In a FIToFI Customer Credit Transfer: Credit to the creditor’s account is pending, status Originator is waiting for funds provided via a cover. |
MD01 | No Mandate |
MD02 | Mandate related information data required by the scheme is missing |
MD05 | Creditor or creditor's agent should not have collected the direct debit |
MD06 | Return of funds requested by end customer |
MD07 | End customer is deceased |
MS02 | Reason has not been specified by end customer |
MS03 | Reason has not been specified by agent |
NARR | Reason is provided as narrative information in the additional reason information |
NOAS | No response from Beneficiary |
NOCM | Customer account is not compliant with regulatory requirements, for example FICA (in South Africa) or any other regulatory requirements |
NOOR | Original SCT never received |
PINL | The card payment is fraudulent (lost and stolen fraud) and was processed as EMV transaction without PIN verification |
RC01 | Bank Identifier code specified in the message has an incorrect format (formerly IncorrectFormatForRoutingCode) |
RC07 | Incorrect BIC of the beneficiary Bank in the SCTR |
RC08 | ClearingSystemMemberidentifier is invalid or missing. Generic usage if cannot specify between debit or credit account |
RC11 | Intermediary Agent is invalid or missing |
RF01 | Transaction reference is not unique within the message |
RR01 | Specification of the debtor’s account or unique identification needed for reasons of regulatory requirements is insufficient or missing |
RR02 | Specification of the debtor’s name and/or address needed for regulatory requirements is insufficient or missing |
RR03 | Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing |
RR04 | Regulatory Reason |
RR05 | Regulatory or Central Bank Reporting information missing, incomplete or invalid |
RR06 | Tax information missing, incomplete or invalid |
RR07 | Remittance information structure does not comply with rules for payment type |
RR08 | Remittance information truncated to comply with rules for payment type |
RR09 | Structured creditor reference invalid or missing |
RR11 | Invalid or missing identification of a bank proprietary service |
RR12 | Invalid or missing identification required within a particular country or payment type |
RUTA | Return following investigation request and no remediation possible |
SL01 | Due to specific service offered by the Debtor Agent |
SL02 | Due to specific service offered by the Creditor Agent |
SL11 | Whitelisting service offered by the Debtor Agent; Debtor has not included the Creditor on its “Whitelist” (yet). In the Whitelist the |
SL12 | Blacklisting service offered by the Debtor Agent; Debtor included the Creditor on his “Blacklist”. In the Blacklist the Debtor may |
SL13 | Due to Maximum allowed Direct Debit Transactions per period service offered by the Debtor Agent |
SL14 | Due to Maximum allowed Direct Debit Transaction amount service offered by the Debtor Agent |
SP01 | Payment is stopped by account holder |
SP02 | Previously stopped by means of a stop payment advise |
SVNR | The card payment is returned since a cash amount rendered was not correct or goods or a service was not rendered to the customer, |
TM01 | Associated message was received after agreed processing cut-off time |
TRAC | Return following direct debit being removed from tracking process |
UPAY | Payment is not justified |
Responses | |
---|---|
Code | Description |
200 | OK |
{ "status": "OK", "payload": 1, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "return.payment.invalid.reason.code" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "additional.info.required" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "cancel.payment.legalReason1.max.length" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "generate.return.payment.failed" ] } |
Description:
This API rejects an incoming recall request
Method: PUT
Endpoint: /t2/rtgs/recall/request/reject
{ "actionUser": null, "additionalInformation": "string", "authUser": null, "reasonCode": "string", "sepaTrnHedSn": 0 //incoming camt056 ID } |
Reject Reason Codes | |
---|---|
Code | Description |
AC04 | Account number specified has been closed on the receiver’s books |
ADAC | Reported when the cancellation request cannot be processed because customer has not yet provided the debit authority on its account |
AGNT | Reported when the cancellation cannot be accepted because of an agent refuses to cancel |
AM04 | Amount of funds available to cover specified message amount is insufficient |
ARDT | Cancellation not accepted as the transaction has already been returned |
ARPL | Reported when the cancellation request cannot be processed because no reply has been received yet from the receiver of the request message |
CUST | Reported when the cancellation cannot be accepted because of a customer decision (Creditor) |
LEGL | Reported when the cancellation cannot be accepted because of regulatory rules |
NARR | Reason is provided as narrative information in the additional reason information |
NOAS | No response from beneficiary (to the cancellation request) |
NOOR | Original transaction (subject to cancellation) never received |
PTNA | Reported when the cancellation request cannot be accepted because the payment instruction has been passed to the next agent |
RQDA | Reported when authority is required by the Creditor to return the payment |
WSEQ | Reported when the cancellation request cannot be processed because the sequence referred to in the request is not valid |
IDMN | Complementing a Pending or Reject Status. Payment cancellation request cannot be accepted until an indemnity agreement is established |
Responses | |
---|---|
Code | Description |
200 | OK |
{ "status": "OK", "payload": 1, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "recall.request.reject.invalid.reason.code" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "additional.info.required" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "cancel.payment.legalReason1.max.length" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "recall.request.reject.failed" ] } |
Description:
This API returns an incoming Target2 transfer. If userName is not used, then SYSTEM will be added.
Method: PUT
Endpoint: /t2/rtgs/update/payment/return
{ "reasonCode": "AC04", "sepaTrnHedSn": 26499, "msgNmId": "pacs.008.001.08", "legalReason1":null, "actionUser": null, "authUser": null, } |
The same reason codes described in table above Return Reason Codes when accepting a recall request, are also used when returning a CBPR+ transfer
In case reasonCode
is NARR
then some additional info (up to 105 characters) required in property legalReason1
.
Responses | |
---|---|
Code | Description |
200 | OK |
{ "status": "OK", "payload": 1, "errorCode": null, "errors": null } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "return.payment.invalid.reason.code" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "additional.info.required" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "cancel.payment.legalReason1.max.length" ] } |
{ "status": "FAILURE", "payload": null, "errorCode": null, "errors": [ "generate.return.payment.failed" ] } |