Connector For SWIFT gpi

Tracker API Detailed Specification This document provides details of the APIs, including the request and response body structures, the element types and the associated code lists and constraints.

09 February 2018

Connector for SWIFT gpi Tracker API Detailed Specification Table of Contents

Table of Contents Table of Contents ...... 4 Preface ...... 6 1 API Set Overview ...... 7 1.1 List of APIs ...... 7 2 UpdatePaymentStatusRequest ...... 10 2.1 API Functionality ...... 10 2.2 Structure ...... 10 2.3 Constraints ...... 11 2.4 Building Blocks ...... 11 3 UpdatePaymentStatusResponse ...... 18 3.1 API Functionality ...... 18 3.2 Structure ...... 18 3.3 Building Blocks ...... 18 4 GetPaymentTransactionDetailsRequest ...... 19 4.1 API Functionality ...... 19 4.2 Structure ...... 19 4.3 Constraints ...... 19 4.4 Building Blocks ...... 19 5 GetPaymentTransactionDetailsResponse ...... 21 5.1 API Functionality ...... 21 5.2 Structure ...... 21 5.3 Constraints ...... 23 5.4 Building Blocks ...... 23 6 GetPaymentTransactionsRequest ...... 35 6.1 API Functionality ...... 35 6.2 Structure ...... 36 6.3 Constraints ...... 36 6.4 Building Blocks ...... 36 7 GetPaymentTransactionsResponse ...... 42 7.1 API Functionality ...... 42 7.2 Structure ...... 42 7.3 Constraints ...... 43 7.4 Building Blocks ...... 43 8 GetChangedPaymentTransactionsRequest ...... 51 8.1 API Functionality ...... 51 8.2 Structure ...... 51 8.3 Constraints ...... 51 8.4 Building Blocks ...... 51 9 GetChangedPaymentTransactionsResponse ...... 53 9.1 API Functionality ...... 53 9.2 Structure ...... 53 9.3 Constraints ...... 55 9.4 Building Blocks ...... 55

09 February 2018 4

Connector for SWIFT gpi Tracker API Detailed Specification

10 GetInvalidEventsRequest ...... 69 10.1 API Functionality ...... 69 10.2 Structure ...... 69 10.3 Constraints ...... 69 10.4 Building Blocks ...... 69 11 GetInvalidEventsResponse ...... 71 11.1 API Functionality ...... 71 11.2 Structure ...... 71 11.3 Constraints ...... 71 11.4 Building Blocks ...... 71 12 Types...... 75 12.1 Date Time ...... 75 12.2 Datatypes ...... 75 A.1 JSON – Snake Case ...... 83 A.2 JSON – Amount Representation: ...... 85

09 February 2018 5

Connector for SWIFT gpi Tracker API Detailed Specification Preface

Preface About this document This document provides details of the APIs, including the request and response body structures, the element types, and the associated code lists and constraints.

Intended audience This document is for the following audience: • Business analysts to understand the functionality of the API • Business architects to understand the functionality of the API and how to integrate the use of the API within their organisation • Software developers of applications using the API to assess the complexity of the API First edition This is the first edition of the document. Related documentation • Connector for SWIFT gpi Tracker API Specification • Connector for SWIFT gpi Tracker API JSON Schemas • Connector for SWIFT gpi Service Description • SWIFT gpi Service Description

09 February 2018 6

Connector for SWIFT gpi Tracker API Detailed Specification API Set Overview

1 API Set Overview 1.1 List of APIs The following table lists all APIs described in this book.

API Definition camt.a01.001.02 UpdatePaymentStatusRequest This API is a status confirmation update to inform the Tracker about the updated status of a given payment. camt.a01.002.02 This API is the response to a status confirmation update UpdatePaymentStatusResponse to inform the Tracker about the updated status of a given payment. camt.a02.001.02 This API is a payment query to get detailed information GetPaymentTransactionDetailsRequest regarding a given payment transaction. It requires the UETR to be known.

Examples of use cases are: • Debtor status check - debtor's agent or debtor wants to see the status • Creditor status check - creditor's agent or creditor wants to see the status

camt.a02.002.02 This API is the response to a payment query to get GetPaymentTransactionDetailsResponse detailed information regarding a given payment transaction.

Examples of use cases are: • Debtor status check - debtor's agent or debtor wants to see the status • Creditor status check - creditor's agent or creditor wants to see the status

camt.a03.001.02 This API is a payment transaction search to get GetPaymentTransactionsRequest transaction-level information regarding all payments that match the search criteria. To have full information of a given payment transaction, the GetPaymentTransactionDetailsRequest can be used.

Examples of use cases are: • Investigation by a participating institution based on criteria given by a customer, such as instructed amount, time of initiation • Flow monitoring, for instance to find payments that are "stuck" for which the institution is the beneficiary institution • Feed a dashboard - give all payment transactions with their last status

09 February 2018 7

Connector for SWIFT gpi Tracker API Detailed Specification API Set Overview

camt.a03.002.02 This API is the response to a payment transaction GetPaymentTransactionsResponse search to get transaction-level information regarding all payments that match the search criteria.

Examples of use cases are: • Investigation by a participating institution based on criteria given by a customer, such as instructed amount, time of initiation • Flow monitoring, for instance to find payments that are "stuck" for which the institution is the beneficiary institution • Feed a dashboard - give all payment transactions with their last status

camt.a04.001.02 This API is a delta query to get all payment update GetChangedPaymentTransactionsRequest information starting from a given date and time. This API allows synchronization of a local database with the Tracker database.

All use cases applicable for the get and search of payment transactions apply also for this API.

The use of the API to get the last changed payment transactions is driven by an architectural choice to feed a local database and to optimise the flow between the Tracker and the API caller.

camt.a04.002.02 This API is the response to a delta query to get all GetChangedPaymentTransactionsResponse payment update information starting from a given date and time. This API allows synchronization of a local database with the Tracker database.

All use cases applicable for the get and search of payment transactions apply also for this API.

The use of the API to get the last changed payment transactions is driven by an architectural choice to feed a local database and to optimise the flow between the Tracker and the API caller.

camt.a05.001.02 GetInvalidEventsRequest This API is a payment events query to get invalid events for payment transactions within a given time frame. An event is either a payment or a status confirmation.

The API is typically used for support or audit purposes, where all invalid messages sent or received are retrievable by one API call.

09 February 2018 8

Connector for SWIFT gpi Tracker API Detailed Specification API Set Overview

camt.a05.002.02 GetInvalidEventsResponse This API is a payment events response to a query to get invalid events for payment transactions within a given time frame. An event is either a payment or a status confirmation.

The API is typically used for support or audit purposes, where all invalid messages sent or received are retrievable by one API call.

09 February 2018 9

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

2 UpdatePaymentStatusRequest 2.1 API Functionality This API is a status confirmation update to inform the Tracker about the updated status of a given payment. Outline The UpdatePaymentStatusRequest API is composed of 5 BuildingBlocks: A. From The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). B. BusinessService Specifies the business service agreed between the two MessagingEndpoints under which rules this business message is exchanged. To be used when there is a choice of processing services or processing service levels. Example: 001 C. TransactionIdentification Contains the unique end to end transaction reference (UETR). Format is lowercase separated by hyphens. D. InstructionIdentification Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. E. PaymentStatus Contains the details on the payment status. 2.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

UpdatePaymentStatusRequest [1..1] From [1..1] IdentifierSet C3

BusinessService [1..1] Text

TransactionIdentification [1..1] Text

InstructionIdentification [1..1] Text

PaymentStatus [1..1]

{Or RawStatus [1..1] Text

Or} DetailedStatus [1..1]

Originator [1..1] IdentifierSet C3

09 February 2018 10

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

FundsAvailable [0..1] DateTime

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

ConfirmedAmount [1..1] Amount C2, C4

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C2

ToCurrency [1..1] CodeSet C2

ExchangeRate [1..1] Rate

ChargeAmount [0..*] Amount C2, C4 2.3 Constraints C1 ACSPReasonCode Reason must only be present if status contains ACSP. C2 ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. C3 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

C4 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217.

Note The decimal separator is a dot. 2.4 Building Blocks This chapter describes the BuildingBlocks of this API. 2.4.1 From Presence: [1..1] Definition: The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. Note The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier"

