Transcription
SWIFT gpi API v5EnhancementsJuly 2021
A strategic channel for the SWIFT community2bn Cumulative API calls in 2020 175mAPI calls made a month400 API institutional consumers
gpi API v5 availability1. API specifications, schemas and documentation available on SWIFT developer portal:https://developer.swift.com2. gpi APIs version 3, enters maintenance mode when v5 becomes available in Live in November 2021(end of support on 30 April 2022)3. Switching from gpi connector to SDK & Microgateway to consume gpi API v54. Questions and feedback related to the API specifications can be sent to your API onboarding consultant (ifsubscribed to this service), standard swift.com support channel or developer-support@swift.comAPIDeliverablesQ1 2021June 2021Data Modelling andAPI SpecificationAPI SpecificationspublishedDoneIn progress25 July 2021Pilot21 Nov 2021Live3
Why choose APIv5?Payment status update APIs specific to the gpi service level Improved data modelling based on the gpi service Less cross-service constraints Easier maintenance (changes will apply only to the service with newbusiness features, the other APIs are unchanged) GET APIs share the same datamodel in all API responses (like in v3/v4)gpi ISO Readiness (advantages in API v5) Alignment of datatypes with ISO 20022 (interoperability)Alignment with gpi ISO rulebookAlignment with CBPR /PMI Usage Guidelines (common denominator)Alignment of the API with the trck datamodel (interoperabilityAPI/messaging)New features (not available in API v3/4) Increased reject return reason code listForwarded To Agent identifiable with national clearing codePartial credit confirmation functionalityAmount inconsistency flag in GET gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
gpi API v5 – technical highlightsWhatchangesshould Iexpect tomake?Update Status of PaymentTransactionGet transaction status / Getchanged transactionsRequest cancellation / updatestatus of cancelled transactionConnecting to / Consuming theAPIsv4v5Single API for: gCCT, gCOV, gFIT toupdate transaction status Status reads for gCCT,gCOV, gFIT, gSRP (status),gCASE Cancellations (gSRP)Implement the API for each ofgCCT, gCOV, gFIT as requiredSWIFT SDK and Microgateway(small number of gpiConnectorexceptions)Install Microgateway orimplement SDKImplement back-office APIconsumption via Microgatewayor SDKImplement new API (single APIfor all status reads andcancellations)5
gpi API v5API Consumption remains unchanged for gpi API v5SWIFT MicrogatewaySWIFT Software Developer Kit (SDK)Generic self-service API concentratorZero-footprint API libraryFrom 1 to 6 months effort per API servicedeployedFrom 2 weeks to 3 months, irrespectiveof the no. of services deployedConsume any API service on SWIFTConsume any API service on SWIFTShields applications from API security& session protocolSimplify API technical integration effortStandalone or embeddableMulti-tenancy – business flow segregationAny programming language applicationJava based application environment onlyLiveLive6
APIv3/4 vs APIv5 – splitting of Payment Status Request APIv3v4PaymentStatusRequest(single APIallservices)PaymentStatusRequest(single APIallservices)gCCT gCOV gpi OVPaymentStatusRequestUC gCCTInstant INSTPaymentStatusRequestgSLVPPaymentStatusRequest gFIT gpiSLVP(simple)ISO MXchannelv5 N/AN/AN/AChange to make in v5 trck UGgCCTtrck UGgCOVtrck UGgFITtrck UGUCtrck UGgCCTINSTtrck UGgSLVP Implement separate API per service
APIv3/4 vs APIv5 – no splitting of other APIsgCCTgCOVgFITUCgCCTINSTgSLVPV3 & V4 & V5GET Transactions Details (UETR-search) GET Changed Transactions (time-range) PUT Request Cancellation(gSRP) *PUT Update Status Cancelled Transaction(gSRP) * ** ** *only v5**In V3, Service Level G009 is converted to G001Change to make in v5 Implement new version of APIsgpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
Split Payment Status Request APIs – gCCT/gCOVSWIFT gpi Tracker1DebtorCredited45gCCT Payment Status RequestgCOV Payment Status RequestMT 103 / pacs.008gpi AgentSTI 001/Service Level(gCCT Debtor Agent/G001gCOV Debtor)2gpi Agent(gCCT Creditor Agent/gCOV Creditor)3MT 202COV / pacs.009 COVE on SWIFTMT 202COV / pacs.009COVE on SWIFTgpi Agentgpi Agent(gCOV Debtor Agent)(gCOV Creditor Agent)Split APIsCreditedType of operationv3/v4v5gpi Agent updates status ofgCCT transaction (f.ex. Step 5)Send PaymentStatusRequestAPI withUpdatePaymentScenario CCTRSend gCCTPaymentStatusRequest APIgpi Agent updates status ofgCOV transaction (f.ex. Step 4)Send PaymentStatusRequestAPI withUpdatePaymentScenario COVESend gCOVPaymentStatusRequest APIgpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.Creditor
Split Payment Status Request APIs – gFIT & gFIT cover-like transactionSWIFT gpi Tracker1gpi Agent(gFIT DebtorgFIT Debtor)Credited5gFIT Payment Status RequestgFIT Payment Status RequestMT 202 / pacs.009 ADVICESTI 004/Service Level G0042MT 202 / pacs.009 on SWIFTSTI 004/Service Level G004Split APIsCredited4gpi Agent(gFIT Creditor Agent/gFIT Creditor)3gpi Agent(gFITDebtor Agent)MT 202 / pacs.009 on SWIFTSTI 004/Service Level G004 gpi Agent(gFITCreditor Agent)Type of operationv4 (v3 not applicable)v5gpi Agent updates status ofgFIT transaction (step 4 and 5)Send PaymentStatusRequestAPI withUpdatePaymentScenario FCTRSend gFITPaymentStatusRequest APIgpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.gpi Agent(gFIT Creditor)
Split Payment Status Request APIs – gCCT/UCSWIFT gpi TrackerOn hold2CreditedgCCT Payment Status Request1DebtorSplit APIsgpi Agent(gCCT Debtor Agent)MT 103/pacs.008STI 001/ServiceLevel G0014UC Payment Status Request3MT 103/pacs.008gpi AgentWith or without STI 005/ServiceLevel G005(gCCT IntermediaryAgent)Type of operationv3/v4v5gpi Agent updates status ofgCCT transaction (f.ex. step 2)Send PaymentStatusRequestAPI with Service Level* 001 andUpdatePaymentScenario CCTRSend gCCTPaymentStatusRequest APINON gpi Agent updates statusof transaction (f.ex. Step 4)Send PaymentStatusRequestAPI without Service Level* andwith UpdatePaymentScenarioCCTRSend UCPaymentStatusRequest APINON gpi Agent(Creditor Agent)Creditor*called BusinessServicein v4 spec
Comparison between v4 and v5gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
V5V4Status Confirmations 1/2This API is a status confirmation update to inform the Tracker about the updated status of a givenpayment.No change Separate specifications by service levelNo change to path/URI from v4 to v5 (remains /payments/{uetr}/status)Consistent path across each API specification by service levelData model changes for API request: Party Identification: replacement of AnyBIC with BICFI.BusinessService renamed into ServiceLevel and use of 4-character codes (f.ex. G001, G004, etc, ). ISO alignmentUpdatePaymentScenario was simplified to PaymentScenario.Payment Scenario element changed logic: in v4 used to select type of update (CCTR or COVE or FCTR). In v5, no longerneeded for this purpose as we have separate specifications by service level. In V5, element allows for update on normalpayment transaction versus update on return transaction (future).All identifications are 35 characters (instruction identification & end to end identification). ISO alignmentTransactionStatusReason element only used for reasons linked to status ACSP.New element RejectReturnReason to be used for reasons linked to status RJCT.Number of reject return reasons increased. ISO alignmentReturn boolean removed (returns for SR2022 presence RejectReturnReason in combination with certain transactionstatuses/transaction status reasons will indicate update on return transaction).gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
V5V4Status Confirmations 2/2This API is a status confirmation update to inform the Tracker about the updated status of a givenpayment.No changeRequest (continued) FundsAvailable element renamed into ConfirmedDate.Confirmed Date only used for ACCC.New element TransactionStatusDate used for ACSP/G000 & G001 and RJCT.DateTime element allow only UTC/Zulu and local time with UTC offset.StatusOriginator renamed into TrackerInformingParty.ForwardedToAgent renamed into InstructedAgent. ISO alignmentInstructedAgent can be identified with a ClearingSystemMemberIdentification (alternative to BIC). ISO alignmentChargesInformation now includes the identification of the Agent taking the charge (only applicable to gCCT/UC/gCCTINST/gSLVP)ISO alignmentAll amounts are 18 digits (excluding decimal dot) ISO alignmentForeign Exchange Details structure was flattened.New elements RemainingToBeConfirmedAmount and PreviouslyConfirmedAmount (only applicable to gCCT/gCCTINST/gSLVP)ConfirmedAmount only used for ACCCInterbankSettlementAmount introduced to be used for ACSP/G000&G001. Optionally for RJCT, ACSP/G002&G003&G004. ISOalignmentResponse No change to response for gCCT, gCOV, gFIT, UC, gCCTINSTgSLVP response may provide a warning message when request is invalid but accepted (e.g. when charge bearer not equal to‘SHAR’)
V5V4Get Payment Transaction DetailsPayment query to get detailed information regarding a given payment. It requires the UETR to beknownNo changeResponse All data model changes applicable to Status Confirmations (previousslide) also applicable to GET APIs Additional data model changes: Datatype timestamps changed to UTC/Zulu (tracker bydefault delivers UTC/Zulu) New element AmountInconsistency New code SLEV in ChargeBearer element ISO alignment Inclusion of new parties: ISO alignmento PreviousInstructingAgent1-2-3o IntermediaryAgent2-3 Network references increased to Max50Text. Seven new Tracker Event Types:o Three codes for cancellation of FITo Four codes for cover of a FIT Renaming of certain elements (f.ex. Sendergpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –Acknowledgement Receipt changed to SenderSWIFT 2021. All rights reserved.Acknowledgement Receipt Date Time)Request No change to request.
Get Changed Payment TransactionsV5V4This API is a delta query to get all payment update information starting from a given date and timeNo changeResponseRequest All data model changes applicable to Status Confirmations (previousslide) also applicable to GET APIs Query Parameter ‘PaymentScenario’ extended with 3 new Additional data model changes:values: Datatype timestamps changed to UTC/Zulu (tracker by FCOV Cover Financial Institution Credit Transferdefault delivers UTC/Zulu) CTCN Customer Credit Transfer Cancellation New element AmountInconsistency FTCN Financial Institution Credit Transfer Cancellation New code SLEV in ChargeBearer element Inclusion of new parties:o PreviousInstructingAgent1-2-3o IntermediaryAgent2-3 Network references increased to Max50Text. Seven new Tracker Event Types:o Three codes for cancellation of FITo Four codes for cover of a FIT Renaming of certain elements (f.ex. Sendergpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –Acknowledgement Receipt changed to SenderSWIFT 2021. All rights reserved.Acknowledgement Receipt Date Time)
Get Payment Transaction Details/Get Changed PaymentTransactionsInclusion of new parties (detail): ISO alignment PreviousInstructingAgent1-2-3 IntermediaryAgent2-3V4V5V5V4
V5V4Cancel TransactionRequesting cancellation of a transaction.No changeRequest BusinessService renamed into ServiceLevel with code G002 ISO alignment OriginalInstructionIdentification 35 char ISO alignment New element OriginalMessageNameIdentification with codeset:o pacs.008 -Identifies a customer credit transfer payment (MT 103, pacs.008, .)o pacs.009 -Identifies a financial institution credit transfer payment (MT 202, MT 205,pacs.009 CORE, .).Response No changegpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
V5V4Transaction Cancellation StatusUpdating the status of a transaction cancellation.No changeRequest BusinessService renamed into ServiceLevel with code G002 ISO alignment StatusOriginator renamed into TrackerInformingParty ForwardedToAgent renamed into InstructedAgent ISO alignmentResponse No changegpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
Comparison between v3 and v5gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.
Status Confirmations (1/3)This API is a status confirmation update to inform the Tracker about the updated status of a givenpayment. Separate specifications by service levelChange to path/URI from v3 to v5 (from “/payment/status” TO “/payments/{uetr}/status”)In v5, consistent path across each API specification by service levelRequest Party Identification: replacement of AnyBIC with BICFI. BusinessService renamed into ServiceLevel and use of 4-character codes (f.ex. G001, G004, etc, ). UpdatePaymentScenario was simplified to PaymentScenario. Payment Scenario element changed logic: in v3 used to select type of update (CCTR or COVE). In v5,no longer needed for this purpose as we have separate specifications by service level. In V5, elementallows for update on normal payment transaction versus update on return transaction (future). UETR required in URI (as shown above) and removed from request body. New field added: end to end identification (only gCOV/gFIT). All identifications are 35 characters (instruction identification & end to end identification).gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.V5V3
Status Confirmations (2/3)This API is a status confirmation update to inform the Tracker about the updated status of a givenpayment.Request (continued) payment status request object wrapping the request parameters removed. payment status object removed and inner attributes moved up one level. transaction status object replaced with transaction status and transaction status reason attributes. TransactionStatusReason element only used for reasons linked to status ACSP. New element RejectReturnReason to be used for reasons linked to status RJCT. Number of reject return reasons increased (16 to 51). Return boolean removed (returns for SR2022 presence RejectReturnReason in combination withcertain transaction statuses/transaction status reasons will indicate update on return transaction). FundsAvailable element renamed into ConfirmedDate. Confirmed Date only used for ACCC. New element TransactionStatusDate used for ACSP/G000 & G001 and RJCT. DateTime element allow only UTC/Zulu and local time with UTC offset. StatusOriginator renamed into TrackerInformingParty. ForwardedToAgent renamed into InstructedAgent. InstructedAgent can be identified with a ClearingSystemMemberIdentification (alternative to BIC).V5V3
Status Confirmations (3/3)This API is a status confirmation update to inform the Tracker about the updated status of a givenpayment.Request (continued) ChargesInformation now includes the identification of the Agent taking the charge (onlyapplicable to gCCT/UC/gCCTINST/gSLVP) All amounts are 18 digits (excluding decimal dot) Foreign Exchange Details structure was flattened New elements RemainingToBeConfirmedAmount and PreviouslyConfirmedAmount (onlyapplicable to gCCT/gCCTINST/gSLVP) ConfirmedAmount only used for ACCC InterbankSettlementAmount introduced to be used for ACSP/G000&G001. Optionally forRJCT, ACSP/G002&G003&G004.Response The successful response body is removed. The API responds with 200 OK for successfultracker updates. gSLVP response may provide a warning message when request is invalid but accepted(e.g. when charge bearer not equal to ‘SHAR’)V5V3
Pdf specification – constraintsThe v5 pdf specification of each PUT API includes an exhaustive overview of the cross-elementcomplex rules that are validated by the application.Also available on theDeveloper Portalgpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.V5V3
V5V3Get Payment Transaction DetailsPayment query to get detailed information regarding a given payment. It requires the UETR to beknownRequest No change to requestResponse All data model changes applicable to Status Confirmations (previousslide) also applicable to GET APIsAdditional data model changes: Datatype timestamps changed to UTC/Zulu (tracker bydefault delivers UTC/Zulu) New element AmountInconsistency New code SLEV in ChargeBearer element Inclusion of new parties:oo gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.Network references increased to Max50Text.14 new Tracker Event Types:oooo ne code for FIT paymentThree codes for cancellation of FITTwo codes for cover of a FITEight codes for returnRenaming of certain elements (f.ex. Sender AcknowledgementReceipt changed to Sender Acknowledgement Receipt Date Time)
V5V3Get Changed Payment TransactionsThis API is a delta query to get all payment update information starting from a given date and timeRequest Query Parameter ‘PaymentScenario’ extended with 3 newvalues: FCOV Cover Financial Institution Credit TransferCTCN Customer Credit Transfer CancellationFTCN Financial Institution Credit Transfer CancellationResponse All data model changes applicable to Status Confirmations (previousslide) also applicable to GET APIsAdditional data model changes: Datatype timestamps changed to UTC/Zulu (tracker bydefault delivers UTC/Zulu) New element AmountInconsistency New code SLEV in ChargeBearer element Inclusion of new parties:oo gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.Network references increased to Max50Text.14 new Tracker Event Types:oooo ne code for FIT paymentThree codes for cancellation of FITTwo codes for cover of a FITEight codes for returnRenaming of certain elements (f.ex. Sender AcknowledgementReceipt changed to Sender Acknowledgement Receipt Date Time)
Get Invalid EventsQuery to get invalid events for payment transactions within a given time frameGet Invalid Events removed due to rare usage.gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.V5V3
V5V3Cancel TransactionRequesting cancellation of a transaction.Request UETR required in URI (as shown above) and removed from request body. cancel transaction request object wrapping the request removed. In From, AnyBIC replaced by BICFI. underlying cancellation details flattened; cancellation reason information attribute andindemnity agreement attribute moved up to root object. BusinessService renamed into ServiceLevel with code G002 OriginalInstructionIdentification 35 char New element OriginalMessageNameIdentification with codeset:o pacs.008 -Identifies a customer credit transfer payment (MT 103, pacs.008, .)o pacs.009 -Identifies a financial institution credit transfer payment (MT 202, MT205, pacs.009 CORE, .).Response The successful response body is removed. The API responds with 200 OK for successfultracker updates.
Transaction Cancellation StatusUpdating the status of a transaction cancellation.Request UETR required in URI (as shown above) and removed from request body. transaction cancellation status request object wrapping the request removed. In From, AnyBIC replaced by BICFI. underlying cancellation details flattened; investigation execution status andinvestigation execution status reason attributes moved up to root object. BusinessService renamed into ServiceLevel with code G002 StatusOriginator renamed into TrackerInformingParty ForwardedToAgent renamed into InstructedAgentResponse The successful response body is removed. The API responds with 200 OK for successfultracker updates.gpi API v5 changes- Confidentiality: RESTRICTED. Do not disclose to third parties without SWIFT's prior written consent –SWIFT 2021. All rights reserved.V5V3
1. API specifications, schemas and documentation available on SWIFT developer portal: https://developer.swift.com 2. gpi APIs version 3, enters maintenance mode when v5 becomes available in Live in November 2021 (end of support on 30 April 2022) 3. Switching from gpi connector to SDK & Microgateway to consume gpi API v5 4.
