connector for swift gpi - tracker api detailed specificationconnector for swift gpi tracker api...

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

09 February 2018 4

Table of Contents Table of Contents ............................................................................................................................... 4

Preface ................................................................................................................................................. 6

1 API Set Overview ...................................................................................................................... 7 List of APIs .............................................................................................................................. 7 1.1

2 UpdatePaymentStatusRequest ............................................................................................. 10 API Functionality ...................................................................................................................10 2.1 Structure ................................................................................................................................10 2.2 Constraints ............................................................................................................................11 2.3 Building Blocks ......................................................................................................................11 2.4

3 UpdatePaymentStatusResponse .......................................................................................... 18 API Functionality ...................................................................................................................18 3.1 Structure ................................................................................................................................18 3.2 Building Blocks ......................................................................................................................18 3.3

4 GetPaymentTransactionDetailsRequest .............................................................................. 19 API Functionality ...................................................................................................................19 4.1 Structure ................................................................................................................................19 4.2 Constraints ............................................................................................................................19 4.3 Building Blocks ......................................................................................................................19 4.4

5 GetPaymentTransactionDetailsResponse ........................................................................... 21 API Functionality ...................................................................................................................21 5.1 Structure ................................................................................................................................21 5.2 Constraints ............................................................................................................................23 5.3 Building Blocks ......................................................................................................................23 5.4

6 GetPaymentTransactionsRequest ........................................................................................ 35 API Functionality ...................................................................................................................35 6.1 Structure ................................................................................................................................36 6.2 Constraints ............................................................................................................................36 6.3 Building Blocks ......................................................................................................................36 6.4

7 GetPaymentTransactionsResponse ..................................................................................... 42 API Functionality ...................................................................................................................42 7.1 Structure ................................................................................................................................42 7.2 Constraints ............................................................................................................................43 7.3 Building Blocks ......................................................................................................................43 7.4

8 GetChangedPaymentTransactionsRequest ........................................................................ 51 API Functionality ...................................................................................................................51 8.1 Structure ................................................................................................................................51 8.2 Constraints ............................................................................................................................51 8.3 Building Blocks ......................................................................................................................51 8.4

9 GetChangedPaymentTransactionsResponse ..................................................................... 53 API Functionality ...................................................................................................................53 9.1 Structure ................................................................................................................................53 9.2 Constraints ............................................................................................................................55 9.3 Building Blocks ......................................................................................................................55 9.4

Connector for SWIFT gpi Tracker API Detailed Specification

09 February 2018 5

10 GetInvalidEventsRequest ...................................................................................................... 69 API Functionality ...................................................................................................................69 10.1 Structure ................................................................................................................................69 10.2 Constraints ............................................................................................................................69 10.3 Building Blocks ......................................................................................................................69 10.4

11 GetInvalidEventsResponse ................................................................................................... 71 API Functionality ...................................................................................................................71 11.1 Structure ................................................................................................................................71 11.2 Constraints ............................................................................................................................71 11.3 Building Blocks ......................................................................................................................71 11.4

12 Types........................................................................................................................................ 75 Date Time ..............................................................................................................................75 12.1 Datatypes ..............................................................................................................................75 12.2

A.1 JSON – Snake Case ................................................................................................................ 83

A.2 JSON – Amount Representation: .......................................................................................... 85

Connector for SWIFT gpi Tracker API Detailed Specification Preface

09 February 2018 6

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

https://www2.swift.com/go/book/bookext051649/pdf

https://www2.swift.com/go/book/bookext051650/html

https://www2.swift.com/go/book/bookext050515/pdf

https://www2.swift.com/go/book/bookext050647/bookext050647/html

Connector for SWIFT gpi Tracker API Detailed Specification API Set Overview

09 February 2018 7

1 API Set Overview List of APIs 1.1

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 UpdatePaymentStatusResponse

This API is the response to a status confirmation update to inform the Tracker about the updated status of a given payment.

camt.a02.001.02 GetPaymentTransactionDetailsRequest

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

camt.a02.002.02 GetPaymentTransactionDetailsResponse

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

camt.a03.001.02 GetPaymentTransactionsRequest

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


09 February 2018 8

camt.a03.002.02 GetPaymentTransactionsResponse

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:



• Feed a dashboard - give all payment transactions with their last status

camt.a04.001.02 GetChangedPaymentTransactionsRequest

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.