09 February 2018 11

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 2.4.2 BusinessService Presence: [1..1] Definition: Specifies the business service agreed between the two MessagingEndpoints under which rules this business message is exchanged. To be used when there is a choice of processing services or processing service levels. Example: 001 Datatype: "Max35Text" 2.4.3 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR). Format is lowercase separated by hyphens. Datatype: "Max40Text" 2.4.4 InstructionIdentification Presence: [1..1] Definition: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. Datatype: "Max35Text" 2.4.5 PaymentStatus Presence: [1..1] Definition: Contains the details on the payment status. PaymentStatus contains one of the following PaymentStatusType1Choice elements

Or Element Mult. Type Constr. No.

{Or RawStatus [1..1] Text

Or} DetailedStatus [1..1]

Originator [1..1] IdentifierSet C3

FundsAvailable [0..1] DateTime

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

ConfirmedAmount [1..1] Amount C2, C4

09 February 2018 12

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C2

ToCurrency [1..1] CodeSet C2

ExchangeRate [1..1] Rate

ChargeAmount [0..*] Amount C2, C4 2.4.5.1 RawStatus Presence: [1..1] Definition: Contains the status of the payment taken from field 79 of the MT 199. Datatype: "Max1850Text" 2.4.5.2 DetailedStatus Presence: [1..1] Definition: Contains the detailed status of a Payment. DetailedStatus contains the following StatusDetails1 elements

Or Element Mult. Type Constr. No.

Originator [1..1] IdentifierSet C3

FundsAvailable [0..1] DateTime

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

ConfirmedAmount [1..1] Amount C2, C4

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C2

ToCurrency [1..1] CodeSet C2

ExchangeRate [1..1] Rate

ChargeAmount [0..*] Amount C2, C4

2.4.5.2.1 Originator Presence: [1..1] Definition: Party that issues the status. Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

09 February 2018 13

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

2.4.5.2.2 FundsAvailable Presence: [0..1] Definition: Date and time at which the funds are available, as reported in the ACSC status update. Datatype: "ISODateTime"

2.4.5.2.3 TransactionStatus Presence: [1..1] Definition: Specifies the status of the transaction. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet Constraints • ACSPReasonCode Reason must only be present if status contains ACSP.

2.4.5.2.3.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC1 AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage : this can be used by the first agent to report to the debtor that the transaction has been completed. Warning : this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement

1 In the SWIFT gpi Customer Credit Transfer (gCCT) Rulebook, ACSC is defined as “settlement completed ; creditor has been credited or the funds have been made available to the creditor, final status”.

09 February 2018 14

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

2.4.5.2.3.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

2.4.5.2.4 ForwardedAgent Presence: [0..1] Definition: Specifies the BIC of the entity to which the entity reporting the status has forwarded the payment transaction. This element can only be used in case the status is ACSP and the reason is G000 or G001. Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

2.4.5.2.5 ConfirmedAmount Presence: [1..1] Definition: The actual amount that has been paid to the ultimate beneficiary, after all charges etc. have been deducted. Impacted by: C2 "ActiveOrHistoricCurrency", C4 "CurrencyAmount"

Note More codes are expected to be defined for this element when the code list is next enhanced as part of ISO 20022 maintenance; this code may therefore change to "ACCC" in a future release.

09 February 2018 15

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 2.4.5.2.6 ForeignExchangeDetails Presence: [0..1] Definition: Specifies the exchange rate details between two currencies. ForeignExchangeDetails contains the following ForeignExchangeTerms32 elements

Or Element Mult. Type Constr. No.

FromCurrency [1..1] CodeSet C2

ToCurrency [1..1] CodeSet C2

ExchangeRate [1..1] Rate

2.4.5.2.6.1 FromCurrency Presence: [1..1] Definition: Currency for which a foreign exchange is required. Impacted by: C2 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 2.4.5.2.6.2 ToCurrency Presence: [1..1] Definition: Currency resulting from a foreign exchange trade. Impacted by: C2 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged.

09 February 2018 16

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

2.4.5.2.6.3 ExchangeRate Presence: [1..1] Definition: The value of one currency expressed in relation to another currency. ExchangeRate expresses the ratio between FromCurrency and ToCurrency (ExchangeRate = FromCurrency/ ToCurrency). Datatype: "BaseOneRate"

2.4.5.2.7 ChargeAmount Presence: [0..*] Definition: Amount of money asked or paid for the charge. Impacted by: C2 "ActiveOrHistoricCurrency", C4 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot.

09 February 2018 17

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusResponse

3 UpdatePaymentStatusResponse 3.1 API Functionality This API is the response to a status confirmation update to inform the Tracker about the updated status of a given payment. Outline The UpdatePaymentStatusResponse API is composed of 1 BuildingBlocks: A. NetworkReference Reference assigned by the network. 3.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

UpdatePaymentStatusResponse [1..1] NetworkReference [1..1] Text

3.3 Building Blocks This chapter describes the BuildingBlocks of this API. 3.3.1 NetworkReference Presence: [1..1] Definition: Reference assigned by the network. Datatype: "Max350Text"

09 February 2018 18

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsRequest

4 GetPaymentTransactionDetailsRequest 4.1 API Functionality This API is a payment query to get detailed information regarding a given payment transaction. It requires the UETR to be known. Examples of use cases are: • Debtor status check - debtor's agent or debtor wants to see the status • Creditor status check - creditor's agent or creditor wants to see the status Outline The GetPaymentTransactionDetailsRequest API is composed of 2 BuildingBlocks: A. MyInstitution Specifies the institution which payments are requested. B. TransactionIdentification Contains the unique end to end transaction reference (UETR) of a payment. 4.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetPaymentTransactionDetailsRequest [1..1] MyInstitution [1..250] IdentifierSet C1

TransactionIdentification [1..1] Text 4.3 Constraints C1 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 4.4 Building Blocks This chapter describes the BuildingBlocks of this API. 4.4.1 MyInstitution Presence: [1..250] Definition: Specifies the institution which payments are requested. Impacted by: C1 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

09 February 2018 19

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsRequest

4.4.2 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR) of a payment. Datatype: "Max40Text"

09 February 2018 20

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

5 GetPaymentTransactionDetailsResponse 5.1 API Functionality This API is the response to a payment query to get detailed information regarding a given payment transaction. Examples of use cases are: • Debtor status check - debtor's agent or debtor wants to see the status • Creditor status check - creditor's agent or creditor wants to see the status Outline The GetPaymentTransactionDetailsResponse API is composed of 6 BuildingBlocks: A. TransactionIdentification Contains the unique end to end transaction reference (UETR) of a payment. B. TransactionStatus Specifies the status of a transaction, in a coded form. C. InitiationTime Date and time at which the message enters the SWIFT gpi system. D. CompletionTime Time at which the instructed bank reports that the transaction has been completed. Date and time based on the creation date of the status confirmation containing a final status ACSC. E. LastUpdateTime Last date and time at which the status of this transaction was updated. F. PaymentEvent This groups the information of an event, that is, of a payment message or status confirmation update. It is repeated as many times as there are events to be returned. 5.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetPaymentTransactionDetailsResponse [1..1] TransactionIdentification [1..1] Text

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

InitiationTime [1..1] DateTime

CompletionTime [0..1] DateTime

LastUpdateTime [0..1] DateTime

PaymentEvent [0..*]

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

09 February 2018 21

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

BusinessService [1..1] Text

Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

InvalidityDescription [0..1] Text

SenderReference [0..1] Text

InstructionIdentification [1..1] Text

