SWIFT GPI Webhooks

Overview

The MassPay SWIFT gpi Webhook enhancement provides customers with real-time, machine-readable SWIFT payment tracking updates for eligible UETR-tracked payments. Customers can consume these webhook events to update ERP, treasury, reconciliation, beneficiary service, and internal operations systems with end-to-end payment visibility.

The enhancement is additive to existing MassPay payment status webhooks. Customers enabled for eventVersion=2.0 receive a new gpi object containing SWIFT tracker status, universal confirmation details, routing participants, fee information, timestamps, and status history.

Webhook Endpoint & Customer Configuration

Customers must provide a secure HTTPS endpoint capable of receiving MassPay webhook events.

• HTTP Method: POST
• Customer Endpoint: Customer-hosted HTTPS URL registered with Convera, for example https://customer.example.com/webhooks/masspay
• Event Type: payment.status.changed
• Event Version: 2.0 for SWIFT gpi-enriched payloads
• Eligibility: SWIFT payments where a valid UETR is available and the customer has been enabled for the gpi webhook feature flag

Request Headers Sent by Convera

Webhook Payload Specification

The payload follows the standard MassPay payment status webhook structure with an additional gpi object for eligible SWIFT payments. All timestamps are ISO 8601 UTC values. Monetary values are represented as decimal strings to avoid precision loss.

• Core Payload Fields
• eventId (string, required): Unique webhook event identifier.
• eventType (string, required): Always payment.status.changed.
• eventVersion (string, required): 2.0 for gpi-enriched events.
• occurredAt (string, required): Date/time the event occurred.
• customerId (string, required): Convera-assigned customer identifier.
• paymentId (string, required): Unique MassPay payment identifier.
• batchId (string, optional): Batch identifier where applicable.
• status (object, required): Canonical MassPay payment status and reason fields.
• network (object, required for tracked SWIFT payments): Includes scheme=SWIFT and the payment uetr.
• gpi (object, conditional): Present only for eligible SWIFT/UETR payments and enabled customers.

Example Webhook Payload

{
  "eventId": "c3b1f1e0-8c5a-4a98-9c2e-7d9b1e6c9f21",
  "eventType": "payment.status.changed",
  "eventVersion": "2.0",
  "occurredAt": "2026-02-02T00:10:25Z",
  "customerId": "123456",
  "paymentId": "abcde-12345",
  "batchId": "batch-789",
  "status": {
    "code": "CREDITED",
    "reasonCode": "",
    "reasonDescription": "",
    "updatedAt": "2026-02-02T00:10:25Z"
  },
  "network": {
    "scheme": "SWIFT",
    "uetr": "c2b02c6e-8d2d-4f63-93a0-9b2c640b2f10"
  },
  "amount": {
    "currency": "USD",
    "instructedAmount": "1250.00",
    "settlementAmount": "1245.50"
  },
  "beneficiary": {
    "name": "ACME LLC",
    "account": "****1234",
    "bankBic": "BOFAUS3N"
  },
  "gpi": {
    "trackerStatus": "ACTC",
    "universalConfirmation": {
      "credited": true,
      "creditedTimestamp": "2026-02-02T00:10:25Z"
    },
    "fees": {
      "totalFeeAmount": "4.50",
      "feeCurrency": "USD",
      "feeBearer": "SHA",
      "deductedAtInstitutions": [
        {
          "bic": "IRVTUS3N",
          "amount": "2.00",
          "currency": "USD"
        },
        {
          "bic": "BNPAFRPP",
          "amount": "2.50",
          "currency": "USD"
        }
      ]
    },
    "route": {
      "originatorBank": {
        "bic": "WBUSUS6L"
      },
      "intermediaries": [
        {
          "bic": "IRVTUS3N"
        },
        {
          "bic": "BNPAFRPP"
        }
      ],
      "beneficiaryBank": {
        "bic": "BOFAUS3N"
      }
    },
    "timestamps": {
      "sentToNetworkAt": "2026-02-02T00:00:10Z",
      "receivedByIntermediaryAt": "2026-02-02T00:05:30Z",
      "creditedAt": "2026-02-02T00:10:25Z",
      "completionTimeSeconds": 615
    },
    "history": [
      {
        "sequence": 1,
        "trackerCode": "ACSP",
        "statusText": "Accepted for Settlement",
        "institution": {
          "bic": "WBUSUS6L"
        },
        "recordedAt": "2026-02-02T00:00:10Z"
      },
      {
        "sequence": 2,
        "trackerCode": "G000",
        "statusText": "Received by Intermediary",
        "institution": {
          "bic": "IRVTUS3N"
        },
        "recordedAt": "2026-02-02T00:05:30Z"
      },
      {
        "sequence": 3,
        "trackerCode": "ACTC",
        "statusText": "Credited to Beneficiary",
        "institution": {
          "bic": "BOFAUS3N"
        },
        "recordedAt": "2026-02-02T00:10:25Z"
      }
    ],
    "references": {
      "endToEndId": "E2E-00991",
      "instructionId": "INS-48821",
      "transactionId": "TRN-77701"
    },
    "reasoning": {
      "swiftReasonCode": "",
      "swiftReasonText": "",
      "converaMappedCode": ""
    }
  }
}

Status Outcomes & Customer Handling Matrix

Delivery, Retries & Idempotency

Security, Validation & Best Practices

• Use HTTPS only: Customer webhook endpoints must use TLS 1.2 or higher and a trusted certificate.
• Verify webhook authenticity: Validate the webhook signature where enabled before processing the payload.
• Deduplicate events: Store processed eventId values to prevent duplicate downstream updates.
• Persist audit identifiers: Store paymentId, batchId, uetr, endToEndId, instructionId, and X-Correlation-Id.
• Handle missing optional fields: Not all SWIFT tracker updates include full fee, routing, or timestamp data. Treat optional fields as nullable.
• Protect payment data: Do not log full account numbers or unnecessary beneficiary information. Preserve masking in downstream logs.
• Process asynchronously: Return a 2xx acknowledgement quickly and perform ERP/reconciliation updates via internal queues or background workers.