SWIFT Developer Portal | Homepage - Tracker API …...2.4.5 MaximumNumber Presence: [0..1] Definition: Indicates the maximum number of entries returned. Datatype: "Number" on page

Tracker API 2.0

For SWIFT gpi

Detailed Specification

GetCorporatePaymentTransactions This document provides details of the APIs for GetCorporatePaymentTransactions. 27 July 2018

Tracker API 2.0 For SWIFT gpi Detailed Specification

Table of Contents

27 July 2018 2

Table of Contents

1 API Set Overview ................................................................................................................................................. 3

1.1 List of APIs ...................................................................................................................................................... 3

2 GetCorporatePaymentTransactionsRequest .......................................................................................... 4

2.1 API Functionality ............................................................................................................................................ 4

2.2 Structure .......................................................................................................................................................... 4 2.3 Constraints ...................................................................................................................................................... 5

2.4 Building Blocks ............................................................................................................................................... 5

3 GetCorporatePaymentTransactionsResponse ....................................................................................... 8

3.1 API Functionality ............................................................................................................................................ 8

3.2 Structure .......................................................................................................................................................... 9

3.3 Constraints ...................................................................................................................................................... 9 3.4 Building Blocks ..............................................................................................................................................10

4 Types .......................................................................................................................................................................18

4.1 Date Time.......................................................................................................................................................18

4.2 Datatypes .......................................................................................................................................................18


API Set Overview

27 July 2018 3

1 API Set Overview

1.1 List of APIs The following table lists all APIs described in this book.

API Definition

camt.a08.001.01 GetCorporatePaymentTransactionsRequest

Contains the request to obtain information on the corporate status of one or more payment transactions.

camt.a08.002.01 GetCorporatePaymentTransactionsResponse

Contains the response to the request to obtain information on the corporate status of one or more payment transactions.


GetCorporatePaymentTransactionsRequest

27 July 2018 4

2 GetCorporatePaymentTransactionsRequest

2.1 API Functionality Contains the request to obtain information on the corporate status of one or more payment transactions.

Outline

The GetCorporatePaymentTransactionsRequest API is composed of 6 BuildingBlocks:

A. MyInstitution

Specifies the institution which payments are requested.

B. UETR

Contains the unique end to end transaction reference.

Format is lowercase separated by hyphens.

C. TimeWindow

Time window for this institution to which the search applies.

D. TransactionStatus

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

E. MaximumNumber

Indicates the maximum number of entries returned.

F. More

Contains the token to get the next set of responses.

2.2 Structure

Or Element/BuildingBlock Mult. Type Constr. No.

Page

Root [1..1]

C2 MyInstitution [1..250] IdentifierSet C1 5

UETR [0..1] IdentifierSet 5

TimeWindow [0..1] ± 5

TransactionStatus [0..*]

6

Status [1..1] CodeSet 6

Reason [0..1] CodeSet 6

MaximumNumber [0..1] Quantity 7

More [0..1] Text 7



27 July 2018 5

2.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 MaximumNumberPresenceRule

MaximumNumber must be present if TimeWindow is present.

This constraint is defined at the API level.

2.4 Building Blocks

This chapter describes the BuildingBlocks of this API. 2.4.1 MyInstitution

Presence: [1..250]

Definition: Specifies the institution which payments are requested.

Impacted by: C1 "AnyBIC"

Datatype: "AnyBICIdentifier" on page 21

Constraints

• AnyBIC


2.4.2 UETR

Presence: [0..1]

Definition: Contains the unique end to end transaction reference.

Format is lowercase separated by hyphens.

Datatype: "UUIDv4Identifier" on page 21 2.4.3 TimeWindow

Presence: [0..1]

Definition: Time window for this institution to which the search applies.

TimeWindow contains the following elements (see "DateTimePeriodDetails" on page 18 for details)

Or Element Mult. Type Constr. No.

Page

FromDateTime [1..1] DateTime 18

ToDateTime [1..1] DateTime 18



27 July 2018 6

2.4.4 TransactionStatus

Presence: [0..*]

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

TransactionStatus contains the following PaymentStatus4 elements


Page



2.4.4.1 Status

Presence: [1..1]

Definition: Reason for the status, as published in an external reason code list.

Datatype: "TransactionIndividualStatus5Code" on page 20

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

ACCC AcceptedCreditSettlementCompleted Settlement on the creditor's account has been completed.

2.4.4.2 Reason

Presence: [0..1]

Definition: Provides more details on the status in process.

Datatype: "PaymentReason2Code" on page 20