camt.a04.002.02 GetChangedPaymentTransactionsResponse

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.

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 9

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.

Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusRequest

09 February 2018 10

2 UpdatePaymentStatusRequest API Functionality 2.1

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.

Structure 2.2Or 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 11

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

Constraints 2.3C1 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.

Building Blocks 2.4This 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 12

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.


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.


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.


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]









09 February 2018 13






2.4.5.1 RawStatus Presence: [1..1]

Definition: Contains the status of the payment taken from field 79 of the MT 199.


2.4.5.2 DetailedStatus Presence: [1..1]

Definition: Contains the detailed status of a Payment.

DetailedStatus contains the following StatusDetails1 elements














2.4.5.2.1 Originator

Presence: [1..1]

Definition: Party that issues the status.


Datatype: "AnyBICIdentifier" Constraints



09 February 2018 14

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




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”.

https://www2.swift.com/uhbonline/books/protected/en_uk/gpi_cst_cdt_transf_r/index.htm


09 February 2018 15

2.4.5.2.3.2 Reason

Presence: [0..1]

Definition: Provides more details on the status in process.

Datatype: "PaymentReason1Code"


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.




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 16

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.


2.4.5.2.6 ForeignExchangeDetails

Presence: [0..1]

Definition: Specifies the exchange rate details between two currencies.

ForeignExchangeDetails contains the following ForeignExchangeTerms32 elements





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


2.4.5.2.6.2 ToCurrency

Presence: [1..1]

Definition: Currency resulting from a foreign exchange trade.





09 February 2018 17

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.




• CurrencyAmount

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


Connector for SWIFT gpi Tracker API Detailed Specification UpdatePaymentStatusResponse

09 February 2018 18

3 UpdatePaymentStatusResponse API Functionality 3.1

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.

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

UpdatePaymentStatusResponse [1..1]

NetworkReference [1..1] Text


3.3.1 NetworkReference Presence: [1..1]

Definition: Reference assigned by the network.


Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsRequest

09 February 2018 19

4 GetPaymentTransactionDetailsRequest API Functionality 4.1

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.


No.

GetPaymentTransactionDetailsRequest [1..1]

MyInstitution [1..250] IdentifierSet C1


Constraints 4.3C1 AnyBIC



4.4.1 MyInstitution Presence: [1..250]

Definition: Specifies the institution which payments are requested.




Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsRequest

09 February 2018 20


Definition: Contains the unique end to end transaction reference (UETR) of a payment.


Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionDetailsResponse

09 February 2018 21

5 GetPaymentTransactionDetailsResponse API Functionality 5.1

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


• 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.


No.

GetPaymentTransactionDetailsResponse [1..1]





InitiationTime [1..1] DateTime

CompletionTime [0..1] DateTime

LastUpdateTime [0..1] DateTime

PaymentEvent [0..*]


MessageNameIdentification [1..1] Text


09 February 2018 22


Valid [1..1] Indicator

InvalidityReason [0..1] CodeSet

InvalidityDescription [0..1] Text

SenderReference [0..1] Text








To [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


InterbankSettlementAmount [0..1] Amount C2, C6

InterbankSettlementDate [0..1] Date

ChargeBearer [0..1] CodeSet






UpdatePayment [0..1] Text

DuplicateMessageReference [0..1] Text

CopiedBusinessService [0..1] Text



09 February 2018 23



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.



C4 AnyBIC


C5 CurrencyAmount



C6 CurrencyAmount


Note Note: The decimal separator is a dot.





5.4.2 TransactionStatus Presence: [1..1]

Definition: Specifies the status of a transaction, in a coded form.







09 February 2018 24

Constraints

• ACSPReasonCode Reason must only be present if Status contains ACSP.

5.4.2.1 Status Presence: [1..1]






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]









09 February 2018 25


5.4.3 InitiationTime Presence: [1..1]

Definition: Date and time at which the message enters the SWIFT gpi system.


5.4.4 CompletionTime Presence: [0..1]

Definition: Time at which the instructed bank reports that the transaction has been completed.



5.4.5 LastUpdateTime Presence: [0..1]

Definition: Last date and time at which the status of this transaction was updated.


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













09 February 2018 26

























5.4.6.1 NetworkReference Presence: [1..1]

Definition: Reference assigned by the network when sending the payment.


5.4.6.2 MessageNameIdentification Presence: [1..1]

Definition: Specifies the original message name identifier to which the message refers.