TransactionStatus [0..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C4

FundsAvailable [0..1] DateTime

From [0..1] IdentifierSet C4

To [0..1] IdentifierSet C4

Originator [0..1] IdentifierSet C4

CreditorAgent [0..1] IdentifierSet C4

PreviousInstructingAgent [0..1] IdentifierSet C4

SenderAcknowledgementReceipt [1..1] DateTime

ReceivedDate [0..1] DateTime

InstructedAmount [0..1] Amount C3, C5

ConfirmedAmount [0..1] Amount C3, C5

InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet

ChargeAmount [0..*] Amount C3, C5

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate

UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text

LastUpdateTime [1..1] DateTime

09 February 2018 22

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

5.3 Constraints C1 ACSPReasonCode Reason must only be present if status contains ACSP. C2 ActiveCurrency The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged.

C3 ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged.

C4 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

C5 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. C6 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note Note: The decimal separator is a dot. 5.4 Building Blocks This chapter describes the BuildingBlocks of this API. 5.4.1 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR) of a payment. Datatype: "Max40Text" 5.4.2 TransactionStatus Presence: [1..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

09 February 2018 23

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Constraints • ACSPReasonCode Reason must only be present if Status contains ACSP. 5.4.2.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement

5.4.2.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator.

09 February 2018 24

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

5.4.3 InitiationTime Presence: [1..1] Definition: Date and time at which the message enters the SWIFT gpi system. Datatype: "ISODateTime" 5.4.4 CompletionTime Presence: [0..1] Definition: Time at which the instructed bank reports that the transaction has been completed. Date and time based on the creation date of the status confirmation containing a final status ACSC. Datatype: "ISODateTime" 5.4.5 LastUpdateTime Presence: [0..1] Definition: Last date and time at which the status of this transaction was updated. Datatype: "ISODateTime" 5.4.6 PaymentEvent Presence: [0..*] Definition: This groups the information of an event, that is, of a payment message or status confirmation update. It is repeated as many times as there are events to be returned. PaymentEvent contains the following PaymentEvent1 elements

Or Element Mult. Type Constr. No.

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

BusinessService [1..1] Text

Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

InvalidityDescription [0..1] Text

SenderReference [0..1] Text

InstructionIdentification [1..1] Text

TransactionStatus [0..1] C1

Status [1..1] CodeSet

09 February 2018 25

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C4

FundsAvailable [0..1] DateTime

From [0..1] IdentifierSet C4

To [0..1] IdentifierSet C4

Originator [0..1] IdentifierSet C4

CreditorAgent [0..1] IdentifierSet C4

PreviousInstructingAgent [0..1] IdentifierSet C4

SenderAcknowledgementReceipt [1..1] DateTime

ReceivedDate [0..1] DateTime

InstructedAmount [0..1] Amount C3, C5

ConfirmedAmount [0..1] Amount C3, C5

InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet

ChargeAmount [0..*] Amount C3, C5

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate

UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text

LastUpdateTime [1..1] DateTime 5.4.6.1 NetworkReference Presence: [1..1] Definition: Reference assigned by the network when sending the payment. Datatype: "Max350Text" 5.4.6.2 MessageNameIdentification Presence: [1..1] Definition: Specifies the original message name identifier to which the message refers. Datatype: "Max35Text" 5.4.6.3 BusinessService Presence: [1..1]

09 February 2018 26

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Definition: Specifies the business service agreed between the two MessagingEndpoints under which rules this business message is exchanged. To be used when there is a choice of processing services or processing service levels. Example: 001 Datatype: "Max35Text" 5.4.6.4 Valid Presence: [1..1] Definition: Indicates if a payment is consistent (YES) or not (NO). Datatype: One of the following values must be used (see "YesNoIndicator" ): • Meaning When True: Yes • Meaning When False: No 5.4.6.5 InvalidityReason Presence: [0..1] Definition: Contains the additional information in case the event is not a valid component of a payment transaction. Datatype: "InvalidPaymentsEvent1Code" 5.4.6.6 InvalidityDescription Presence: [0..1] Definition: Contains a textual description as to why the event is not a valid component of a payments transaction. Datatype: "Max350Text" 5.4.6.7 SenderReference Presence: [0..1] Definition: Identification assigned by the sender of the message. For MT format this is the MUR. Datatype: "Max30Text" 5.4.6.8 InstructionIdentification Presence: [1..1] Definition: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. Datatype: "Max35Text" 5.4.6.9 TransactionStatus Presence: [0..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

09 February 2018 27

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

Constraints • ACSPReasonCode Reason must only be present if status contains ACSP. 5.4.6.9.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition

RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.

ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement. 5.4.6.9.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator.

09 February 2018 28

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

5.4.6.10ForwardedAgent Presence: [0..1] Definition: Specifies the BIC of the entity to which the entity reporting the status has forwarded the payment transaction. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.11FundsAvailable Presence: [0..1] Definition: Date and time at which the funds are available, as reported in the ACSC status update. Must only be used when TransactionStatus is "ACSC". Datatype: "ISODateTime" 5.4.6.12From Presence: [0..1] Definition: The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. Note The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.13To Presence: [0..1] Definition: The MessagingEndpoint designated by the sending MessagingEndpoint to be the recipient who will ultimately process this business message. Note The receiving MessagingEndpoint might be different from the receiving address potentially contained in the transport header (as defined in the transport layer). Impacted by: C4 "AnyBIC"

09 February 2018 29

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.14Originator Presence: [0..1] Definition: Party that issues the status. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.15CreditorAgent Presence: [0..1] Definition: Financial institution servicing an account for the creditor. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.16PreviousInstructingAgent Presence: [0..1] Definition: Agent immediately prior to the instructing agent. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 5.4.6.17SenderAcknowledgementReceipt Presence: [1..1] Definition: Date and time at which the sender acknowledged receipt of the message. Datatype: "ISODateTime"

09 February 2018 30

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

5.4.6.18ReceivedDate Presence: [0..1] Definition: Date and time at which the message was acknowledged by the receiver. Datatype: "ISODateTime" 5.4.6.19InstructedAmount Presence: [0..1] Definition: Amount of money to be moved between the debtor (ordering customer) and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 5.4.6.20ConfirmedAmount Presence: [0..1] Definition: The actual amount that has been paid to the ultimate beneficiary, after all charges etc. have been deducted. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints ActiveOrHistoricCurrency The currency Code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 5.4.6.21InterbankSettlementAmount Presence: [0..1] Definition: Amount of money moved between the instructing agent and the instructed agent. Impacted by: C2 "ActiveCurrency", C6 "CurrencyAmount" Datatype: "ActiveCurrencyAndAmount" Constraints • ActiveCurrency

09 February 2018 31

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 5.4.6.22InterbankSettlementDate Presence: [0..1] Definition: Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due. Datatype: "ISODate" 5.4.6.23ChargeBearer Presence: [0..1] Definition: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Datatype: "ChargeBearerType3Code"

Code Name Name Definition SHAR Shared In a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor. In a direct debit context, means that transaction charges on the sender side are to be borne by the creditor, transaction charges on the receiver side are to be borne by the debtor.

DEBT BorneByDebtor All transaction charges are to be borne by the debtor. CRED BorneByCreditor All transaction charges are to be borne by the creditor.

5.4.6.24ChargeAmount Presence: [0..*] Definition: Amount of money asked or paid for the charge. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot.

09 February 2018 32

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

5.4.6.25ForeignExchangeDetails Presence: [0..1] Definition: Specifies the exchange rate details between two currencies. ForeignExchangeDetails contains the following ForeignExchangeTerms32 elements

Or Element Mult. Type Constr. No.

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate 5.4.6.25.1 From Currency Presence: [1..1] Definition: Currency for which a foreign exchange is required. Impacted by: C3 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 5.4.6.25.2 ToCurrency Presence: [1..1] Definition: Currency resulting from a foreign exchange trade. Impacted by: C3 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 5.4.6.25.3 ExchangeRate Presence: [1..1] Definition: The value of one currency expressed in relation to another currency. ExchangeRate expresses the ratio between FromCurrency and ToCurrency (ExchangeRate = FromCurrency/ ToCurrency). Datatype: "BaseOneRate" 5.4.6.26 UpdatePayment Presence: [0..1] Definition: Implements the correlation between a payment message and a status update on it. Contains the network reference of the payment for which the status confirmation was applicable.

09 February 2018 33

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

Datatype: "Max35Text" 5.4.6.27 DuplicateMessageReference Presence: [0..1] Definition: Network reference of the payment that is the original recorded payment. Datatype: "Max50Text" 5.4.6.28 CopiedBusinessService Presence: [0..1] Definition: Specifies the copied business service of the market infrastructure. Datatype: "Max35Text" 5.4.6.29 LastUpdateTime Presence: [1..1] Definition: Last date and time at which the status of this payment event was updated. Datatype: "ISODateTime"

09 February 2018 34

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

6 GetPaymentTransactionsRequest 6.1 API Functionality This API is a payment transaction search to get transaction-level information regarding all payments that match the search criteria. To have full information of a given payment transaction, the GetPaymentTransactionDetailsRequest can be used. Examples of use cases are: • Investigation by a participating institution based on criteria given by a customer, such as instructed amount, time of initiation • Flow monitoring, for instance to find payments that are "stuck" for which the institution is the beneficiary institution • Feed a dashboard - give all payment transactions with their last status Outline The GetPaymentTransactionsRequest API is composed of 10 BuildingBlocks: A. MyInstitution Specifies an institution that is owned by the sender, for which the sender can ask payment transaction details. B. TimeWindow Time window for this institution to which the search applies. C. Agent Identifies agent(s) involved in a payment transaction. D. Location Specifies the location of the search. E. InstructionIdentification Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. F. TransactionStatus Specifies the status of a transaction, in a coded form. G. Amount Specifies the amount range for a given currency and amount type. H. Event Specifies one of the states of the payment transaction. I. MaximumNumber Indicates the maximum number of entries returned. J. More Contains the token to get the next set of responses.

09 February 2018 35

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

6.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetPaymentTransactionsRequest [1..1] MyInstitution [1..250] IdentifierSet C2

TimeWindow [1..1] ±

Agent [0..*]

AnyBIC [1..*] IdentifierSet C2

Role [1..1] CodeSet

Location [0..1] CodeSet

InstructionIdentification [0..1] Text

TransactionStatus [0..*] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

Amount [0..1]

Type [1..1] CodeSet

Currency [0..1] CodeSet C3

FromAmount [1..1] Amount

ToAmount [1..1] Amount

Event [1..1] CodeSet

MaximumNumber [1..1] Quantity

More [0..1] Text 6.3 Constraints C1 ACSPReasonCode Reason must only be present if status contains ACSP.

C2 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

C3 ValidationByTable Must be a valid currency code which is registered with the ISO 4217 Maintenance Agency, and consist of three contiguous letters. 6.4 Building Blocks This chapter describes the BuildingBlocks of this API.

09 February 2018 36

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

6.4.1 MyInstitution Presence: [1..250] Definition: Specifies an institution that is owned by the sender, for which the sender can ask payment transaction details. Impacted by: C2 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 6.4.2 TimeWindow Presence: [1..1] Definition: Time window for this institution to which the search applies. TimeWindow contains the following elements (see "DateTimePeriodDetails" for details)

Or Element Mult. Type Constr. No.

FromDateTime [1..1] DateTime

ToDateTime [1..1] DateTime

6.4.3 Agent Presence: [0..*] Definition: Identifies agent(s) involved in a payment transaction. Agent contains the following AgentType1 elements

Or Element Mult. Type Constr. No.

AnyBIC [1..*] IdentifierSet C2

Role [1..1] CodeSet 6.4.3.1 AnyBIC Presence: [1..*] Definition: Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362 "Banking - Banking telecommunication messages - Business identifier code (BIC)". Impacted by: C2 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

09 February 2018 37

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

6.4.3.2 Role Presence: [1..1] Definition: Specifies the role of the party in the payment chain. Datatype: "PaymentsPartyType1Code" 6.4.4 Location Presence: [0..1] Definition: Specifies the location of the search. Datatype: "Location1Code"

Code Name Name Definition

OTHR AtAnotherInstitution At another institution

MYIN AtMyInstitution At my institution.

6.4.5 InstructionIdentification Presence: [0..1] Definition: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. Datatype: "Max35Text" 6.4.6 TransactionStatus Presence: [0..*] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

Constraints • ACSPReasonCode Reason must only be present if status contains ACSP. 6.4.6.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.

09 February 2018 38

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

6.4.6.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition

G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow.

G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure.

G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator.

G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

6.4.7 Amount Presence: [0..1] Definition: Specifies the amount range for a given currency and amount type. Amount contains the following AmountType1 elements

Or Element Mult. Type Constr. No.

Type [1..1] CodeSet

09 February 2018 39

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

Currency [0..1] CodeSet C3

FromAmount [1..1] Amount

ToAmount [1..1] Amount 6.4.7.1 Type Presence: [1..1] Definition: Specifies the type of amount. Datatype: "TypeOfAmount8Code"

Code Name Name Definition CONF ConfirmedAmount The actual amount that has been paid to the ultimate beneficiary, after all charges etc. have been deducted. INST InstructedAmount Amount of money to be moved between the debtor (ordering customer) and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.

6.4.7.2 Currency Presence: [0..1] Definition: Currency code of the ranged amount. Impacted by: C3 "ValidationByTable" Datatype: "CurrencyCode" Constraints • ValidationByTable 6.4.7.3 FromAmount Presence: [1..1] Definition: Lowest amount value Datatype: "ImpliedCurrencyAndAmount" 6.4.7.4 ToAmount Presence: [1..1] Definition: Highest amount value Datatype: "ImpliedCurrencyAndAmount" 6.4.8 Event Presence: [1..1] Definition: Specifies one of the states of the payment transaction. Datatype: "PaymentTransactionState1Code"

Code Name Name Definition CRED Credited The transaction is credited.

09 February 2018 40

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

RCCA ReceivedAtCreditorAgent The transaction is received at the creditor's agent. RCMY ReceivedByMyInstitution The transaction is received by my institution. STMY SentByMyInstitution The transaction is sent by my institution.

STDA SentByDebtorAgent The transaction is sent by the debtor's agent.

6.4.9 MaximumNumber Presence: [1..1] Definition: Indicates the maximum number of entries returned. Datatype: "Number" 6.4.10 More Presence: [0..1] Definition: Contains the token to get the next set of responses. Datatype: "Max350Text"

09 February 2018 41

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

7 GetPaymentTransactionsResponse 7.1 API Functionality This API is the response to a payment transaction search to get transaction-level information regarding all payments that match the search criteria. Examples of use cases are: • Investigation by a participating institution based on criteria given by a customer, such as instructed amount, time of initiation • Flow monitoring, for instance to find payments that are "stuck" for which the institution is the beneficiary institution • Feed a dashboard - give all payment transactions with their last status Outline The GetPaymentTransactionsResponse API is composed of 3 BuildingBlocks: A. PaymentTransaction Contains the payment transactions that meet the search criteria. B. TotalNumber Contains the total number of returned result entries. C. More Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. 7.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetPaymentTransactionsResponse [1..1] PaymentTransaction [1..*]

TransactionIdentification [1..1] Text

MyInstitution [1..1] IdentifierSet C3

Role [1..1] CodeSet

EventTime [1..1] DateTime

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

PreviousInstructingAgent [0..1] IdentifierSet C3

Agents [1..*]

From [0..1] IdentifierSet C3

To [0..1] IdentifierSet C3

TransactionStatus [1..1] C1

Status [1..1] CodeSet

09 February 2018 42

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

Received [1..1] Indicator

CreditorAgent [0..1] IdentifierSet C3

InitiationTime [1..1] DateTime

CompletionTime [0..1] DateTime

InstructedAmount [1..1] Amount C2, C4

LastUpdateTime [1..1] DateTime

TotalNumber [1..1] Quantity

More [0..1] Text 7.3 Constraints C1 ACSPReasonCode Reason must only be present if status contains ACSP.

C2 ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged.

C3 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

C4 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 7.4 Building Blocks This chapter describes the BuildingBlocks of this API. 7.4.1 PaymentTransaction Presence: [1..*] Definition: Contains the payment transactions that meet the search criteria. PaymentTransaction contains the following PaymentTransaction72 elements

Or Element Mult. Type Constr. No.

TransactionIdentification [1..1] Text

MyInstitution [1..1] IdentifierSet C3

Role [1..1] CodeSet

09 February 2018 43

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

EventTime [1..1] DateTime

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

PreviousInstructingAgent [0..1] IdentifierSet C3

Agents [1..*]

From [0..1] IdentifierSet C3

To [0..1] IdentifierSet C3

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

Received [1..1] Indicator

CreditorAgent [0..1] IdentifierSet C3

InitiationTime [1..1] DateTime

CompletionTime [0..1] DateTime

InstructedAmount [1..1] Amount C2, C4

LastUpdateTime [1..1] DateTime 7.4.1.1 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR) of a payment. Datatype: "Max40Text" 7.4.1.2 MyInstitution Presence: [1..1] Definition: Specifies an institution that is owned by the sender, for which the sender can ask payment transaction details. Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.3 Role Presence: [1..1] Definition: Specifies the role of the party in the payment chain. Datatype: "PaymentsPartyType1Code"

09 February 2018 44

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

7.4.1.4 EventTime Presence: [1..1] Definition: Time determined by the Role that the entity defined in MyInstitution is playing in this transaction. Datatype: "ISODateTime" 7.4.1.5 TransactionStatus Presence: [1..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

Constraints • ACSPReasonCode Reason must only be present if status contains ACSP. 7.4.1.5.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition

RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.

ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement 7.4.1.5.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

09 February 2018 45

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

7.4.1.6 PreviousInstructingAgent Presence: [0..1] Definition: Agent immediately prior to the instructing agent. Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.7 Agents Presence: [1..*] Definition: Identifies the agents currently participating in a transaction. Agents contains the following PaymentEvent2 elements

Or Element Mult. Type Constr. No.

From [0..1] IdentifierSet C3

To [0..1] IdentifierSet C3

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C3

Received [1..1] Indicator

09 February 2018 46

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

7.4.1.7.1 From Presence: [0..1] Definition: The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. Note The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.7.2 To Presence: [0..1] Definition: The MessagingEndpoint designated by the sending MessagingEndpoint to be the recipient who will ultimately process this business message. Note The receiving MessagingEndpoint might be different from the receiving address potentially contained in the transport header (as defined in the transport layer). Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.7.3 TransactionStatus Presence: [1..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

Constraints • ACSPReasonCode Reason must only be present if status contains ACSP. 7.4.1.7.3.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list.

09 February 2018 47

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

7.4.1.7.3.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

7.4.1.7.4 ForwardedAgent Presence: [0..1] Definition: Specifies the BIC of the entity to which the entity reporting the status has forwarded the payment transaction. Impacted by: C3 "AnyBIC"

09 February 2018 48

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.7.5 Received Presence: [1..1] Definition: Indicates whether a payment has been received or not. Datatype: One of the following values must be used (see "YesNoIndicator" ): • Meaning When True: Yes • Meaning When False: No 7.4.1.8 CreditorAgent Presence: [0..1] Definition: Financial institution servicing an account for the creditor. Impacted by: C3 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 7.4.1.9 InitiationTime Presence: [1..1] Definition: Date and time at which the message enters the SWIFT gpi system. Datatype: "ISODateTime" 7.4.1.10CompletionTime Presence: [0..1] Definition: Time at which the instructed bank reports that the transaction has been completed. Date and time based on the creation date of the status confirmation containing a final status ACSC. Datatype: "ISODateTime" 7.4.1.11InstructedAmount Presence: [1..1] Definition: 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. This amount has to be transported unchanged through the transaction chain. Impacted by: C2 "ActiveOrHistoricCurrency", C4 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency

09 February 2018 49

Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 7.4.1.12LastUpdateTime Presence: [1..1] Definition: Last date and time at which the status of this transaction was updated. Datatype: "ISODateTime" 7.4.2 TotalNumber Presence: [1..1] Definition: Contains the total number of returned result entries. Datatype: "Number" 7.4.3 More Presence: [0..1] Definition: Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. Datatype: "Max350Text"

09 February 2018 50

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsRequest

8 GetChangedPaymentTransactionsRequest 8.1 API Functionality This API is a delta query to get all payment update information starting from a given date and time. This API allows synchronization of a local database with the Tracker database. All use cases applicable for the get and search of payment transactions apply also for this API. The use of the API to get the last changed payment transactions is driven by an architectural choice to feed a local database and to optimise the flow between the Tracker and the API caller. Outline The GetChangedPaymentTransactionsRequest API is composed of 3 BuildingBlocks: A. MyInstitution Specifies the institution which payments are requested. B. StartTime Contains the start date and time as from which the last changed payment transactions must be provided. C. More Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. 8.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetChangedPaymentTransactionsRequest [1..1] C2 MyInstitution [1..250] IdentifierSet C1

StartTime [0..1] DateTime

More [0..1] Text 8.3 Constraints C1 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

C2 StartTimeOrMoreMustBePresent StartTime or More must be present. If both are present, then the StartTime must be the same as on the previous request from which the More token has been taken. Note This constraint is defined at the API level. 8.4 Building Blocks This chapter describes the BuildingBlocks of this API.

09 February 2018 51

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsRequest

8.4.1 MyInstitution Presence: [1..250] Definition: Specifies the institution which payments are requested. Impacted by: C1 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 8.4.2 StartTime Presence: [0..1] Definition: Contains the start date and time as from which the last changed payment transactions must be provided. Datatype: "ISODateTime" 8.4.3 More Presence: [0..1] Definition: Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. Datatype: "Max350Text"

09 February 2018 52

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

9 GetChangedPaymentTransactionsResponse 9.1 API Functionality This API is the response to a delta query to get all payment update information starting from a given date and time. This API allows synchronization of a local database with the Tracker database. All use cases applicable for the get and search of payment transactions apply also for this API. The use of the API to get the last changed payment transactions is driven by an architectural choice to feed a local database and to optimise the flow between the tracker and the API caller. Outline The GetChangedPaymentTransactionsResponse API is composed of 2 BuildingBlocks: A. PaymentTransaction Contains the payment transactions that meet the search criteria. B. More Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. 9.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetChangedPaymentTransactionsResponse [1..1] PaymentTransaction [0..*]

TransactionIdentification [1..1] Text

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

InitiationTime [1..1] DateTime

CompletionTime [0..1] DateTime

LastUpdateTime [1..1] DateTime

PaymentEvent [1..*]

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

BusinessService [1..1] Text

Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

09 February 2018 53

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

InvalidityDescription [0..1] Text

SenderReference [0..1] Text

InstructionIdentification [1..1] Text

TransactionStatus [0..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C4

FundsAvailable [0..1] DateTime

From [0..1] IdentifierSet C4

To [0..1] IdentifierSet C4

Originator [0..1] IdentifierSet C4

CreditorAgent [0..1] IdentifierSet C4

PreviousInstructingAgent [0..1] IdentifierSet C4

SenderAcknowledgementReceipt [1..1] DateTime

ReceivedDate [0..1] DateTime

InstructedAmount [0..1] Amount C3, C5

ConfirmedAmount [0..1] Amount C3, C5

InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet

ChargeAmount [0..*] Amount C3, C5

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate

UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text

LastUpdateTime [1..1] DateTime

More [0..1] Text

09 February 2018 54

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

9.3 Constraints C1 ACSPReasonCode Reason must only be present if status contains ACSP. C2 ActiveCurrency The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged.

C3 ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. C4 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. C5 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note Note: The decimal separator is a dot. C6 CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 9.4 Building Blocks This chapter describes the BuildingBlocks of this API. 9.4.1 PaymentTransaction Presence: [0..*]

Definition: Contains the payment transactions that meet the search criteria. PaymentTransaction contains the following PaymentTransaction73 elements

Or Element Mult. Type Constr. No.

TransactionIdentification [1..1] Text

TransactionStatus [1..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

InitiationTime [1..1] DateTime

09 February 2018 55

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

CompletionTime [0..1] DateTime

LastUpdateTime [1..1] DateTime

PaymentEvent [1..*]

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

BusinessService [1..1] Text

Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

InvalidityDescription [0..1] Text

SenderReference [0..1] Text

InstructionIdentification [1..1] Text

TransactionStatus [0..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C4

FundsAvailable [0..1] DateTime

From [0..1] IdentifierSet C4

To [0..1] IdentifierSet C4

Originator [0..1] IdentifierSet C4

CreditorAgent [0..1] IdentifierSet C4

PreviousInstructingAgent [0..1] IdentifierSet C4

SenderA cknowledgementReceipt [1..1] DateTime

ReceivedDate [0..1] DateTime

InstructedAmount [0..1] Amount C3, C5

ConfirmedAmount [0..1] Amount C3, C5

InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet

ChargeAmount [0..*] Amount C3, C5

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C3

09 February 2018 56

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate

UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text

LastUpdateTime [1..1] DateTime

9.4.1.1 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR) of a payment. Datatype: "Max40Text" 9.4.1.2 TransactionStatus Presence: [1..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet

Constraints • ACSPReasonCode Reason must only be present if status contains ACSP. 9.4.1.2.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list. Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

09 February 2018 57

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

9.4.1.2.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

9.4.1.3 InitiationTime Presence: [1..1] Definition: Date and time at which the message enters the SWIFT gpi system. Datatype: "ISODateTime" 9.4.1.4 CompletionTime Presence: [0..1] Definition: Time at which the instructed bank reports that the transaction has been completed.

09 February 2018 58

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

Date and time based on the creation date of the status confirmation containing a final status ACSC. Datatype: "ISODateTime" 9.4.1.5 LastUpdateTime Presence: [1..1] Definition: Last date and time at which the status of this transaction was updated. Datatype: "ISODateTime" 9.4.1.6 PaymentEvent Presence: [1..*] Definition: This groups the information of an event, that is, of a payment message or status confirmation update. It is repeated as many times as there are events to be returned. PaymentEvent contains the following PaymentEvent1 elements

Or Element Mult. Type Constr. No.

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

BusinessService [1..1] Text

Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

InvalidityDescription [0..1] Text

SenderReference [0..1] Text

InstructionIdentification [1..1] Text

TransactionStatus [0..1] C1

Status [1..1] CodeSet

Reason [0..1] CodeSet

ForwardedAgent [0..1] IdentifierSet C4

FundsAvailable [0..1] DateTime

From [0..1] IdentifierSet C4

To [0..1] IdentifierSet C4

Originator [0..1] IdentifierSet C4

CreditorAgent [0..1] IdentifierSet C4

PreviousInstructingAgent [0..1] IdentifierSet C4

SenderAcknowledgementReceipt [1..1] DateTime

ReceivedDate [0..1] DateTime

09 February 2018 59

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

InstructedAmount [0..1] Amount C3, C5

ConfirmedAmount [0..1] Amount C3, C5

InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet

ChargeAmount [0..*] Amount C3, C5

ForeignExchangeDetails [0..1]

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate

UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text

LastUpdateTime [1..1] DateTime 9.4.1.6.1 NetworkReference Presence: [1..1] Definition: Reference assigned by the network when sending the payment. Datatype: "Max350Text" 9.4.1.6.2 MessageNameIdentification Presence: [1..1] Definition: Specifies the original message name identifier to which the message refers. Datatype: "Max35Text" 9.4.1.6.3 BusinessService Presence: [1..1] Definition: Specifies the business service agreed between the two MessagingEndpoints under which rules this business message is exchanged. To be used when there is a choice of processing services or processing service levels. Example: 001 Datatype: "Max35Text" 9.4.1.6.4 Valid Presence: [1..1] Definition: Indicates if a payment is consistent (YES) or not (NO). Datatype: One of the following values must be used (see "YesNoIndicator" ): • Meaning When True: Yes • Meaning When False: No

09 February 2018 60

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

9.4.1.6.5 InvalidityReason Presence: [0..1] Definition: Contains the additional information in case the event is not a valid component of a payment transaction. Datatype: "InvalidPaymentsEvent1Code" 9.4.1.6.6 InvalidityDescription Presence: [0..1] Definition: Contains a textual description as to why the event is not a valid component of a payments transaction. Datatype: "Max350Text" 9.4.1.6.7 SenderReference Presence: [0..1] Definition: Identification assigned by the sender of the message. For MT format this is the MUR. Datatype: "Max30Text" 9.4.1.6.8 InstructionIdentification Presence: [1..1] Definition: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. Datatype: "Max35Text" 9.4.1.6.9 TransactionStatus Presence: [0..1] Definition: Specifies the status of a transaction, in a coded form. Impacted by: C1 "ACSPReasonCode" TransactionStatus contains the following PaymentStatus3 elements

Or Element Mult. Type Constr. No.

Status [1..1] CodeSet

Reason [0..1] CodeSet Constraints • ACSPReasonCode Reason must only be present if Status contains ACSP. 9.4.1.6.9.1 Status Presence: [1..1] Definition: Reason for the status, as published in an external reason code list.

09 February 2018 61

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

Datatype: "TransactionIndividualStatus4Code"

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement

9.4.1.6.9.2 Reason Presence: [0..1] Definition: Provides more details on the status in process. Datatype: "PaymentReason1Code"

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow.

09 February 2018 62

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

9.4.1.6.10 ForwardedAgent Presence: [0..1] Definition: Specifies the BIC of the entity to which the entity reporting the status has forwarded the payment transaction. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 9.4.1.6.11 FundsAvailable Presence: [0..1] Definition: Date and time at which the funds are available, as reported in the ACSC status update. Must only be used when TransactionStatus is "ACSC". Datatype: "ISODateTime" 9.4.1.6.12 From Presence: [0..1] Definition: The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. Note The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 9.4.1.6.13 To Presence: [0..1] Definition: The MessagingEndpoint designated by the sending MessagingEndpoint to be the recipient who will ultimately process this business message. Note The receiving MessagingEndpoint might be different from the receiving address potentially contained in the transport header (as defined in the transport layer). Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC

09 February 2018 63

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 9.4.1.6.14 Originator Presence: [0..1] Definition: Party that issues the status. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 9.4.1.6.15 CreditorAgent Presence: [0..1] Definition: Financial institution servicing an account for the creditor. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

9.4.1.6.16 PreviousInstructingAgent Presence: [0..1] Definition: Agent immediately prior to the instructing agent. Impacted by: C4 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 9.4.1.6.17 SenderAcknowledgementReceipt Presence: [1..1] Definition: Date and time at which the sender acknowledged receipt of the message. Datatype: "ISODateTime" 9.4.1.6.18 ReceivedDate Presence: [0..1]

09 February 2018 64

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

Definition: Date and time at which the message was acknowledged by the receiver. Datatype: "ISODateTime" 9.4.1.6.19 InstructedAmount Presence: [0..1] Definition: Amount of money to be moved between the debtor (ordering customer) and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 9.4.1.6.20 ConfirmedAmount Presence: [0..1] Definition: The actual amount that has been paid to the ultimate beneficiary, after all charges etc. have been deducted. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 9.4.1.6.21 InterbankSettlementAmount Presence: [0..1] Definition: Amount of money moved between the instructing agent and the instructed agent. Impacted by: C2 "ActiveCurrency", C6 "CurrencyAmount" Datatype: "ActiveCurrencyAndAmount" Constraints • ActiveCurrency

09 February 2018 65

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 9.4.1.6.22 InterbankSettlementDate Presence: [0..1] Definition: Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due. Datatype: "ISODate" 9.4.1.6.23 ChargeBearer Presence: [0..1] Definition: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Datatype: "ChargeBearerType3Code"

Code Name Name Definition SHAR Shared In a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor. In a direct debit context, means that transaction charges on the sender side are to be borne by the creditor, transaction charges on the receiver side are to be borne by the debtor.

DEBT BorneByDebtor All transaction charges are to be borne by the debtor.

CRED BorneByCreditor All transaction charges are to be borne by the creditor. 9.4.1.6.24 ChargeAmount Presence: [0..*] Definition: Amount of money asked or paid for the charge. Impacted by: C3 "ActiveOrHistoricCurrency", C5 "CurrencyAmount" Datatype: "ActiveOrHistoricCurrencyAndAmount" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount

09 February 2018 66

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 9.4.1.6.25 ForeignExchangeDetails Presence: [0..1] Definition: Specifies the exchange rate details between two currencies. ForeignExchangeDetails contains the following ForeignExchangeTerms32 elements

Or Element Mult. Type Constr. No.

FromCurrency [1..1] CodeSet C3

ToCurrency [1..1] CodeSet C3

ExchangeRate [1..1] Rate 9.4.1.6.25.1 FromCurrency Presence: [1..1] Definition: Currency for which a foreign exchange is required. Impacted by: C3 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 9.4.1.6.25.2 ToCurrency Presence: [1..1] Definition: Currency resulting from a foreign exchange trade. Impacted by: C3 "ActiveOrHistoricCurrency" Datatype: "ActiveOrHistoricCurrencyCode" Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 9.4.1.6.25.3 ExchangeRate Presence: [1..1] Definition: The value of one currency expressed in relation to another currency. ExchangeRate expresses the ratio between FromCurrency and ToCurrency (ExchangeRate = FromCurrency/ ToCurrency). Datatype: "BaseOneRate"

09 February 2018 67

Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

9.4.1.6.26 UpdatePayment Presence: [0..1] Definition: Implements the correlation between a payment message and a status update on it. Contains the network reference of the payment for which the status confirmation was applicable. Datatype: "Max35Text" 9.4.1.6.27 DuplicateMessageReference Presence: [0..1] Definition: Network reference of the payment that is the original recorded payment. Datatype: "Max50Text" 9.4.1.6.28 CopiedBusinessService Presence: [0..1] Definition: Specifies the copied business service of the market infrastructure. Datatype: "Max35Text"

9.4.1.6.29 LastUpdateTime Presence: [1..1] Definition: Last date and time at which the status of this payment event was updated. Datatype: "ISODateTime" 9.4.2 More Presence: [0..1] Definition: Contains a token to obtain the next set of responses. It indicates whether there are more results to retrieve, what timestamp to start from and how many more result entries are to be retrieved. Datatype: "Max350Text"

09 February 2018 68

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsRequest

10 GetInvalidEventsRequest 10.1 API Functionality This API is a payment events query to get invalid events for payment transactions within a given time frame. An event is either a payment or a status confirmation. The API is typically used for support or audit purposes, where all invalid messages sent or received are retrievable by one API call. Outline The GetInvalidEventsRequest API is composed of 3 BuildingBlocks: A. MyInstitution Specifies the institution which payments are requested. B. FromDateTime Date and time at which the range starts. C. ToDateTime Date and time at which the range ends. 10.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetInvalidEventsRequest [1..1] MyInstitution [1..250] IdentifierSet C1

FromDateTime [1..1] DateTime

ToDateTime [1..1] DateTime 10.3 Constraints C1 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 10.4 Building Blocks This chapter describes the BuildingBlocks of this API. 10.4.1 MyInstitution Presence: [1..250] Definition: Specifies the institution which payments are requested. Impacted by: C1 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters.

09 February 2018 69

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsRequest

10.4.2 FromDateTime Presence: [1..1] Definition: Date and time at which the range starts. Datatype: "ISODateTime" 10.4.3 ToDateTime Presence: [1..1] Definition: Date and time at which the range ends. Datatype: "ISODateTime"

09 February 2018 70

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsResponse

11 GetInvalidEventsResponse 11.1 API Functionality This API is a payment events response to a query to get invalid events for payment transactions within a given time frame. An event is either a payment or a status confirmation. The API is typically used for support or audit purposes, where all invalid messages sent or received are retrievable by one API call. Outline The GetInvalidEventsResponse API is composed of 1 BuildingBlocks: A. Event Each instance contains one payment event that matches the search criteria. 11.2 Structure Or Element/BuildingBlock Mult. Type Constr. No.

GetInvalidEventsResponse [1..1] Event [1..*]

TransactionIdentification [1..1] Text

BusinessService [1..1] Text

Participant [1..1] Indicator

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

InstructionIdentification [1..1] Text

From [1..1] IdentifierSet C1

To [0..1] IdentifierSet C1

InvalidityReason [1..1] CodeSet 11.3 Constraints C1 AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 11.4 Building Blocks This chapter describes the BuildingBlocks of this API.

09 February 2018 71

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsResponse

11.4.1 Event Presence: [1..*] Definition: Each instance contains one payment event that matches the search criteria. Event contains the following PaymentEvent3 elements

Or Element Mult. Type Constr. No.

TransactionIdentification [1..1] Text

BusinessService [1..1] Text

Participant [1..1] Indicator

NetworkReference [1..1] Text

MessageNameIdentification [1..1] Text

InstructionIdentification [1..1] Text

From [1..1] IdentifierSet C1

To [0..1] IdentifierSet C1

InvalidityReason [1..1] CodeSet 11.4.1.1 TransactionIdentification Presence: [1..1] Definition: Contains the unique end to end transaction reference (UETR) of a payment. Datatype: "Max40Text" 11.4.1.2 BusinessService Presence: [1..1] Definition: Specifies the business service agreed between the two MessagingEndpoints under which rules this business message is exchanged. To be used when there is a choice of processing services or processing service levels. Example: 001 Datatype: "Max35Text" 11.4.1.3 Participant Presence: [1..1] Definition: Indicates whether the requestor institution participates in the payment transaction identified by the Transaction Identification (UETR). Datatype: One of the following values must be used (see "YesNoIndicator" 6): • Meaning When True: Yes • Meaning When False: No 11.4.1.4 NetworkReference Presence: [1..1] Definition: Reference assigned by the network when sending the payment.

09 February 2018 72

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsResponse

Datatype: "Max350Text" 11.4.1.5 MessageNameIdentification Presence: [1..1] Definition: Specifies the original message name identifier to which the message refers. Datatype: "Max35Text" 11.4.1.6 InstructionIdentification Presence: [1..1] Definition: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. Usage: The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. Datatype: "Max35Text" 11.4.1.7 From Presence: [1..1] Definition: The sending MessagingEndpoint that has created this business message for the receiving MessagingEndpoint that will process this business message. Note The sending MessagingEndpoint might be different from the sending address potentially contained in the transport header (as defined in the transport layer). Impacted by: C1 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 11.4.1.8 To Presence: [0..1] Definition: The MessagingEndpoint designated by the sending MessagingEndpoint to be the recipient who will ultimately process this business message. Note The receiving MessagingEndpoint might be different from the receiving address potentially contained in the transport header (as defined in the transport layer). Impacted by: C1 "AnyBIC" Datatype: "AnyBICIdentifier" Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 11.4.1.9 InvalidityReason

09 February 2018 73

Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsResponse

Presence: [1..1] Definition: Specifies the reason why the event is invalid. Datatype: "InvalidEventReason1Code"

09 February 2018 74

Connector for SWIFT gpi Tracker API Detailed Specification Types

12 Types 12.1 Date Time 12.1.1 DateTimePeriodDetails Definition: Time span defined by a start date and time, and an end date and time.

Or Element Mult. Type Constr. No.

FromDateTime [1..1] DateTime

ToDateTime [1..1] DateTime 12.1.1.1 FromDateTime Presence: [1..1] Definition: Date and time at which the range starts. Datatype: "ISODateTime" 12.1.1.2 ToDateTime Presence: [1..1] Definition: Date and time at which the range ends. Datatype: "ISODateTime" 12.2 Datatypes 12.2.1 Amount 12.2.1.1 ActiveCurrencyAndAmount Definition: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. Type: Amount This data type contains the following attribute:

Name Datatype

Currency "ActiveCurrencyCode" on page 82

Format minInclusive 0 totalDigits 18 fractionDigits 5

Constraints • ActiveCurrency The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged.

09 February 2018 75

Connector for SWIFT gpi Tracker API Detailed Specification Types

• CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 12.2.1.2 ActiveOrHistoricCurrencyAndAmount Definition: A number of monetary units specified in an active or a historic currency where the unit of currency is explicit and compliant with ISO 4217. Type: Amount This data type contains the following attribute:

Name Datatype

Currency "ActiveOrHistoricCurrencyCode" on page 82

Format minInclusive 0 totalDigits 18 fractionDigits 5

Constraints

• ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. • CurrencyAmount The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note The decimal separator is a dot. 12.2.1.3 ImpliedCurrencyAndAmount Definition: Number of monetary units specified in a currency where the unit of currency is implied by the context and compliant with ISO 4217. The decimal separator is a dot. Note A zero amount is considered a positive amount. Type: Amount

Format minInclusive 0 totalDigits 18 fractionDigits 5

12.2.2 CodeSet 12.2.2.1 ActiveCurrencyCode Definition: A code allocated to a currency by a Maintenance Agency under an international identification scheme as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Type: CodeSet Format pattern [A-Z]{3,3}

09 February 2018 76

Connector for SWIFT gpi Tracker API Detailed Specification Types

Constraints • ActiveCurrency The currency code must be a valid active currency code, not yet withdrawn on the day the message containing the currency is exchanged. Valid active currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and are not yet withdrawn on the day the message containing the currency is exchanged. 12.2.2.2 ActiveOrHistoricCurrencyCode Definition: A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Type: CodeSet Format pattern [A-Z]{3,3} Constraints • ActiveOrHistoricCurrency The currency code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the currency is exchanged. 12.2.2.3 ChargeBearerType3Code Definition: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Type: CodeSet

Code Name Name Definition

SHAR Shared In a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor. In a direct debit context, means that transaction charges on the sender side are to be borne by the creditor, transaction charges on the receiver side are to be borne by the debtor.

DEBT BorneByDebtor All transaction charges are to be borne by the debtor.

CRED BorneByCreditor All transaction charges are to be borne by the creditor.

12.2.2.4 CurrencyCode Definition: Code allocated to a currency, by a maintenance agency, under an international identification scheme as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Valid currency codes are registered with the ISO 4217 Maintenance Agency, and consist of three contiguous letters. Type: CodeSet Format pattern [A-Z]{3,3}

09 February 2018 77

Connector for SWIFT gpi Tracker API Detailed Specification Types

Constraints • ValidationByTable 12.2.2.5 InvalidEventReason1Code Definition: Codeset containing the reasons why an event (a message) was invalid in the context of the transaction. Type: CodeSet 12.2.2.6 InvalidPaymentsEvent1Code Definition: Specifies the reason why a payments event is an invalid component of a payments transaction. Type: CodeSet 12.2.2.7 Location1Code Definition: Specifies the location of the search Type: CodeSet

Code Name Name Definition

OTHR AtAnotherInstitution At another institution

MYIN AtMyInstitution At my institution.

12.2.2.8 PaymentReason1Code Definition: Provides the reason for a specific Payment Status. Type: CodeSet

Code Name Name Definition G002 CreditNotConfirmed Credit to creditor's account cannot be confirmed same day.

Update will follow. G004 CreditPendingFunds Credit to creditor's account is pending, status originator waiting for funds provided by or on behalf of the Instructing or Intermediary gpi Agent. Update will follow.

G000 GpiAgent Payment is pushed to next gpi Agent or gpi-compatible market infrastructure. G001 NonGpiAgent Payment is pushed to a non-gpi Agent or un-supported market infrastructure. No further updates from the status originator. G003 CreditPendingDocuments Credit to creditor's account is pending receipt of required documents. Instructed gpi Agent has requested the creditor to provide additional documentation.

Update will follow. 12.2.2.9 PaymentsPartyType1Code Definition: CodeSet identifying parties involved in a payments transaction. Type: CodeSet 12.2.2.10PaymentTransactionState1Code Definition: Contains the different states which a payment transaction can be in.

09 February 2018 78

Connector for SWIFT gpi Tracker API Detailed Specification Types

Type: CodeSet

Code Name Name Definition CRED Credited The transaction is credited.

RCCA ReceivedAtCreditorAgent The transaction is received at the creditor's agent. RCMY ReceivedByMyInstitution The transaction is received by my institution. STMY SentByMyInstitution The transaction is sent by my institution.

STDA SentByDebtorAgent The transaction is sent by the debtor's agent.

12.2.2.11TransactionIndividualStatus4Code Definition: Specifies the status of a single payment transaction. Type: CodeSet

Code Name Name Definition RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected. ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

ACSC AcceptedSettlementCompleted Settlement on the debtor's account has been completed.

Usage: this can be used by the first agent to report to the debtor that the transaction has been completed. Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement

12.2.2.12 TypeOfAmount8Code

Definition: Specifies the type of amount. Type: CodeSet

Code Name Name Definition CONF ConfirmedAmount The actual amount that has been paid to the ultimate beneficiary, after all charges etc. have been deducted. INST InstructedAmount Amount of money to be moved between the debtor (ordering customer) and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.

09 February 2018 79

Connector for SWIFT gpi Tracker API Detailed Specification Types

12.2.3 Date 12.2.3.1 ISODate Definition: A particular point in the progression of time in a calendar year expressed in the YYYY-MM- DD format. This representation is defined in "XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October 2004" which is aligned with ISO 8601. Type: Date 12.2.4 DateTime 12.2.4.1 ISODateTime Definition: A particular point in the progression of time defined by a mandatory date and a mandatory time component, expressed in either UTC time format (YYYY-MM- DDThh:mm:ss.sssZ), local time with UTC offset format (YYYY-MM-DDThh:mm:ss.sss+/- hh:mm), or local time format (YYYY-MM- DDThh:mm:ss.sss). These representations are defined in "XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October 2004" which is aligned with ISO 8601. Note on the time format: 1) beginning / end of calendar day 00:00:00 = the beginning of a calendar day 24:00:00 = the end of a calendar day 2) fractions of second in time format Decimal fractions of seconds may be included. In this case, the involved parties shall agree on the maximum number of digits that are allowed. Type: DateTime 12.2.5 IdentifierSet 12.2.5.1 AnyBICIdentifier Definition: Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362 "Banking - Banking telecommunication messages - Business identifier code (BIC)". Type: IdentifierSet Identification scheme: SWIFT; AnyBICIdentifier Format pattern [A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1} Constraints • AnyBIC Only a valid business identifier code is allowed. Business identifier codes for financial or non- financial institutions are registered by the ISO 9362 Registration Authority in the BIC Directory, and consists of eight (8) or eleven (11) contiguous characters. 12.2.6 Indicator 12.2.6.1 YesNoIndicator Definition: Indicates a "Yes" or "No" type of answer for an element. Type: Indicator Meaning When True: Yes Meaning When False: No

09 February 2018 80

Connector for SWIFT gpi Tracker API Detailed Specification Types

12.2.7 Quantity 12.2.7.1 Number Definition: Number of objects represented as an integer. Type: Quantity

Format totalDigits 18 fractionDigits 0

12.2.8 Rate 12.2.8.1 BaseOneRate Definition: Rate expressed as a decimal, for example, 0.7 is 7/10 and 70%. Type: Rate

Format totalDigits 11

fractionDigits 10 baseValue 1.0

12.2.9 Text 12.2.9.1 Max1850Text Definition: Specifies a character string with a maximum length of 1850 characters. Type: Text

Format minLength 1 maxLength 1850

12.2.9.2 Max30Text Definition: Specifies a character string with a maximum length of 30 characters. Type: Text Format

maxLength 30 12.2.9.3 Max350Text Definition: Specifies a character string with a maximum length of 350 characters.

Type: Text

Format

minLength 1 maxLength 350

12.2.9.4 Max35Text Definition: Specifies a character string with a maximum length of 35 characters.

09 February 2018 81

Connector for SWIFT gpi Tracker API Detailed Specification Types

Type: Text

Format minLength 1 maxLength 35

12.2.9.5 Max40Text Definition: Specifies a character string with a maximum length of 40 characters. Type: Text

Format minLength 1 maxLength 40

12.2.9.6 Max50Text Definition: Specifies a character string with a maximum length of 50 characters. Type: Text

Format minLength 1 maxLength 50

09 February 2018 82

Connector for SWIFT gpi Tracker API Detailed Specification JSON Representation

Appendix A JSON Representation A.1 JSON – Snake Case This appendix depicts how the JSON structures of an API request and an API response shall be constructed in accordance with the detailed API specifications defined in this document. The "GetPaymentTransactions" API is used as an example to indicate so. For all APIs, the "Request" building block of the API specification corresponds to the JSON structure of the API request. For "GetPaymentTransactions" API, the JSON structure of the API request will look as follows (newline-delimited JSON is foreseen):

{ “my_institution”: “my_institution_value”, “time_window”: { “from_date_time”: “from_date_time_value”, “to_date_time”: “to_date_time_value” }, “agent”: [ { “any_bic”: “any_bic_value”, “role”: “role_value” }, … ], “location”: “location_value”, “instruction_identification”: “instruction_identification_value”, “transaction_status”: [ { “status”: “status_value”, “reason”: “reason_value” }, … ], “amount”: { “type”: “type_value”, “currency”: “currency_value”, “from_amount”: “from_amount_value”, “to_amount”: “to_amount_value” }, “event”: “event_value”, “maximum_number”: “maximum_number_value”,

09 February 2018 83

Connector for SWIFT gpi Tracker API Detailed Specification JSON Representation

“more”: “more_value” } Similarly, for all APIs, the "Response" building block of the API specification corresponds to the JSON structure of the API response. For "GetPaymentTransactions" API, the JSON structure of the API response will look as follows:

HTTP/1.1 200 OK { “payment_transaction”: [ { “transaction_identification”: “transaction_identification_value”, “my_institution”: “my_institution_value”, “role”: “role_value”, “event_time”: “event_time_value”, “transaction_status”: { “status”: “status_value”, “reason”: “reason_value” }, “previous_instructing_agent”: “previous_instructing_agent_value”, “agents”: [ { “from”: “from_value”, “to”: “to_value”, “transaction_status”: { “status”: “status_value”, “reason”: “reason_value” }, “forwarded_agent”: “forwarded_agent_value”, “received”: “received_value” }, … ], “creditor_agent”: “creditor_agent_value”, “initiation_time”: “initiation_time_value”, “completion_time”: “completion_time_value”, “instructed_amount”: { “$”:“instructed_amount_value”, “@currency”: “currency_value” },

09 February 2018 84

Connector for SWIFT gpi Tracker API Detailed Specification JSON Representation

“last_update_time”: “last_update_time_value” }, … ], “total_number”: “total_number_value”, “more”: “more_value” } A.2 JSON – Amount Representation: "instructed_amount": : { "$": 1.10, "@currency": "EUR" },

The "$" is used for the value of the amount, and the "@currency" is the currency code. The example shows an amount of 1.10 EUR.

09 February 2018 85

Connector for SWIFT gpi Tracker API Detailed Specification Legal Notices

Legal Notices Copyright SWIFT © 2018. All rights reserved.

Disclaimer SWIFT supplies this publication for information purposes only. The information in this publication may change from time to time. You must always refer to the latest available version.

Translations The English version of SWIFT documentation is the only official and binding version.

Trademarks SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: the SWIFT logo, SWIFT, SWIFTNet, Sibos, 3SKey, Innotribe, the Standards Forum logo, MyStandards, and SWIFT Institute. Other product, service, or company names in this publication are trade names, trademarks, or registered trademarks of their respective owners.

09 February 2018 86