Payment Confirmation API

Overview

The MassPay Payment Confirmation API is a secure, pull-based REST API that enables customers to retrieve machine-readable payment confirmations for payments processed through MassPay. Confirmations can be used for treasury reconciliation, audit evidence, beneficiary servicing, payment tracking, ERP posting, and downstream operational workflows.

The API supports two selectable confirmation formats:

CPP-equivalent JSON: the canonical MassPay/CPP confirmation schema for customer system integration.

ISO 20022 pacs.008 XML: available where enabled for eligible corridors and customer configurations.

API Endpoint & Base URLs

HTTP Method: GET

Path: /confirmations/customers/{customerId}/payments/{paymentId}

Environments:

Sandbox / UAT: https://masspaysandbox-oauth.api.convera.com/masspayments /confirmations/customers/{customerId}/payments/{paymentId}

Production: https://oauth.api.convera.com/masspayments /confirmations/customers/{customerId}/payments/{paymentId}

Request Headers

Header	Required	Description
Authorization	Yes	Bearer {oauth_access_token} issued via approved MassPay API credentials.
Accept	Recommended	Use application/json for CPP confirmation or application/xml for pacs.008 confirmation.
Accept-Version	Recommended	API version header used to support non-breaking contract evolution.
X-Correlation-Id	Recommended	Customer-generated identifier for end-to-end audit tracing, operational support, and log correlation.

Request Specification

Path Parameters

customerId (string, required): Convera-assigned customer identifier.

paymentId (string, required): MassPay unique payment identifier.

Query Parameters

format (string, optional): Requested confirmation format. Supported values are CPP and PACS008. Defaults to CPP if omitted.

includeSignature (boolean, optional): When true, returns a cryptographic signature where configured for the customer and format.

GET /confirmations/customers/12345/payments/95a147ec-986a-4c25-b569-a96955340d9b?format=CPP&includeSignature=false
Authorization: Bearer {oauth_access_token}
Accept: application/json
Accept-Version: 1
X-Correlation-Id: deb2787e-da14-4ebe-b701-d8de79000452

Response Specification & Handling Matrix

Example CPP JSON Response

{
  "confirmation": {
    "paymentId": "95a147ec-986a-4c25-b569-a96955340d9b",
    "customerPaymentId": "PT213668465614",
    "orderId": "42926719-3b0b-4307-8607-3bb6791d0f4e",
    "batchId": "NTR7865170",
    "status": "SENT_TO_NETWORK",
    "amount": {
      "currency": "USD",
      "value": 100.00
    },
    "beneficiary": {
      "name": "ACME SUPPLIER LLC",
      "account": {
        "accountNumber": "000123456789"
      },
      "bank": {
        "bic": "CHASUS33XXX",
        "name": "JPMORGAN CHASE BANK",
        "country": "US"
      }
    },
    "payer": {
      "name": "ACME INC",
      "account": {
        "accountNumber": "9988776655"
      },
      "bank": {
        "bic": "CONVGB2LXXX"
      }
    },
    "chargesBearer": "SHAR",
    "purposeCode": "SALA",
    "endToEndId": "PT213668465614",
    "instructionId": "I-95a147ec",
    "uetr": "f1b7a6a1-23dc-4d3b-8e3b-3f1b1b5a1d11",
    "valueDate": "2024-11-27",
    "createdAt": "2024-11-27T09:10:53.088Z",
    "lastUpdatedAt": "2024-11-27T10:15:20.010Z",
    "networkProvenance": {
      "instructingAgent": "CONVGB2LXXX",
      "instructedAgent": "CHASUS33XXX",
      "clearingReference": "REF123456",
      "localInstrument": "WIRE"
    }
  },
  "metadata": {
    "statusCode": 200,
    "statusDescription": "Success",
    "correlationId": "deb2787e-da14-4ebe-b701-d8de79000452"
  }
}

Example pacs.008 XML Response

GET /confirmations/customers/12345/payments/95a147ec-986a-4c25-b569-a96955340d9b?format=PACS008&includeSignature=false
Accept: application/xml
Authorization: Bearer {oauth_access_token}
X-Correlation-Id: deb2787e-da14-4ebe-b701-d8de79000452