5.4.6.3 BusinessService Presence: [1..1]


09 February 2018 27




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.


5.4.6.7 SenderReference Presence: [0..1]

Definition: Identification assigned by the sender of the message.

For MT format this is the MUR.


5.4.6.8 InstructionIdentification Presence: [1..1]




5.4.6.9 TransactionStatus Presence: [0..1]





09 February 2018 28




Constraints


5.4.6.9.1 Status

Presence: [1..1]






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]









09 February 2018 29


5.4.6.10ForwardedAgent Presence: [0..1]





5.4.6.11FundsAvailable Presence: [0..1]


Must only be used when TransactionStatus is "ACSC".


5.4.6.12From Presence: [0..1]






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).



09 February 2018 30


Constraints


5.4.6.14Originator Presence: [0..1]





5.4.6.15CreditorAgent Presence: [0..1]

Definition: Financial institution servicing an account for the creditor.



Constraints


5.4.6.16PreviousInstructingAgent Presence: [0..1]

Definition: Agent immediately prior to the instructing agent.




5.4.6.17SenderAcknowledgementReceipt Presence: [1..1]

Definition: Date and time at which the sender acknowledged receipt of the message.



09 February 2018 31

5.4.6.18ReceivedDate Presence: [0..1]

Definition: Date and time at which the message was acknowledged by the receiver.


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.



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.


5.4.6.20ConfirmedAmount Presence: [0..1]



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.


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 32




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"


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..*]



Datatype: "ActiveOrHistoricCurrencyAndAmount"

Constraints





09 February 2018 33

5.4.6.25ForeignExchangeDetails Presence: [0..1]







5.4.6.25.1 From Currency Presence: [1..1]





5.4.6.25.2 ToCurrency Presence: [1..1]





5.4.6.25.3 ExchangeRate Presence: [1..1]



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 34


5.4.6.27 DuplicateMessageReference Presence: [0..1]

Definition: Network reference of the payment that is the original recorded payment.


5.4.6.28 CopiedBusinessService Presence: [0..1]

Definition: Specifies the copied business service of the market infrastructure.


5.4.6.29 LastUpdateTime Presence: [1..1]

Definition: Last date and time at which the status of this payment event was updated.


Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsRequest

09 February 2018 35

6 GetPaymentTransactionsRequest API Functionality 6.1

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.




• 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.


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 36


No.

GetPaymentTransactionsRequest [1..1]


TimeWindow [1..1] ±

Agent [0..*]

AnyBIC [1..*] IdentifierSet C2

Role [1..1] CodeSet

Location [0..1] CodeSet


TransactionStatus [0..*] C1



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



C2 AnyBIC


C3 ValidationByTable

Must be a valid currency code which is registered with the ISO 4217 Maintenance Agency, and consist of three contiguous letters.



09 February 2018 37


Definition: Specifies an institution that is owned by the sender, for which the sender can ask payment transaction details.




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)


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


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)".





09 February 2018 38

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"


OTHR AtAnotherInstitution At another institution

MYIN AtMyInstitution At my institution.

6.4.5 InstructionIdentification Presence: [0..1]




6.4.6 TransactionStatus Presence: [0..*]







Constraints


6.4.6.1 Status Presence: [1..1]






09 February 2018 39


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]




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

Update will follow.




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


Type [1..1] CodeSet


09 February 2018 40

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"


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"


CRED Credited The transaction is credited.


09 February 2018 41

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.


Connector for SWIFT gpi Tracker API Detailed Specification GetPaymentTransactionsResponse

09 February 2018 42

7 GetPaymentTransactionsResponse API Functionality 7.1

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




• 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.

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

GetPaymentTransactionsResponse [1..1]

PaymentTransaction [1..*]



Role [1..1] CodeSet

EventTime [1..1] DateTime





Agents [1..*]






09 February 2018 43



Received [1..1] Indicator






TotalNumber [1..1] Quantity

More [0..1] Text





C3 AnyBIC


C4 CurrencyAmount




7.4.1 PaymentTransaction Presence: [1..*]

Definition: Contains the payment transactions that meet the search criteria.

PaymentTransaction contains the following PaymentTransaction72 elements




Role [1..1] CodeSet


09 February 2018 44

EventTime [1..1] DateTime





Agents [1..*]













7.4.1.1 TransactionIdentification Presence: [1..1]



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.




