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

## Overview {#overview}

The Payment Acceptance API uses a set of core data objects to support creditor onboarding, payment processing, status updates, and event-driven notifications for commercial card payments processed under ISO 20022 standards.

## Payment Instructions {#payment-instructions}

Payment instructions represent commercial card payment transactions submitted through Commercial Direct Payments (CDP) and processed by Creditor Agents.

* **`instruction_identification`**: A unique UUID identifying each payment instruction.
* **`status`** : Current lifecycle state of the payment instruction. Supported values include: `APPROVED`, `DECLINED`, `REJECTED`, `SETTLED`, `CANCELLATION_ACCEPTED`, and `CANCELLATION_REJECTED`.
* **`ica`**: Interbank Card Association (ICA) identifier of the Creditor Agent submitting or managing the payment instruction.

These attributes are used when updating or retrieving payment instruction status through the Payment Status Update and Status Inquiry operations.

## Creditors {#creditors}

Creditors represent suppliers registered in the CDP Supplier Directory.

* **`creditorId`**: A system-generated UUID that uniquely identifies a creditor registration.
* **`legal_business_name`**: Legal name of the creditor organization.
* **`dba`**: Doing Business As name used by the creditor.
* **`is_active`**: Boolean value indicating whether the creditor is active in CDP.

Creditor records are created, retrieved, updated, and deleted using Creditor Registration endpoints.

## Creditor Profiles {#creditor-profiles}

Creditor profiles define how a registered creditor can receive payments.

* **`creditor_profile_id`**: A unique identifier created by the Creditor Agent to represent a creditor payment profile.
* **`creditorId`**: Reference to the parent creditor registration.
* **`ica`**: ICA of the Creditor Agent managing the profile.

Each creditor can have one or more profiles to support different payment configurations.

## Creditor Payment Controls {#creditor-payment-controls}

Payment controls define rules that govern how payments are processed for a creditor profile.

* **`payment_control_id`**: Unique identifier for a specific payment control.
* **`creditor_profile_id`**: Reference to the creditor profile to which the control applies.
* **`control_attributes`**: Payment rule configuration (such as limits or eligibility criteria) as defined in the payment control schema.

Payment controls support creation, retrieval, update, and deletion operations.

## Debtors {#debtors}

Debtors represent buyers initiating commercial card payments.

* **`debtor_profile_id`**: A unique identifier created by the Debtor Agent to identify a debtor profile.
* **`debtor_details`**: Debtor information returned when retrieving debtor records.

Debtor data is read-only within the Payment Acceptance API and is retrieved to support payment context.

## Event Notifications {#event-notifications}

Event notifications deliver asynchronous updates related to payment instructions.

* **`eventId`**: Unique identifier for the notification event.
* **`eventType`** : Identifies the type of event. Supported values include:
  * `ISO_CARD_PAYMENT_DETAILS_RECEIVED`
  * `PAYMENT_CANCELLATION_REQUESTED`
  * `PAYMENT_CANCELLED`
* **`eventCreatedDate`**: Timestamp indicating when the event was generated.
* **`data`** : Event-specific payload. The schema varies by `eventType` and includes payment instruction or status details.

Event notifications are delivered to Creditor Agent webhook endpoints using mutual TLS (mTLS).

## Error Handling {#error-handling}

Error responses follow a standard structure across all endpoints.

* **`Source`**: Identifies the service where the error occurred.
* **`ReasonCode`**: Machine-readable code identifying the error condition.
* **`Description`**: Human-readable explanation of the error.
* **`Recoverable`**: Boolean indicating whether the request can be retried.
* **`Details`**: Diagnostic information, such as correlation identifiers for tracing.

This standardized structure enables consistent error handling and troubleshooting across integrations.

## Versioning and Concurrency {#versioning-and-concurrency}

Update operations that modify existing resources rely on server-side validation to prevent conflicting updates.

* **How it works**: Clients must retrieve the latest resource state before submitting an update request.
* **Where it applies**: Commonly used for updating payment instruction status, creditor records, profiles, and payment controls.

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

All API operations require secure authentication and transport security.

* **Authentication**: OAuth 1.0a
* **Transport Security**: TLS
* **Event Notifications**: Secured using mutual TLS (mTLS)

These mechanisms ensure confidentiality, integrity, and non-repudiation for all commercial payment data.