# Card payment instruction source: https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/card-tutorial/index.md ## Overview {#overview} This tutorial will show you the end-to-end flow of a card payment instruction. > > #### What you will learn {#what-you-will-learn} > > * How to initiate a payment instruction > * How to add card details to a payment instruction > * How to update the status of the payment instruction ## Before you start {#before-you-start} Before starting this tutorial, ensure that you have already completed the following: * Registered with Mastercard Track Business Payment Service * Reviewed the payment instruction structure and remittance data structure required for the payload below #### Payment instruction structure {#payment-instruction-structure} ![alt text](https://static.developer.mastercard.com/content/mastercard-supplier-payment-agent/uploads/paymentinstruction.png "Payment Instruction Flow") #### Remittance data structure {#remittance-data-structure} ![alt text](https://static.developer.mastercard.com/content/mastercard-supplier-payment-agent/uploads/remittanceinformation.png "Remittance Information Flow") ## What you will achieve {#what-you-will-achieve} At the end of this tutorial you will successfully create and process a card payment instruction from end-to-end. ## Next steps {#next-steps} Click **Next** to get started. ## The Buyer Payment Agent initiates the payment instruction request {#the-buyer-payment-agent-initiates-the-payment-instruction-request} There is no action required for the Supplier Payment Agent at this step. However, the Buyer Payment Agent can indicate that the payment instruction should proceed as a future dated payment by including a value for the `requestedExecutionDate` field. The Supplier Payment Agent must be enabled for future dated payments in order for the payment instruction to proceed as a future dated payment. Contact your Mastercard representative to enable future dated payments. Diagram submitenhancedcard1 #### Click Next. {#click-next} ## Business Payment Service validates the payment instruction against the Supplier payment preferences {#business-payment-service-validates-the-payment-instruction-against-the-supplier-payment-preferences} If the payment instruction is rejected, then Business Payment Service sends the CARD_PAYMENT_STATUS_UPDATED notification to the Buyer Payment Agent. There is no action required for the Supplier Payment Agent at this step. Diagram submitenhancedcard2 #### Click Next. {#click-next-1} ## The Buyer Payment Agent updates the payment instruction with encrypted card details {#the-buyer-payment-agent-updates-the-payment-instruction-with-encrypted-card-details} There is no action required for the Supplier Payment Agent at this step. Diagram submitenhancedcard3 #### Click Next. {#click-next-2} ## Business Payment Service sends the payment instruction with the encrypted card details to the Supplier Payment Agent to process the payment {#business-payment-service-sends-the-payment-instruction-with-the-encrypted-card-details-to-the-supplier-payment-agent-to-process-the-payment} Diagram submitenhancedcard4 ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step} You should receive an event notification with the payment instruction and encrypted card data once the payment instruction is created by the Buyer Payment Agent. An example event notification for this step looks like: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "CARD_PAYMENT_DETAILS_RECEIVED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "buyerId": "contoso.corp.pay@track", "supplierId": "acme.east@track", "paymentMethod": "CARD", "instructedAmount": { "amount": 2200.5, "currency": "USD" }, "chargeBearer": "BUYR", "chargesInformation": [ { "amount": 100, "type": "CARD_FEE" } ], "tax": { "totalTaxAmount": 200.5 }, "remittanceInformation": { "structured": [ { "referredDocumentInformation": [ { "number": "3521264364", "type": "CINV", "relatedDate": "2020-07-16", "paymentDueDate": "2020-08-16", "lineDetails": [ { "identifications": [ { "number": "5489549615", "type": { "code": "ASNB", "proprietary": "" }, "relatedDate": "2020-06-20" } ], "quantity": 1, "unitofMeasure": "EA", "description": "Sample Item", "amount": { "duePayableAmount": 3000, "discountAppliedAmounts": [ { "type": { "code": "TDMS", "proprietary": "" }, "amount": 500 } ], "taxAmounts": [ { "type": { "code": "STAT", "proprietary": "" }, "amount": 200.5 } ], "adjustmentAmountsandReasons": [ { "amount": 100, "creditDebitIndicator": "DBIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 2100.5 } } ], "referredDocumentAmount": { "duePayableAmount": 3000, "discountAppliedAmounts": [ { "type": { "code": "TMDS", "proprietary": "" }, "amount": 500 } ], "taxAmounts": [ { "type": { "code": "STAT", "proprietary": "" }, "amount": 200.5 } ], "adjustmentAmountsandReasons": [ { "amount": 100, "creditDebitIndicator": "DBIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 2100.5 } } ], "supplierReferenceInformation": { "type": { "code": "SCOR", "proprietary": "" }, "issuer": "ISO", "reference": "RF18 5390 0754 7034" }, "Invoicer": { "Name": "ACME Inc.", "organisationIdentification": [ { "Identification": "82-2981873", "type": "TXID" } ] }, "Invoicee": { "Name": "Contoso Inc.", "OrganisationIdentification": [ { "Identification": "02-0794278", "type": "TXID" } ] }, "additionalRemittanceInformation": [ "Data1:abc", "Data2:xyz", "Data3:lmn", "DataN:nnn" ] }, { "referredDocumentInformation": [ { "number": "3521264364", "type": "CREN", "relatedDate": "2020-07-16", "paymentDueDate": "2020-08-16", "lineDetails": [ { "identifications": [ { "number": "5489549615", "type": { "code": "ASNB", "proprietary": "" }, "relatedDate": "2020-06-20" } ], "amount": { "creditNoteAmount": 500 } } ], "referredDocumentAmount": { "creditNoteAmount": 500 } } ], "supplierReferenceInformation": { "type": { "code": "SCOR", "proprietary": "" }, "issuer": "ISO", "reference": "RF18 5390 0754 7034" }, "Invoicer": { "name": "ACME Inc.", "organisationIdentifications": [ { "identification": "82-2981873", "type": "TXID" } ] }, "Invoicee": { "name": "Contoso Inc.", "organisationIdentifications": [ { "identification": "02-0794278", "type": "TXID" } ] }, "additionalRemittanceInformation": [ "Data1:abc", "Data2:xyz", "Data3:lmn", "DataN:nnn" ] } ] }, "encryptedCard": { "encryptedKey": "kbxvW4kMiUT1fZITZ/30IHFY9iq7Az+AclsaJKVHe8e9hJ2id+9s39wsNs3xPMSMenhOITA+ti+QKl3t70DC3aA6tLSisUJEigFN4NfukXasWTa2F6yBmDUVGYps1VW930/dlYuWBV1PkE9Gdpozft5NPk23grDRYIICm+yM5hriU2G0Wlag6IRyCiHsKqX01qndIPCINNbgrXFqE7ZmAg+S9Vs+yQC2kd01lb7RnZHmUpRbHnBl3SKu9flmbgdPPmd0PwWyzxAMfhoQqENk7BqC4lUojf/UfHjfMeoI/d1Qh6NYmMf9sjj9SBDiFVfDIVw56U9CtrsVUgbSVV9r4Q==", "encryptedValue": "GWe+JReXeS0rRyTYRQLQosLGPjzwu4KgzrUil8NeimVx2GlPMokImFKgyMRzajNVWKfceGedyTJKAz2guODI1ZrL2Um2HLY4FYhj4IloBNnqFZE4wOTFw26iz9+pGPK0w6aQYkIkYaEOELQ8WfPxud8QUVc6pqwjsTarmsb+BLcfDvkkUiPL6NZd4YgahR8k", "iv": "y4Fjzs9W7Mo7dYjU7o85ng==", "publicKeyFingerprint": "70632bc104e31f204fdc59f9e40fb3f1c84f4938699e475abcefdd6b293888ed", "oaepPaddingDigestAlgorithm": "SHA256" }, "paymentStatus": { "status": "PENDING", "statusReasonInformation": [ { "reasonCode": "AMT_GRT_WARN", "description": "Transaction has been flagged. The payment amount exceeds the maximum allowed by this Supplier" } ] } } } ``` ## 2. Review the error codes associated with this step. {#2-review-the-error-codes-associated-with-this-step} You will receive an event notification indicating the status of the payment instruction. | Status | Description | Usage | |-----------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ACCEPTED | Payment instruction is Accepted by Business Payment Service based on the Supplier's Payment preferences. | Business Payment Service sends this status to the Supplier Payment Agent when the payment instruction complies with the Supplier Payment preferences. | | ACCEPTED with WARNING | Payment instruction is conditionally Accepted by Business Payment Service based on the Supplier's Payment preferences. | Business Payment Service sends this status to the Supplier Payment Agent when the payment instruction does not fully comply with the Supplier Payment preferences. The payment instruction still flows through the payment instruction lifecycle. Specific WARNING reason codes are listed in the Payment preference Violation Reason Codes table. | If the Buyer Payment Agent submits payment instruction that violate your Supplier's payment preferences, the payment instruction may be rejected. If the Buyer Payment Agent receives a warning instead of a rejection you will also receive the following warning message codes. Note: The warning messages do not affect the payment flow. If a warning message is received, the payment still processes. | Reason code | Description | |----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CARD_WARNING | `Supplier ID` flags all `Payment Method` transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | NO_CUSTOMER_NUMBER_WARNING | This transaction is in transit. Supplier `Supplier ID` flags payments which do not include Customer Numbers for all invoices when making `Payment Method` payments. | | CUSTOMER_NUMBER_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions from customer account number `Customer Number`. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | MAX_INSTRUCTED_AMT_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions that exceed the maximum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MIN_INSTRUCTED_AMT_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions less than the minimum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | BUYER_ID_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions from `Buyer ID`. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | PERCENT_WARNING | This transaction is in transit. `Supplier ID` flags `Payment Method` payments that do not include a `Fee Amount Percentage %` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | FLAT_AMOUNT_WARNING | This transaction is in transit. `Supplier ID` flags `Payment Method` payments that do not include a `Fee Amount Dollar $` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MAX_DAYS_AFTER_RELATED_DATE_WARNING | This transaction is in transit. `` flags `` payments that are made later than `<# of Days After Invoice Date>` calendar days after the related date of the referred document for acceptance due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | FEE_PERCENT_DAYS_AFTER_INVOICE_WARNING | This transaction is in transit. `` flags `` payments include a `` fee when sent `<# of Days After Invoice Date>` calendar days after the invoice date due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | FEE_FLAT_DAYS_AFTER_INVOICE_WARNING | This transaction is in transit. `` flags `` payments include a `` fee when sent `<# of Days After Invoice Date>` calendar days after the invoice date due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | NO_RELATED_DATE_WARNING | This transaction is in transit. Supplier `` flags payments which do not include related dates for all invoices when making `` payments. | #### Click Next. {#click-next-3} ## Business Payment Service sends the CARD_PAYMENT_DETAILS_RECEIVED event notification to the Buyer Payment Agent once the Supplier Payment Agent acknowledges the payment instruction notification {#business-payment-service-sends-the-card_payment_details_received-event-notification-to-the-buyer-payment-agent-once-the-supplier-payment-agent-acknowledges-the-payment-instruction-notification} There is no action required for the Supplier Payment Agent at this step. Diagram submitenhancedcard5 ## 2. Review the status code associated with this request. {#2-review-the-status-code-associated-with-this-request} When a Supplier Payment Agent updates the payment instruction status you may receive the following payment status update code from Business Payment Service: | Status | Description | Usage | |-----------|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | SUBMITTED | Payment instruction is submitted to Supplier Payment Agent | Business Payment Service sends this status to the Buyer Payment Agent when the payment instruction is sent to the Supplier Payment Agent. | You have the option at this step to cancel the payment instruction before it is approved. To do so, you can use the following status update code: | Method | Status | Description | |--------|-----------|----------------------------------------------| | Card | CANCELLED | Payment is cancelled by Buyer Payment Agent. | If you opt to cancel the payment instruction at this point, you must include the following reason code: | Reason code | Status | Description | |--------------------------|-----------|------------------------------------------------| | CANCELLED_BY_BUYER_AGENT | CANCELLED | Please contact the Buyer for more information. | If the transaction has been processed by the Supplier Payment Agent, then the cancellation request is rejected. | Reason code | Status | Description | |-----------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_REQUEST | INVALID REQUEST | Invalid request, the current workflow status of the payment instruction does not allow this update. Please investigate the status of the payment to update the payment instruction. | #### Click Next. {#click-next-4} ## The Supplier Payment Agent sends the authorization status to Business Payment Service {#the-supplier-payment-agent-sends-the-authorization-status-to-business-payment-service} Diagram submitenhancedcard6 ## 1. Create the payment instruction update request. {#1-create-the-payment-instruction-update-request} With the February 2023 release, the previously required `cvv` field is now optional. However, the Supplier Payment Agent can reject the payment instruction if desired. Alert: The Mastercard assigned ICA is used for agent identification in all service requests for core operations. A customer service provider can use their API credentials to transact on behalf of a customer by providing their customer's ICA number in the request. Direct payment agents can still transact by entering their own ICA when sending a transaction to Mastercard Track Business Payment Service. API Reference: `PUT /supplier-payment-agents/{ica}/payment-instructions/{transaction_id}` Example payloads for this call include: * JSON ```JSON { "status": "APPROVED", "transactionIdentification": { "approvalCode": "214636", "retrievalReferenceNumber": "54946469666", "transactionReference": "4494944994949", "transactionDateTime": "2020-11-12T15:23:41.207Z" } } ``` * JSON ```JSON { "status": "DECLINED", "statusReasonInformation": [ { "reasonCode": "LOST_CARD" } ] } ``` * JSON ```JSON { "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "INVOICE_NOT_SUPPORTED" } ] } ``` ## 2. Review the status and reason codes associated with this step. {#2-review-the-status-and-reason-codes-associated-with-this-step} You can update the payment instruction status to one of the following: | Status | Description | Usage | |----------|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | APPROVED | Payment instruction is Approved by Supplier Payment Agent | This status is updated by the Supplier Payment Agent when the payment instruction is processed by their payment gateway. | | DECLINED | Payment instruction is Declined by Supplier Payment Agent | This status is updated by the Supplier Payment Agent when the payment instruction is processed by their payment gateway. | | REJECTED | Payment instruction is rejected by the Supplier Payment Agent. | The Supplier Payment Agent can reject the payment instruction with one of the reason codes below if any data validation error or failure occurs. | If you update the payment instruction status to `DECLINED` in the response payload, you must indicate a reason code for the payment failure. | Reason code | Description | |-------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | FAILED | Transaction has failed. | | NO_REPLY | Transaction `` has failed, unable to reach issuing Bank. | | INVALID_ISSUER | Transaction `` has failed, card issuer is not recognized. | | INSUFFICIENT_FUNDS | Transaction `` has failed, due to insufficient funds. | | LOST_CARD | Transaction `` has failed, this card was lost or stolen. | | NOT_PERMITTED | Transaction `` has failed, transaction not approved by the issuing Bank. | | LIMIT_EXCEEDED | Transaction `` has failed, the issuing Bank has restricted this card. | | PROCESSOR_DOWN | Transaction `` has failed, system down. | | NO_CVV | Card Verification Value is required. Please use a valid Card Verification Value numerical minimum length is 3 and maximum length is 4. | | INVALID_CVV | Invalid Card Verification Value. Please use a valid Card Verification Value numerical minimum length is 3 and maximum length is 4. | | REFER_TO_CARD_ISSUER | Transaction {transactionId} has failed, referred to the issuing bank. | | INVALID_MERCHANT | Transaction {transactionId} has failed, invalid merchant. | | CAPTURE_CARD | Transaction {transactionId} has failed, capture card. | | DO_NOT_HONOR | Transaction {transactionId} has failed, do not honor. | | SUPPLIER_BANK_NOT_FOUND | Transaction {transactionId} has failed, Supplier Bank was not found. | | BANK_ACC_FAILURE | Transaction {transactionId} has failed, Supplier's Bank did not accept the transaction. | | INVALID_TRANSACTION | Transaction {transactionId} has failed, invalid transaction. | | INVALID_AMOUNT | Transaction {transactionId} has failed, invalid amount. | | INVALID_CARD_NUMBER | Transaction {transactionId} has failed, invalid card number. | | STOLEN_CARD | Transaction {transactionId} has failed, this card was reported stolen. | | EXPIRED_CARD | Transaction {transactionId} has failed, expired card. | | RESTRICTED_CARD | Transaction {transactionId} has failed, the issuing Bank has restricted this card. | | SECURITY_VIOLATION | Transaction {transactionId} has failed, three-digit CVV2 or CVC or the four-digit CID security code was incorrect. | | BUYER_BANK_NOT_FOUND | Transaction {transactionId} has failed, Buyer Bank was not found. | | CONTACT_CARD_ISSUER | Transaction {transactionId} has failed, contact your issuing bank. | | DUPLICATE_TRANSMISSION | Transaction {transactionId} has failed, duplicate transmission detected. | | AMOUNT_LIMIT_EXCEEDED | Transaction {transactionId} has failed, exceeds withdrawal amount limit. | | COUNT_LIMIT_EXCEEDED | Transaction {transactionId} has failed, exceeds withdrawal count limit. | If you update the payment instruction status to `REJECTED` in the response payload, you must include a reason code for the payment rejection. | Reason code | Description | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SUPPLIER_SYSTEM_DOWN | Unable to find an updated and accurate account number for theSupplier. | | NO_PARTIAL_PAYMENT | Supplier `` will not accept partial payments at this time. | | ALT_MOP | Transaction `` has failed, `` needs to use an alternative method of payment for transacting to ``. | | ALT_MOP_NOT_BPS | Transaction `` has failed, `` does not accept BPS payment from this ``. | | UNSUPPORTED_CURRENCY_BY_SUPPLIER | `` has failed, the Supplier does not accept the selected currency. | | INVOICE_NOT_SUPPORTED | Transaction `` is rejected. The accepting Supplier Payment Agent does not support one or more invoices. | | INVALID_INVOICE_DATA | Transaction `` is rejected. One or more invoices include information that creates a reconciliation mismatch for the accepting Supplier Payment Agent. | | INVALID_CREDIT_NOTE_DATA | Transaction `` is rejected. One or more credit notes include information that creates a reconciliation mismatch for the accepting Supplier Payment Agent. | | NO_CVV | Card Verification Value is required. Please use a valid Card Verification Value numerical minimum length is 3 and maximum length is 4. | You may receive one of the following error messaging codes if you provide incorrect information while updating the status. | Message code | Description | |------------------------|---------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit. | | NO_STATUS | Missing payment instruction status. | | INVALID_STATUS | Payment Instruction status is not valid | #### Click Next. {#click-next-5} ## Business Payment Service sends the CARD_PAYMENT_STATUS_UPDATED event notification with the updated payment instruction status to the Buyer Payment Agent {#business-payment-service-sends-the-card_payment_status_updated-event-notification-with-the-updated-payment-instruction-status-to-the-buyer-payment-agent} There is no action required for the Supplier Payment Agent at this step. Diagram submitenhancedcard7 #### Click Next. {#click-next-6} ## The Supplier Payment Agent reconciles the payment outside of Business Payment Service and updates the status to SETTLED {#the-supplier-payment-agent-reconciles-the-payment-outside-of-business-payment-service-and-updates-the-status-to-settled} Diagram submitenhancedcard8 ## 1. Reconcile the payment outside of Business Payment Service. {#1-reconcile-the-payment-outside-of-business-payment-service} This activity happens outside of Business Payment Service. Once the payment is reconciled, return to Business Payment Service to complete the remaining steps. ## 2. Update the payment instruction status to SETTLED. {#2-update-the-payment-instruction-status-to-settled} Alert: The Mastercard assigned ICA is used for agent identification in all service requests for core operations. A customer service provider can use their API credentials to transact on behalf of a customer by providing their customer's ICA number in the request. Direct payment agents can still transact by entering their own ICA when sending a transaction to Business Payment Service. API Reference: `PUT /supplier-payment-agents/{ica}/payment-instructions/{transaction_id}` An example payload for this call looks like: * JSON ```JSON { "status": "SETTLED", "settlementTimeIndication": { "creditDateTime": "2020-11-12T15:23:41.207Z" } } ``` ## 3. Review the status and error codes associated with this step. {#3-review-the-status-and-error-codes-associated-with-this-step} You can only update the status of the card payment instruction to `SETTLED` at this step. | Status code | Description | Usage | |-------------|--------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | SETTLED | Payment instruction marked Settled by Supplier Payment Agent | This status is updated by the Supplier Payment Agent when the funds have been received and reconciled by the Supplier Payment Agent. | You may receive one of the following error codes if you provide invalid information while updating the status. | Error code | Description | |------------------------|---------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit. | | NO_STATUS | Missing payment instruction status. | | INVALID_STATUS | Payment Instruction status is not valid | #### Click Next. {#click-next-7} ## Business Payment Service sends the reconciliation payment instruction status to the Buyer Payment Agent {#business-payment-service-sends-the-reconciliation-payment-instruction-status-to-the-buyer-payment-agent} There is no action required for the Supplier Payment Agent at this step. Diagram submitenhancedcard9