7.4.1.3 Role Presence: [1..1]

Definition: Specifies the role of the party in the payment chain.

Datatype: "PaymentsPartyType1Code"


09 February 2018 45

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.









Constraints


7.4.1.5.1 Status

Presence: [1..1]






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





09 February 2018 46







7.4.1.6 PreviousInstructingAgent Presence: [0..1]





7.4.1.7 Agents Presence: [1..*]

Definition: Identifies the agents currently participating in a transaction.

Agents contains the following PaymentEvent2 elements










09 February 2018 47

7.4.1.7.1 From Presence: [0..1]






7.4.1.7.2 To Presence: [0..1]





Constraints


7.4.1.7.3 TransactionStatus Presence: [1..1]







Constraints


7.4.1.7.3.1 Status Presence: [1..1]



09 February 2018 48






7.4.1.7.3.2 Reason Presence: [0..1]









7.4.1.7.4 ForwardedAgent Presence: [0..1]




09 February 2018 49



7.4.1.7.5 Received Presence: [1..1]

Definition: Indicates whether a payment has been received or not.



7.4.1.8 CreditorAgent Presence: [0..1]




Constraints


7.4.1.9 InitiationTime Presence: [1..1]



7.4.1.10CompletionTime Presence: [0..1]




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.



• ActiveOrHistoricCurrency


09 February 2018 50




7.4.1.12LastUpdateTime Presence: [1..1]



7.4.2 TotalNumber Presence: [1..1]

Definition: Contains the total number of returned result entries.

Datatype: "Number"


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.


Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsRequest

09 February 2018 51

8 GetChangedPaymentTransactionsRequest API Functionality 8.1

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


B. StartTime

Contains the start date and time as from which the last changed payment transactions must be provided.

C. More



No.

GetChangedPaymentTransactionsRequest [1..1] C2


StartTime [0..1] DateTime

More [0..1] Text



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.


Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsRequest

09 February 2018 52






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.





Connector for SWIFT gpi Tracker API Detailed Specification GetChangedPaymentTransactionsResponse

09 February 2018 53

9 GetChangedPaymentTransactionsResponse API Functionality 9.1

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



No.

GetChangedPaymentTransactionsResponse [1..1]

PaymentTransaction [0..*]








PaymentEvent [1..*]







09 February 2018 54






























More [0..1] Text


09 February 2018 55



C2 ActiveCurrency




C4 AnyBIC


C5 CurrencyAmount


Note Note: The decimal separator is a dot.

C6 CurrencyAmount




9.4.1 PaymentTransaction Presence: [0..*]

Definition: Contains the payment transactions that meet the search criteria.

PaymentTransaction contains the following PaymentTransaction73 elements








09 February 2018 56



PaymentEvent [1..*]






























09 February 2018 57

















Constraints


9.4.1.2.1 Status Presence: [1..1]







09 February 2018 58











9.4.1.3 InitiationTime Presence: [1..1]



9.4.1.4 CompletionTime Presence: [0..1]



09 February 2018 59



9.4.1.5 LastUpdateTime Presence: [1..1]



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























09 February 2018 60















9.4.1.6.1 NetworkReference Presence: [1..1]



9.4.1.6.2 MessageNameIdentification Presence: [1..1]



9.4.1.6.3 BusinessService Presence: [1..1]




9.4.1.6.4 Valid Presence: [1..1]

Definition: Indicates if a payment is consistent (YES) or not (NO).




09 February 2018 61

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.


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.


9.4.1.6.8 InstructionIdentification Presence: [1..1]




9.4.1.6.9 TransactionStatus Presence: [0..1]







Constraints

• ACSPReasonCode Reason must only be present if Status contains ACSP.

9.4.1.6.9.1 Status Presence: [1..1]



09 February 2018 62






9.4.1.6.9.2 Reason

Presence: [0..1]










09 February 2018 63

9.4.1.6.10 ForwardedAgent Presence: [0..1]





9.4.1.6.11 FundsAvailable Presence: [0..1]


Must only be used when TransactionStatus is "ACSC".


9.4.1.6.12 From Presence: [0..1]






9.4.1.6.13 To Presence: [0..1]





• AnyBIC


09 February 2018 64


9.4.1.6.14 Originator Presence: [0..1]





9.4.1.6.15 CreditorAgent Presence: [0..1]





9.4.1.6.16 PreviousInstructingAgent Presence: [0..1]





