# Commercial Card Payment Initiation
source: https://developer.mastercard.com/payment-initiation-api/documentation/tutorials-and-guides/card-pay-initiation-tutorial/index.md

## Overview {#overview}

This tutorial walks you through the end‑to‑end flow of Mastercard commercial card payment initiation using the ISO 20022 payment initiation format. You will learn how to create a card payment initiation request and understand how Commercial Direct Payments (CDP) processes the request from submission through completion.
>
> #### What you will learn {#what-you-will-learn}
>
> In this tutorial, you will learn how to:
>
> * Initiate a commercial card payment using the Payment Initiation API.

## Before you start {#before-you-start}

Before beginning this tutorial, ensure that you have completed the following prerequisites:

* Registered for the Payment Initiation API service
* Reviewed the required payment initiation and remittance data structures for the request payload

#### Payment initiation structure {#payment-initiation-structure}

![Hierarchical diagram of the Payment Initiation structure, showing fields including Debtor and Creditor Information, Payment Method, Amounts, Execution Date, Charge Bearer, Supplementary Data with Card and Charges details, and Remittance Information with related, unstructured, and structured remittance elements.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/pay-initiation-3.png "Payment Instruction Flow")

#### Remittance data structure {#remittance-data-structure}

![Hierarchical diagram of the Remittance Information structure showing Structured remittance fields, Referred Document Information and its subfields, monetary amounts, adjustments, creditor references, and additional remittance information.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/pay-initiation-4.png "Remittance Information Flow")

## What you will achieve {#what-you-will-achieve}

By the end of this tutorial, you will:

* Successfully create a card payment initiation request in ISO 20022 format.
* Understand the end‑to‑end payment flow after CDP receives a payment initiation request.

#### Click Next {#click-next}

## Debtor Agent initiates a card payment request {#debtor-agent-initiates-a-card-payment-request}

This endpoint returns information related to a card payment initiated by a Debtor Agent. The sequence diagram illustrates the interaction between the Debtor Agent, CDP, and the Creditor Agent for submitting and processing a card payment initiation request.   
Note: Steps 1, 2, 4, 6, and 8 apply to the Debtor Agent for submitting the payment initiation request and receiving payment status updates. Diagram step-1-mermaid

1. The Debtor Agent initiates a card payment request.
   API Reference: `POST /debtor-agents/{ica}/payment-initiations`

2. CDP validates the request.
3. CDP generates the `instructionIdentification`.
4. CDP returns a 201 Created response containing the `instructionIdentification` with a status of RECEIVED.

## 1. Review the payment initiation structure. {#1-review-the-payment-initiation-structure}

Before submitting a payment initiation request, review the payment initiation and remittance structures, including the instructed amount and remitted amount fields.

![Instructed and Remitted Amount Information Flow](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/instructedamount.png "Instructed and Remitted Amount Information Flow")

## 2. Create the payment initiation request. {#2-create-the-payment-initiation-request}

Note: The example JSON shows the payment method `CARD`. Alert: The Mastercard‑assigned ICA is used for agent identification in all core service requests. A Customer Service Provider may transact on behalf of a customer by including the customer's ICA in the request. Direct payment agents may continue to transact using their own ICA when submitting transactions to CDP.
API Reference: `POST /debtor-agents/{ica}/payment-initiations`

If the Debtor Agent includes a value for the `requestedExecutionDate` field, the payment initiation is treated as a future‑dated payment. The Creditor Agent must be enabled for future‑dated payments for the request to proceed.

## 3. Review the status and error codes associated with this request. {#3-review-the-status-and-error-codes-associated-with-this-request}

After submitting the payment initiation request, CDP returns the following status:

|  Status  |           Description            |                                          Usage                                          |
|----------|----------------------------------|-----------------------------------------------------------------------------------------|
| RECEIVED | Payment instruction is received. | This is a status of the Debtor Agent will receive in the response of a payment request. |