G005 DeliveredWithServicelLevel Payment delivered to creditor agent with service level

G006 DeliveredWithoutServicelLevel Payment delivered to creditor agent without service level.



27 July 2018 7


G001 PaymentTransferredAndNotTracked In an FI To FI Customer Credit Transfer: The Status Originator transferred the payment to the next Agent or to a Market Infrastructure. The payment transfer is not tracked. No further updates will follow from the Status Originator

In a Financial Institution Credit Transfer with cover: The Status Originator performed the account booking and transferred the cover transaction to the next Reimbursement Agent or to a Market Infrastructure. The payment transfer is not tracked. No further updates will follow from the Status Originator.

2.4.5 MaximumNumber Presence: [0..1]

Definition: Indicates the maximum number of entries returned.

Datatype: "Number" on page 22 2.4.6 More

Presence: [0..1]

Definition: Contains the token to get the next set of responses.

Datatype: "Max350Text" on page 22


GetCorporatePaymentTransactionsResponse

27 July 2018 8

3 GetCorporatePaymentTransactionsResponse

3.1 API Functionality Contains the response to the request to obtain information on the corporate status of one or more payment transactions.

Outline

The GetCorporatePaymentTransactionsResponse API is composed of 3 BuildingBlocks:

A. PaymentTransaction

Contains details on the payment transaction.

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.



27 July 2018 9

3.2 Structure

Or Element/BuildingBlock Mult. Type Constr. No.

Page

Root [1..1]

PaymentTransaction [1..*]

10


TransactionStatus [1..1]

11



EventTime [1..1] DateTime 12

Originator [1..1] IdentifierSet C2 12

InstructedAmount [0..1] Amount C1, C3 12

ConfirmedAmount [0..1] Amount C1, C3 13

PaymentEvent [1..*]

13

From [1..1] IdentifierSet C2 14

To [0..1] IdentifierSet C2 14

ChargeBearer [0..1] CodeSet 15

ChargeAmount [0..1] Amount C1, C3 15

ForeignExchangeDetails [0..1]

15

SourceCurrency [1..1] CodeSet C1 16

TargetCurrency [1..1] CodeSet C1 16

ExchangeRate [1..1] Rate 16

TotalNumber [1..1] Quantity 17

More [0..1] Text 17

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

C2 AnyBIC




27 July 2018 10

C3 CurrencyAmount

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

Note: The decimal separator is a dot.

3.4 Building Blocks This chapter describes the BuildingBlocks of this API.

3.4.1 PaymentTransaction

Presence: [1..*]

Definition: Contains details on the payment transaction.

PaymentTransaction contains the following PaymentTransaction75 elements


Page


TransactionStatus [1..1]

11



EventTime [1..1] DateTime 12

Originator [1..1] IdentifierSet C2 12

InstructedAmount [0..1] Amount C1, C3 12

ConfirmedAmount [0..1] Amount C1, C3 13

PaymentEvent [1..*]

13






15




3.4.1.1 UETR

Presence: [1..1]

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

Datatype: "UUIDv4Identifier" on page 21



27 July 2018 11

3.4.1.2 TransactionStatus

Presence: [1..1]

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

TransactionStatus contains the following PaymentStatus4 elements


Page



3.4.1.2.1 Status

Presence: [1..1]

Definition: Reason for the status, as published in an external reason code list.

Datatype: "TransactionIndividualStatus5Code" on page 20





3.4.1.2.2 Reason

Presence: [0..1]

Definition: Provides more details on the status in process.

Datatype: "PaymentReason2Code" on page 20






27 July 2018 12




3.4.1.3 EventTime Presence: [1..1]

Definition: This is the time when the related status was reached.

Datatype: "ISODateTime" on page 21 3.4.1.4 Originator

Presence: [1..1]

Definition: Party that issues the status.



Constraints

• AnyBIC


3.4.1.5 InstructedAmount