9.4.1.6.17 SenderAcknowledgementReceipt Presence: [1..1]

Definition: Date and time at which the sender acknowledged receipt of the message.


9.4.1.6.18 ReceivedDate Presence: [0..1]


09 February 2018 65

Definition: Date and time at which the message was acknowledged by the receiver.


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.






9.4.1.6.20 ConfirmedAmount Presence: [0..1]







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 66




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"





9.4.1.6.24 ChargeAmount Presence: [0..*]





• CurrencyAmount


09 February 2018 67



9.4.1.6.25 ForeignExchangeDetails Presence: [0..1]







9.4.1.6.25.1 FromCurrency Presence: [1..1]



Datatype: "ActiveOrHistoricCurrencyCode"

Constraints


9.4.1.6.25.2 ToCurrency Presence: [1..1]





9.4.1.6.25.3 ExchangeRate Presence: [1..1]




09 February 2018 68

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.


9.4.1.6.27 DuplicateMessageReference Presence: [0..1]

Definition: Network reference of the payment that is the original recorded payment.


9.4.1.6.28 CopiedBusinessService Presence: [0..1]

Definition: Specifies the copied business service of the market infrastructure.


9.4.1.6.29 LastUpdateTime Presence: [1..1]

Definition: Last date and time at which the status of this payment event was updated.





Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsRequest

09 February 2018 69

10 GetInvalidEventsRequest API Functionality 10.1

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


B. FromDateTime

Date and time at which the range starts.

C. ToDateTime

Date and time at which the range ends.


No.

GetInvalidEventsRequest [1..1]












Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsRequest

09 February 2018 70

10.4.2 FromDateTime Presence: [1..1]

Definition: Date and time at which the range starts.


10.4.3 ToDateTime Presence: [1..1]

Definition: Date and time at which the range ends.


Connector for SWIFT gpi Tracker API Detailed Specification GetInvalidEventsResponse

09 February 2018 71

11 GetInvalidEventsResponse API Functionality 11.1

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.


No.

GetInvalidEventsResponse [1..1]

Event [1..*]



Participant [1..1] Indicator











09 February 2018 72

11.4.1 Event Presence: [1..*]

Definition: Each instance contains one payment event that matches the search criteria.

Event contains the following PaymentEvent3 elements




Participant [1..1] Indicator










11.4.1.2 BusinessService Presence: [1..1]




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):


11.4.1.4 NetworkReference Presence: [1..1]



09 February 2018 73


11.4.1.5 MessageNameIdentification Presence: [1..1]



11.4.1.6 InstructionIdentification Presence: [1..1]




11.4.1.7 From Presence: [1..1]






11.4.1.8 To Presence: [0..1]





Constraints


11.4.1.9 InvalidityReason


09 February 2018 74

Presence: [1..1]

Definition: Specifies the reason why the event is invalid.

Datatype: "InvalidEventReason1Code"

Connector for SWIFT gpi Tracker API Detailed Specification Types

09 February 2018 75

12 Types Date Time 12.1

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




12.1.1.1 FromDateTime Presence: [1..1]

Definition: Date and time at which the range starts.


12.1.1.2 ToDateTime Presence: [1..1]

Definition: Date and time at which the range ends.


Datatypes 12.212.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 76



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




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 77

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".


pattern [A-Z]{3,3}

Constraints


12.2.2.3 ChargeBearerType3Code Definition: Specifies which party/parties will bear the charges associated with the processing of the payment transaction.

Type: CodeSet





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.


pattern [A-Z]{3,3}


09 February 2018 78

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


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







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 79

Type: CodeSet


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





12.2.2.12 TypeOfAmount8Code

Definition: Specifies the type of amount.

Type: CodeSet


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 80

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


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 81

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


Type: Text

Format

minLength 1

maxLength 350



09 February 2018 82

Type: Text

Format

minLength 1

maxLength 35


Type: Text

Format

minLength 1

maxLength 40


Type: Text

Format

minLength 1

maxLength 50

Connector for SWIFT gpi Tracker API Detailed Specification JSON Representation

09 February 2018 83

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 84

“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”,


{



},

“previous_instructing_agent”: “previous_instructing_agent_value”,

“agents”:

[

{

“from”: “from_value”,

“to”: “to_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 85

“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.

Connector for SWIFT gpi Tracker API Detailed Specification Legal Notices

09 February 2018 86

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.