# Commercial Card Payment Acceptance source: https://developer.mastercard.com/payment-acceptance-api/documentation/tutorials-and-guides/card-pay-acceptance-tutorial/index.md ## Overview {#overview} This tutorial will show you the end-to-end flow of Mastercard commercial card payment acceptance in ISO20022 payment instructions format. #### What you will learn {#what-you-will-learn} * How to process a payment * How to update the status of the payment ## Before you start {#before-you-start} Before starting this tutorial, ensure that you have already completed the following: * Registered with Commercial Direct Payments (CDP) API Service. * Reviewed the payment initiation structure and remittance data structure required for the following 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-acceptance-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-acceptance-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 have successfully processed the end-to-end commercial card payment. ## Debtor Agent initiates card payment request {#debtor-agent-initiates-card-payment-request} There is no action required for the Creditor Agent at this step. This endpoint returns information relating to card payment initiated by a Debtor Agent. The sequence diagram describes the interaction between the Debtor Agent, CDP, and Creditor Agent for submitting and processing a card payment initiation request. Diagram step-1-mermaid 1. The Debtor Agent initiates a \[POST\] card payment initiation request. ## CDP validates payment initiation request {#cdp-validates-payment-initiation-request} CDP validates the payment initiation request against the Creditor's payment preferences. This is an optional validation step and is performed only if the Creditor Agent has configured payment preferences. Diagram step-2-mermaid 1. CDP validates the request against any Creditor Payment preferences. Tip: Refer to the [Creditor Payment Preference](https://developer.mastercard.com/payment-acceptance-api/documentation/use-cases/creditor-payment-controls/index.md) for details on how payment preferences work. 2. CDP generates the `instructionIdentification`. 3. CDP sends the payment status "RECEIVED/ACCEPTED/REJECTED". 4. CDP returns a 201 Created response containing the `instructionIdentification` with a status of RECEIVED. ## CDP sends payment notification to the Creditor Agent {#cdp-sends-payment-notification-to-the-creditor-agent} > There are two categories of Creditors, which are registered with the CDP API service for automated card payment initiation and processing: > > 1. Creditors onboarded by Creditor Agents > 2. Creditors accepting payments through Mastercard Gateway > > The Creditors, which are not part of the CDP service network, can receive payment initiation requests through CDP's email delivery. All the three flows are mentioned in the following diagram. ### CDP sends payment notification basis how the Creditor is set up with CDP {#cdp-sends-payment-notification-basis-how-the-creditor-is-set-up-with-cdp} 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. ## 1. CDP sends payment notification to the Creditor Agent to process the payment {#1-cdp-sends-payment-notification-to-the-creditor-agent-to-process-the-payment} Diagram submitenhancedcard4 1. CDP notifies the Creditor Agent by sending an encrypted CARD_PAYMENT_DETAILS_RECEIVED event with an ACCEPTED status. 2. The Creditor Agent acknowledges the notification with a 200 OK response. 3. The Creditor Agent proceeds to execute the card payment. ## 2. Review the sample event notification associated with this step {#2-review-the-sample-event-notification-associated-with-this-step} A JSON sample for the APPROVED status looks like: * JSON ```JSON { "body": { "eventId": "b1dfe836-669b-4320-9772-040aafcf4b6e", "eventType": "ISO_CARD_PAYMENT_DETAILS_RECEIVED", "eventCreatedDate": "2026-01-20T19:53:21.161Z", "data": { "paymentInformation": { "paymentInformationIdentification": "WJTKWNBMKI1TNK9HJXNNBK2ZIXCUB7UI", "paymentMethod": "CARD", "requestedExecutionDate": "2026-01-20", "debtor": { "name": "Morgan_LLP_BusinessIRQYh", "postalAddress": { "streetName": "2200 Mastercard Blvd.", "postalCode": "63368", "townName": "O'Fallon", "countrySubDivision": "MO", "country": "US" }, "identification": { "organisationIdentification": { "anyBIC": "7OZBBAAX", "lei": "81G1IF550C4PM62Z6075", "other": [ { "identification": "2133444799", "schemeName": { "code": "BANK" } }, { "identification": "2133444324", "schemeName": { "code": "CBID" } }, { "identification": "2133444790", "schemeName": { "code": "DUNS" } }, { "identification": "2133444323", "schemeName": { "code": "COID" } }, { "identification": "991165432", "schemeName": { "code": "TXID" } }, { "identification": "775645890", "schemeName": { "code": "CUST" } }, { "identification": "midc.electronics.pay@cps", "issuer": "Morgan_LLP_Business", "schemeName": { "code": "PRID" } } ] } } }, "debtorAccount": { "identification": { "other": [ { "identification": "1118", "schemeName": { "code": "AIIN" }, "issuer": "Morgan_LLP_Business" } ] }, "type": { "code": "CARD" }, "currency": "USD", "name": "Morgan_LLP_Business" }, "creditTransferTransactionInformation": { "paymentIdentification": { "instructionIdentification": "ea6cb4d1-0d06-41e7-9a09-6a2d3c92bcde", "endToEndIdentification": "CERFPXWZENRBIV0K98YZBFMVEGQB4XF2201", "uetr": "365a1be6-9a84-4508-be1b-f8e8e3ac5941" }, "amount": { "instructedAmount": { "currency": "USD", "amount": 10 } }, "exchangeRateInformation": { "unitCurrency": "USD", "exchangeRate": 0.88, "rateType": "AGRD", "contractIdentification": "sdter-ior-7858" }, "chargeBearer": "DEBT", "tax": { "totalTaxAmount": { "currency": "USD", "amount": 40 } } } }, "createdDate": "2026-01-20T19:53:21.132Z", "updatedDate": "2026-01-20T19:53:21.132Z", "paymentStatus": { "status": "PENDING", "statusReasonInformation": [] } } }, "id": 46780, "postedDate": "2026-01-20T19:53:21.311+00:00", "_id": 19945807392544, "_revision": 1, "_modified": 1768938801311 } ``` ## CDP notifies Debtor Agent on Creditor Agent acknowledgment {#cdp-notifies-debtor-agent-on-creditor-agent-acknowledgment} There is no action required for the Creditor Agent at this step. Diagram step-4-mermaid 1. CDP sends a payment status notification with SUBMITTED status to the Debtor Agent. 2. The Debtor Agent acknowledges the notification by returning a 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 ## Creditor Agent processes and sends the card payment authorization status to CDP {#creditor-agent-processes-and-sends-the-card-payment-authorization-status-to-cdp} ### 1. The Creditor Agent processes and sends the card payment authorization status to CDP {#1-the-creditor-agent-processes-and-sends-the-card-payment-authorization-status-to-cdp} Diagram step-5-mermaid 1. The Creditor Agent submits a \[PUT\] request to update the card payment status to APPROVED, DECLINED, or REJECTED. 2. CDP 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} A JSON sample for the APPROVED status looks like: * JSON ```JSON { "status": "APPROVED", "transactionIdentification": { "approvalCode": "aprCd123", "retrievalReferenceNumber": "ref-123", "transactionDateTime": "2024-08-17T17:37:23.230Z", "transactionReference": "transc-ref-123" } } ```
A JSON sample for the DECLINED status looks like: * JSON ```JSON { "status": "DECLINED", "statusReasonInformation": [ { "reasonCode": "INSUFFICIENT_FUNDS", "description": "Transaction has failed due to insufficient funds." } ] } ``` A JSON sample for the REJECTED status looks like: * JSON ```JSON { "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "INVALID_INVOICE_DATA", "description": "Transaction is rejected. One or more invoices include information that creates a reconciliation mismatch for the accepting Creditor Agent." } ] } ``` ### 3. Review the status codes and reason codes associated with this request. {#3-review-the-status-codes-and-reason-codes-associated-with-this-request} | Status | Description | Usage | |----------|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | APPROVED | Payment initiation is Approved by 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 Creditor Agent | This status is updated by the Creditor Agent when the payment initiation is processed by their payment gateway. | | REJECTED | Payment initiation is rejected by the Creditor Agent. | The Creditor Agent can reject the payment initiation with one of the reason codes below if any data validation error or failure occurs. | If the payment initiation status is `DECLINED`, you will receive the applicable reason codes. For more details, refer to the [Payment Declined Request Error Codes](https://developer.mastercard.com/payment-acceptance-api/documentation/code-and-formats/index.md#payment-declined-request-error-codes). If the payment initiation status is `REJECTED`, you will receive the applicable reason codes. For more details, refer to the [Payment Rejected Request Error Codes](https://developer.mastercard.com/payment-acceptance-api/documentation/code-and-formats/index.md#payment-rejected-request-error-codes). ## CDP sends the payment status update to the Debtor Agent {#cdp-sends-the-payment-status-update-to-the-debtor-agent} There is no action required for the Creditor Agent at this step. 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 acknowledges the notification by returning a 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 ## Creditor Agent reconciles and updates payment initiation request {#creditor-agent-reconciles-and-updates-payment-initiation-request} ### 1. The Creditor Agent reconciles the payment and updates the status to SETTLED {#1-the-creditor-agent-reconciles-the-payment-and-updates-the-status-to-settled} Diagram step-7-mermaid 1. The Creditor Agent sends the reconciliation status as SETTLED to CDP. 2. CDP acknowledges the update by returning a 200 OK response. ### 2. Review the sample event notification associated with this step. {#2-review-the-sample-event-notification-associated-with-this-step-2} A JSON sample for the SETTLED status looks like: * JSON ```JSON { "status": "SETTLED", "settlementTimeIndication": { "creditDateTime": "2024-08-17T17:37:23.230Z", "debitDateTime": "2024-08-17T17:37:23.230Z" } } ```
### 3. Review the status code associated with this request. {#3-review-the-status-code-associated-with-this-request} #### Update status codes {#update-status-codes} | Status code | Description | Usage | |-------------|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | SETTLED | Payment initiation marked Settled by Creditor Agent. | This status is updated by the Creditor Agent when the funds have been received and reconciled by the Creditor Agent. | ## CDP sends the reconciliation payment status to the Debtor Agent {#cdp-sends-the-reconciliation-payment-status-to-the-debtor-agent} There is no action required for the Creditor Agent at this step. Diagram step-8-mermaid 1. CDP sends a payment instruction reconciliation status notification with SETTLED status to the Debtor Agent. 2. The Debtor Agent acknowledges the notification by returning a 200 OK response.