# Data Explanations
source: https://developer.mastercard.com/payment-initiation-api/documentation/tutorial-and-guide/data-explanation/index.md

## Overview {#overview}

The Payment Initiation API uses a set of core data elements to initiate, manage, and track commercial card payment instructions under the ISO 20022 standard. These data objects support debtor onboarding, payment submission, cancellation workflows, and event-driven status notifications.

## Payment Instructions {#payment-instructions}

Payment instructions represent commercial card payments initiated by Debtor Agents and processed through Commercial Direct Payments (CDP).

* **`instruction_identification`**: A unique UUID identifying each payment instruction.
* **`ica`**: Interbank Card Association (ICA) ID identifying the Debtor Agent submitting the payment.
* **`CustomerCreditTransferInitiation`**: ISO 20022--compliant payment initiation payload containing payment, debtor, creditor, and remittance details. This payload is encrypted in transit.
* **`status`**: Lifecycle state of the payment instruction, updated as the payment progresses or is cancelled.

Payment instructions are created, retrieved, and updated (for cancellation only) through the payment initiation and status update endpoints.

## Debtors {#debtors}

Debtors represent buyers who initiate commercial card payments.

* **`debtorId`**: A system-generated UUID identifying a registered debtor.
* **`legal_business_name`**: Legal business name of the debtor organization.
* **`dba`**: Doing Business As name of the debtor.
* **`is_active`**: Boolean flag indicating whether the debtor is currently active in CDP.

Debtor records are managed through Debtor Registration endpoints.

## Debtor Profiles {#debtor-profiles}

Debtor profiles define how a debtor initiates payments and are referenced during payment initiation.

* **`debtor_profile_id`**: A unique identifier created by the Debtor Agent to identify a debtor payment profile.
* **`debtorId`**: Reference to the associated debtor registration.
* **`ica`**: ICA of the Debtor Agent managing the profile.

A debtor can maintain one or more profiles to support different payment configurations.

## Creditors (Read‑Only) {#creditors-readonly}

Creditors represent suppliers receiving commercial card payments.  

In the Payment Initiation API, creditor data is retrieved for reference only.

* **`creditor_profile_id`**: A unique identifier created by the Creditor Agent to identify the creditor profile.
* **`CreditorRecord`**: Creditor-related information returned when querying creditor details.

Creditor onboarding and configuration are handled through the Payment Initiation API.

## Payment Status Updates (Cancellation) {#payment-status-updates-cancellation}

Payment status updates in the Payment Initiation API are limited to cancellation-related actions initiated by Debtor Agents.

* **`DebtorPaymentStatusUpdate`**: Request payload used to submit a cancellation request.
* **`instruction_identification`**: Identifies the payment instruction to be cancelled.
* **`status`**: Updated status reflecting the cancellation request outcome.

Only cancellation-related updates are supported through Debtor Agent status update operations.

## Event Notifications {#event-notifications}

Event notifications deliver asynchronous updates related to payment instruction status changes.

* **`eventId`**: A unique identifier for the notification event.
* **`eventType`** : Type of event triggering the notification. Supported values include:
  * `CARD_PAYMENT_STATUS_UPDATED`
  * `PAYMENT_CANCELLATION_ACCEPTED`
  * `PAYMENT_CANCELLATION_REJECTED`
* **`eventCreatedDate`**: Timestamp indicating when the event was created.
* **`data`**: Event-specific payload containing payment instruction and status details.

Notifications are delivered to Debtor Agent webhook endpoints.

## Error Handling {#error-handling}

All error responses use a consistent structure across Payment Initiation endpoints.

* **`Source`**: Identifies the service where the error occurred.
* **`ReasonCode`**: Machine-readable error code.
* **`Description`**: Human-readable explanation of the error.
* **`Recoverable`**: Indicates whether the request can be safely retried.
* **`Details`**: Diagnostic information used for error tracing (for example, correlation IDs).

This structure ensures predictable error handling across integration scenarios.

## Versioning and Update Behavior {#versioning-and-update-behavior}

Update operations rely on server-side validation to maintain payment instruction integrity.

* **How it works** : Clients must reference a valid `instruction_identification` when submitting updates.
* **Where it applies**: Cancellation-related payment status updates only.

Other payment attributes cannot be modified after submission.

## Environment and Security Note {#environment-and-security-note}

The Payment Initiation API enforces strict security controls for all operations.

* **Authentication**: OAuth 1.0a
* **Transport Security**: TLS
* **Payload Security**: Payment initiation requests are encrypted end-to-end.
* **Event Notifications**: Delivered via secure webhook endpoints.

These controls ensure confidentiality, integrity, and compliance for all payment data.