When you submit a card payment initiation request, you may receive one or more of the applicable error codes.
For more details, refer to the [Payment Initiation Response Error Codes](https://developer.mastercard.com/payment-initiation-api/documentation/code-and-formats/index.md#payment-initiation-response-error-codes).

#### Click Next {#click-next-1}

## CDP validates payment initiation request {#cdp-validates-payment-initiation-request}

### 1. CDP validates the payment initiation against the Creditor payment preferences (This is an optional check, happens only if the Creditor Agent opts for this.) {#1-cdp-validates-the-payment-initiation-against-the-creditor-payment-preferences-this-is-an-optional-check-happens-only-if-the-creditor-agent-opts-for-this}

There is no action required for the Debtor Agent at this step, however, if the payment initiation request is rejected, then the Debtor Agent receives a status back with the reason code and reason description.
Diagram step-2-mermaid

1. CDP validates the payment request against the Creditor payment controls and creates the `instructionIdentification`.
2. CDP sends the payment status (RECEIVED, ACCEPTED, or REJECTED) to the Debtor Agent.
3. The Debtor Agent returns a 200 OK success response.

#### Creditor payment preferences {#creditor-payment-preferences}

Creditor Agents may optionally configure Creditor payment preferences. Debtor Agents must ensure that submitted payment requests comply with these preferences. CDP validates the following preference types when this feature is enabled:

* **Time preferences:** Limit the duration within which payments can be accepted between a Debtor and a Creditor.
* **Relationship preferences:** Restrict how Debtors are permitted to pay a Creditor.
* **Amount preferences:** Restrict payments based on the total instructed amount.
* **Fee references:** Specify additional fees required when submitting a payment.

### 2. Review the sample status response associated with this step. {#2-review-the-sample-status-response-associated-with-this-step}

If the payment initiation complies with the Creditor's payment preferences, CDP returns an ACCEPTED status. A sample response looks like:
* JSON

```JSON
{
  "transactionId": "59aff05a-3d11-42e3-8f1e-230a0ed182d3",
  "paymentStatus": {
    "status": "ACCEPTED"
  },
  "createdDate": "2024-09-18T10:25:13.37Z"
}
```

Note: If the payment initiation does not follow the Creditor's payment preferences, you will receive a warning or rejection. If a warning message is received, the system still processes the payment.

A sample response for the ACCEPTED status with a warning for payment preference looks like:
* JSON

```JSON
{
  "transactionId": "7b07757c-8e36-419e-a7da-25dae4f37e84",
  "paymentStatus": {
    "status": "ACCEPTED",
    "statusReasonInformation": [
      {
        "description": "This transaction is in transit. 0001.penCreditor01@cdp flags all CARD transactions that exceed the maximum instructed amount allowed by the Creditor. The transaction will be reviewed by the Creditor for acceptance and the status updated accordingly.",
        "reasonCode": "MAX_INSTRUCTED_AMT_WARNING"
      }
    ]
  },
  "createdDate": "2024-09-18T10:17:05.003Z"
}
```

If the payment initiation does not conflict with the Creditor's payment preferences, you will receive a status listed as REJECTED. A sample response looks like:
* JSON

```JSON
{
  "transactionId": "a809d396-cd87-41be-893f-93ab49b5a7d5",
  "paymentStatus": {
    "status": "REJECTED",
    "statusReasonInformation": [
      {
        "description": "Transaction rejected. The transaction instructed amount exceeds the maximum allowed via CARD by this Creditor.",
        "reasonCode": "MAX_INSTRUCTED_AMT_REJECTED"
      }
    ]
  },
  "createdDate": "2024-09-18T10:23:40.009Z"
}
```

### 3. Review the status and error codes associated with this step. {#3-review-the-status-and-error-codes-associated-with-this-step}

#### Authorization status codes {#authorization-status-codes}

|  Status  |                            Description                            |                                           Usage                                           |
|----------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| ACCEPTED | Payment initiation is accepted by the Commercial Direct Payments. | This is a status that the Debtor Agent will receive in the response of a payment request. |
| REJECTED | Payment initiation is rejected by the Commercial Direct Payments. | This is a status that the Debtor Agent will receive in the response of a payment request. |

If you submit payment instructions that violate the Creditor's payment preferences, you will receive the applicable warning or rejection message codes.
For more details, refer to the [Payment Preference Request Error Codes](https://developer.mastercard.com/payment-initiation-api/documentation/code-and-formats/index.md#payment-preference-request-error-codes).
Note: The warning messages do not affect the payment flow. If a warning message is received, the system still processes the payment.

#### Click Next {#click-next-2}

## CDP sends payment notification on how the Creditor is set up {#cdp-sends-payment-notification-on-how-the-creditor-is-set-up}

> There are two categories of Creditors registered with the Payment Initiation API service for automated card payment initiation and processing:
>
> 1. Creditors onboarded by Creditor Agents
> 2. Creditors accepting payments through Mastercard Gateway
>
> Creditors that are not registered with the CDP service network can still receive payment initiation requests through CDP email delivery. All the three flows are mentioned in the following diagram.
Diagram step-3-mermaid

#### Scenario 1: Creditor is set up to pay through Creditor Agent {#scenario-1-creditor-is-set-up-to-pay-through-creditor-agent}

1. CDP sends the payment notification to the Creditor Agent through a POST call with an encrypted payment payload.
2. The Creditor Agent acknowledges receipt of the payment notification.

#### Scenario 2: Creditor is set up to pay through Mastercard Gateway {#scenario-2-creditor-is-set-up-to-pay-through-mastercard-gateway}

3. CDP sends the payment notification to the Mastercard Gateway through a POST call with an encrypted payment payload.
4. Mastercard Gateway acknowledges the payment request.

#### Scenario 3: Email payment when Creditor is not registered with the CDP {#scenario-3-email-payment-when-creditor-is-not-registered-with-the-cdp}

5. CDP sends an encrypted payment notification to the Mastercard Email Service.
6. The Email Service returns a confirmation indicating successful email delivery.

Note: To see information about possible errors that can be returned from the service, refer to the [Payment Initiation Response Error Codes](https://developer.mastercard.com/payment-initiation-api/documentation/code-and-formats/index.md#payment-initiation-response-error-codes).

#### Click Next {#click-next-3}

## CDP notifies Debtor Agent when Creditor Agent acknowledges payment initiation request {#cdp-notifies-debtor-agent-when-creditor-agent-acknowledges-payment-initiation-request}

### 1. CDP sends a payment status update to the Debtor Agent once the Creditor Agent acknowledges the payment initiation notification {#1-cdp-sends-a-payment-status-update-to-the-debtor-agent-once-the-creditor-agent-acknowledges-the-payment-initiation-notification}

There is no action required from the Debtor Agent at this stage. However, the Debtor Agent receives an event notification containing the current status of the payment initiation request.
Diagram step-4-mermaid

1. CDP sends a payment status notification with SUBMITTED status to the Debtor Agent.
2. The Debtor Agent returns a 200 OK success response.

Note: The similar flow is applicable when you have:

* Creditors accepting payments through Mastercard Gateway
* Payment initiation requests through CDP email delivery

### 2. Review the sample event notification associated with this step. {#2-review-the-sample-event-notification-associated-with-this-step}

When the Creditor Agent acknowledges the payment initiation notification, CDP sends an event notification to the Debtor Agent with the corresponding payment status. This looks like:
* JSON

```JSON
{
  "body": {
    "eventId": "17a7ae11-0683-43a6-8ead-aadf9ecd171d",
    "eventType": "CARD_PAYMENT_STATUS_UPDATED",
    "eventCreatedDate": "2024-09-18T06:57:54.496Z",
    "data": {
      "transactionId": "5bce0daf-e021-49b8-8176-2808b8fdf827",
      "paymentMethod": "CARD",
      "createdDate": "2024-09-18T06:57:54.081Z",
      "updatedDate": "2024-09-18T06:57:54.480Z",
      "status": "SUBMITTED",
      "endToEndId": "f91bceb3-7331-4ae3-b916-5af49fc74"
    }
  }
}
```

### 3. Review the status code associated with this request. {#3-review-the-status-code-associated-with-this-request}

#### Status update code from CDP {#status-update-code-from-cdp}

When the Creditor Agent updates the payment initiation status, Commercial Direct Payments (CDP) sends a payment status update to the Debtor Agent.
The following status update codes may be returned by CDP at this stage:

|  Status   |                      Description                       |                                                Usage                                                 |
|-----------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| SUBMITTED | Payment initiation is submitted to the Creditor Agent. | CDP sends this status to the Debtor Agent when the payment initiation is sent to the Creditor Agent. |

#### Click Next {#click-next-4}

## The Creditor Agent sends the card payment authorization status to CDP {#the-creditor-agent-sends-the-card-payment-authorization-status-to-cdp}

There is no action required for the Debtor Agent at this step.
Diagram step-5-mermaid

1. The Creditor Agent sends a PUT request to CDP to update the card payment status to APPROVED, DECLINED, or REJECTED.
2. CDP returns 200 OK response.

Note: The similar flow is applicable when you have:

* Creditors accepting payments through Mastercard Gateway
* Payment initiation requests through CDP's email delivery

#### Click Next {#click-next-5}

## CDP notifies Debtor Agent of authorization {#cdp-notifies-debtor-agent-of-authorization}

### 1. CDP sends the payment status update to the Debtor Agent {#1-cdp-sends-the-payment-status-update-to-the-debtor-agent}

Diagram step-6-mermaid

1. CDP sends a CARD_PAYMENT_STATUS_UPDATED event notification with APPROVED, DECLINED, or REJECTED status to the Debtor Agent.
2. The Debtor Agent sends a 200 OK success response.

Note: The similar flow is applicable when you have:

* Creditors accepting payments through Mastercard Gateway
* Payment initiation requests through CDP's email delivery

### 2. Review the sample event notifications associated with this step. {#2-review-the-sample-event-notifications-associated-with-this-step}

CDP sends the Debtor Agent an event notification when the status is updated by the Creditor Agent. This event notification looks like:
* JSON

```JSON
{
  "body": {
    "eventId": "46a79f4a-a440-40cc-bfce-70884268d699",
    "eventType": "CARD_PAYMENT_STATUS_UPDATED",
    "eventCreatedDate": "2024-09-18T07:01:53.703Z",
    "data": {
      "transactionId": "5bce0daf-e021-49b8-8176-2808b8fdf827",
      "paymentMethod": "CARD",
      "createdDate": "2024-09-18T06:57:54.081Z",
      "updatedDate": "2024-09-18T07:01:53.692Z",
      "status": "APPROVED",
      "endToEndId": "f91bceb3-7331-4ae3-b916-5af49fc74",
      "transactionIdentification": {
        "approvalCode": "214666",
        "retrievalReferenceNumber": "54946469666",
        "transactionReference": "4494944994949",
        "transactionDateTime": "2024-09-18T06:57:54.081Z"
      }
    }
  }
}
```

A declined status event notification looks like:
* JSON

```JSON
{
  "body": {
    "eventId": "f009846f-be71-4e0d-8b72-624ab5eac006",
    "eventType": "CARD_PAYMENT_STATUS_UPDATED",
    "eventCreatedDate": "2024-09-18T06:53:09.074Z",
    "data": {
      "transactionId": "e6c0cc62-4476-4877-b9d0-c5b055f583c7",
      "paymentMethod": "CARD",
      "createdDate": "2024-09-18T06:51:52.886Z",
      "updatedDate": "2024-09-18T06:53:09.059Z",
      "status": "DECLINED",
      "statusReasonInformation": [
        {
          "reasonCode": "INSUFFICIENT_FUNDS",
          "description": "Transaction e6c0cc62-4476-4877-b9d0-c5b055f583c7 has failed, due to insufficient funds"
        }
      ],
      "endToEndId": "f91bceb3-7331-4ae3-b916-5af49fc74"
    }
  }
}
```

A rejected status event notification looks like:
* JSON

```JSON
{
  "transactionId": "a809d396-cd87-41be-893f-93ab49b5a7d5",
  "paymentStatus": {
    "status": "REJECTED",
    "statusReasonInformation": [
      {
        "description": "Transaction rejected. The transaction instructed amount exceeds the maximum allowed via CARD by this Creditor.",
        "reasonCode": "MAX_INSTRUCTED_AMT_REJECTED"
      }
    ]
  },
  "createdDate": "2024-09-18T10:23:40.009Z"
}
```

### 3. Review the status and error codes associated with this step. {#3-review-the-status-and-error-codes-associated-with-this-step-1}

#### Status update codes from CDP {#status-update-codes-from-cdp}

When a Creditor Agent updates the payment status, you will receive one of the following payment status update codes from the CDP:

|  Status  |                      Description                      |                                                                    Usage                                                                     |
|----------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| REJECTED | Payment initiation is rejected by the Creditor Agent. | The Creditor Agent can reject the payment initiation with one of the following reason codes, if any data validation error or failure occurs. |
| APPROVED | Payment initiation is approved by the Creditor Agent  | This status is updated by the Creditor Agent when the payment initiation is processed by their payment gateway.                              |
| DECLINED | Payment initiation is declined by the Creditor Agent. | This status is updated by the Creditor Agent when the payment initiation is processed by their payment gateway.                              |

If the Creditor Agent updates the payment status to `DECLINED` or `REJECTED`, CDP returns one of the applicable reason codes.
For more details, refer to the [Payment Rejected and Payment Declined Request Error Codes](https://developer.mastercard.com/payment-initiation-api/documentation/code-and-formats/index.md#payment-rejected-and-payment-declined-request-error-codes).

#### Click Next {#click-next-6}

## Creditor Agent reconciles and updates payment initiation request {#creditor-agent-reconciles-and-updates-payment-initiation-request}

There is no action required for the Debtor Agent at this step.
Diagram step-7-mermaid

1. The Creditor Agent reconciles the payment and updates the status to SETTLED.
2. CDP sends \[200\] success response.

Note: The similar flow is applicable when you have:

* Creditors accepting payments through Mastercard Gateway
* Payment initiation requests through CDP's email delivery

#### Click Next {#click-next-7}

## CDP notifies Debtor Agent of reconciliation status {#cdp-notifies-debtor-agent-of-reconciliation-status}

### 1. CDP sends the reconciliation payment status to the Debtor Agent {#1-cdp-sends-the-reconciliation-payment-status-to-the-debtor-agent}

Diagram step-8-mermaid

1. CDP sends a payment instruction reconciliation status notification with SETTLED status to the Debtor Agent.
2. The Debtor Agent returns a 200 OK success response.

Note: The similar flow is applicable when you have:

* Creditors accepting payments through Mastercard Gateway
* Payment initiation requests through CDP's email delivery

### 2. Review the sample event notification associated with this step. {#2-review-the-sample-event-notification-associated-with-this-step-1}

CDP notifies the Debtor Agent with an event notification when the payment initiation is reconciled by the Creditor Agent. This event notification looks like:
* JSON

```JSON
{
  "body": {
    "eventId": "6539f7a5-704d-41a5-b639-21857a9b7028",
    "eventType": "CARD_PAYMENT_STATUS_UPDATED",
    "eventCreatedDate": "2024-09-18T07:05:11.490Z",
    "data": {
      "transactionId": "5bce0daf-e021-49b8-8176-2808b8fdf827",
      "paymentMethod": "CARD",
      "createdDate": "2024-09-18T06:57:54.081Z",
      "updatedDate": "2024-09-18T07:05:11.477Z",
      "status": "SETTLED",
      "endToEndId": "f91bceb3-7331-4ae3-b916-5af49fc74"
    }
  }
}
```

### 3. Review the status codes associated with this step. {#3-review-the-status-codes-associated-with-this-step}

When a Creditor Agent updates the payment initiation status, you may receive the following payment status update code from CDP:

| Status  |                       Description                       |                                                        Usage                                                         |
|---------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| SETTLED | Payment initiation marked settled by the Creditor Agent | This status is updated by the Creditor Agent when the funds have been received and reconciled by the Creditor Agent. |