Presence: [0..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: C1 "ActiveOrHistoricCurrency", C3 "CurrencyAmount"

Datatype: "ActiveOrHistoricCurrencyAndAmount" on page 18



27 July 2018 13

Constraints

• ActiveOrHistoricCurrency


• CurrencyAmount



3.4.1.6 ConfirmedAmount Presence: [0..1]

Definition: The actual amount that has been paid to the ultimate beneficiary, after all charges etc... have been deducted.



Constraints



• CurrencyAmount



3.4.1.7 PaymentEvent Presence: [1..*]

Definition: This groups the information of an event, i.e., of a payment message or status confirmation update. It is repeated as many times as there are events to be returned.



27 July 2018 14

PaymentEvent contains the following PaymentEvent6 elements


Page






15




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



Constraints

• AnyBIC


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





27 July 2018 15

Constraints

• AnyBIC


3.4.1.7.3 ChargeBearer

Presence: [0..1]

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

Datatype: "ChargeBearerType3Code" on page 19


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.

3.4.1.7.4 ChargeAmount

Presence: [0..1]

Definition: Amount of money asked or paid for the charge.



Constraints



• CurrencyAmount



3.4.1.7.5 ForeignExchangeDetails Presence: [0..1]



27 July 2018 16

Definition: Specifies the exchange rate details between two currencies.

ForeignExchangeDetails contains the following CurrencyExchange8 elements


Page




3.4.1.7.5.1 SourceCurrency

Presence: [1..1]

Definition: Currency from which an amount is to be converted in a currency conversion.

Impacted by: C1 "ActiveOrHistoricCurrency"

Datatype: "ActiveOrHistoricCurrencyCode" on page 19

Constraints



3.4.1.7.5.2 TargetCurrency

Presence: [1..1]

Definition: Currency into which an amount is to be converted in a currency conversion.

Impacted by: C1 "ActiveOrHistoricCurrency"

Datatype: "ActiveOrHistoricCurrencyCode" on page 19

Constraints



3.4.1.7.5.3 ExchangeRate

Presence: [1..1]

Definition: Factor used to convert an amount from one currency into another. This reflects the price at which one currency was bought with another currency.

Usage: ExchangeRate expresses the ratio between UnitCurrency and QuotedCurrency (ExchangeRate = UnitCurrency/QuotedCurrency).

Datatype: "BaseOneRate" on page 22



27 July 2018 17

3.4.2 TotalNumber

Presence: [1..1]

Definition: Contains the total number of returned result entries.

Datatype: "Number" on page 22 3.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" on page 22


Types

27 July 2018 18

4 Types

4.1 Date Time

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


Page

FromDateTime [1..1] DateTime 18

ToDateTime [1..1] DateTime 18

4.1.1.1 FromDateTime

Presence: [1..1]

Definition: Date and time at which the range starts.

Datatype: "ISODateTime" on page 21 4.1.1.2 ToDateTime

Presence: [1..1]

Definition: Date and time at which the range ends.

Datatype: "ISODateTime" on page 21

4.2 Datatypes

4.2.1 Amount

4.2.1.1 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 19

Format minInclusive 0

totalDigits 18

fractionDigits 5


Types

27 July 2018 19

Constraints



• CurrencyAmount



4.2.2 CodeSet

4.2.2.1 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



4.2.2.2 ChargeBearerType3Code

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

Type: CodeSet


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.


Types

27 July 2018 20


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

4.2.2.3 PaymentReason2Code Definition: Provides the reason for a specific Payment Status.

Type: CodeSet






4.2.2.4 TransactionIndividualStatus5Code

Definition: Specifies the status of a single payment transaction.

Type: CodeSet






Types

27 July 2018 21

4.2.3 DateTime

4.2.3.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 4.2.4 IdentifierSet

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


4.2.4.2 UUIDv4Identifier

Definition: Universally Unique IDentifier (UUID) version 4, as described in IETC RFC 4122 "Universally Unique IDentifier (UUID) URN Namespace".

Type: IdentifierSet

Identification scheme: RFC4122; UUIDv4


Types

27 July 2018 22

Format

pattern [a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}

4.2.5 Quantity

4.2.5.1 Number Definition: Number of objects represented as an integer.

Type: Quantity

Format totalDigits 18

fractionDigits 0

4.2.6 Rate

4.2.6.1 BaseOneRate

Definition: Rate expressed as a decimal, eg, 0.7 is 7/10 and 70%.

Type: Rate

Format totalDigits 11

fractionDigits 10

baseValue 1.0

4.2.7 Text

4.2.7.1 Max350Text

Definition: Specifies a character string with a maximum length of 350 characters.

Type: Text

Format

minLength 1

maxLength 350


Legal Notices

27 July 2018 23

Legal Notices Copyright SWIFT © 2018. All rights reserved.

Restricted Distribution Do not distribute this publication outside your organisation unless your subscription or order expressly grants you that right, in which case ensure you comply with any other applicable conditions.

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

Documents

SWIFT Developer Portal | Homepage - Tracker API …...2.4.5 MaximumNumber Presence: [0..1] Definition: Indicates the maximum number of entries returned. Datatype: "Number" on page