HTTP/1.1 200 OK
Content-Type: application/xml
X-Correlation-Id: deb2787e-da14-4ebe-b701-d8de79000452

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>I-95a147ec</MsgId>
      <CreDtTm>2024-11-27T09:10:53.088Z</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <SttlmInf>
        <SttlmMtd>CLRG</SttlmMtd>
      </SttlmInf>
      <InstgAgt>
        <FinInstnId>
          <BICFI>CONVGB2LXXX</BICFI>
        </FinInstnId>
      </InstgAgt>
      <InstdAgt>
        <FinInstnId>
          <BICFI>CHASUS33XXX</BICFI>
        </FinInstnId>
      </InstdAgt>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <InstrId>I-95a147ec</InstrId>
        <EndToEndId>PT213668465614</EndToEndId>
        <UETR>f1b7a6a1-23dc-4d3b-8e3b-3f1b1b5a1d11</UETR>
      </PmtId>
      <IntrBkSttlmAmt Ccy="USD">100.00</IntrBkSttlmAmt>
      <IntrBkSttlmDt>2024-11-27</IntrBkSttlmDt>
      <ChrgBr>SHAR</ChrgBr>
      <Dbtr>
        <Nm>ACME INC</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <Othr>
            <Id>9988776655</Id>
          </Othr>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BICFI>CONVGB2LXXX</BICFI>
        </FinInstnId>
      </DbtrAgt>
      <CdtrAgt>
        <FinInstnId>
          <BICFI>CHASUS33XXX</BICFI>
          <Nm>JPMORGAN CHASE BANK</Nm>
        </FinInstnId>
      </CdtrAgt>
      <Cdtr>
        <Nm>ACME SUPPLIER LLC</Nm>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <Othr>
            <Id>000123456789</Id>
          </Othr>
        </Id>
      </CdtrAcct>
      <Purp>
        <Cd>SALA</Cd>
      </Purp>
      <RmtInf>
        <Ustrd>Payment confirmation for customer payment PT213668465614</Ustrd>
      </RmtInf>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

Confirmation Status Values

Status	Description	Recommended Customer Action
COMMITTED	Payment is committed in MassPay and confirmation data is available or becoming available.	Store the confirmation record and continue monitoring payment progress if final network status is required.
SENT_TO_NETWORK	Payment instruction has been released or forwarded to the clearing scheme, correspondent bank, or network.	Use as evidence that the payment was instructed externally. Store alongside ERP or treasury records.
ACCEPTED	Downstream network, clearing partner, or receiving institution has accepted the instruction where confirmation is available.	Update downstream ledgers and customer-facing payment tracking to reflect accepted status.
REJECTED	Payment was rejected before or during downstream execution.	Do not treat as proof of successful payment. Route to exception handling and review reject details.

HTTP Error Handling & Resilience

HTTP Status	Scenario	Recommended Handling
200 OK	Confirmation successfully returned.	Validate the response format, persist the payload, and store key references such as paymentId, customerPaymentId, endToEndId, and uetr.
400 Bad Request	Malformed path, invalid query parameter, or unsupported parameter value.	Correct the request before retrying. Do not retry unchanged invalid requests.
401 / 403	Authentication failure, expired token, missing scope, or customer not authorised for the resource.	Refresh OAuth token and verify production scopes and customer entitlements.
404 Not Found	Payment not found for the specified customer, or requested format is unavailable for the corridor.	Check customerId, paymentId, corridor eligibility, and format enablement.
409 Conflict	Payment is not yet in a confirmable state.	Retry after the Retry-After interval where provided, or wait for the next payment status event.
422 Unprocessable Entity	Unsupported parameter combination, such as requesting a signature when signatures are not enabled.	Adjust query parameters or confirm customer configuration before retrying.
429 Rate Limited	Customer or client has exceeded API rate limits.	Back off and retry according to the Retry-After header.
5xx Server Error	Transient platform, gateway, or downstream service issue.	Retry using exponential backoff and retain the same X-Correlation-Id for traceability.

Best Practices & Example Flow

Trigger confirmation retrieval from payment state: call the API once the payment reaches a confirmable state such as COMMITTED, SENT_TO_NETWORK, or ACCEPTED.

Store immutable confirmation artefacts: persist the JSON or XML confirmation payload in your customer system for reconciliation, audit, servicing, and dispute support.

Use stable identifiers for reconciliation: index confirmations by paymentId, customerPaymentId, endToEndId, instructionId, and uetr where available.

Apply data protection controls: avoid logging unmasked account details or personal data. Mask beneficiary and payer information in operational logs unless full details are explicitly required and authorised.

Handle unavailable formats gracefully: use CPP JSON as the canonical format and request PACS008 only where the corridor and customer configuration support it.

Verify signatures where enabled: when includeSignature=true, validate the returned JWS or XMLDSIG signature using Convera-published keys and your internal trust policy.

Example Customer Integration Flow

Customer submits or releases a payment through MassPay.

Customer system receives a payment status update or polls until the payment is confirmable.

Customer system calls GET /confirmations/customers/{customerId}/payments/{paymentId} with the desired format.

MassPay returns the confirmation payload and metadata.

Customer stores the confirmation, reconciles it against ERP/treasury records, and exposes the status to authorised internal users.