# Card payment instruction source: https://developer.mastercard.com/mastercard-buyer-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-buyer-payment-agent/uploads/paymentinstruction.png "Payment Instruction Flow") #### Remittance data structure {#remittance-data-structure} ![alt text](https://static.developer.mastercard.com/content/mastercard-buyer-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. ## Buyer Payment Agent initiates payment instruction {#buyer-payment-agent-initiates-payment-instruction} This endpoint returns information relating to card payment instructions initiated by a Buyer Payment Agent. The sequence diagram describes the interaction between the Buyer Payment Agent, Business Payment Service, and Supplier Payment Agent for submitting and processing a card payment instruction. Note: Steps 1, 2, 3, 5, 7, and 9 are applicable to the Buyer Payment Agent for submitting payment instructions and receiving the payment status. Diagram submitenhancedcard1 ## 1. Review the payment instruction structure. {#1-review-the-payment-instruction-structure} Before submitting a payment instruction, familiarize yourself with the invoice remitted amount and instructed amount payment structures. ![Instructed and Remitted Amount Information Flow](https://static.developer.mastercard.com/content/mastercard-buyer-payment-agent/uploads/instructedamount.png "Instructed and Remitted Amount Information Flow") ## 2. Create the payment instruction request. {#2-create-the-payment-instruction-request} Note: The example JSON shows the payment method `TRF`. To specify card as the payment method, update the example swagger call to show `CARD` as the payment method and remove any values listed in `localInstrument` before clicking **Execute**. 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: `POST /buyer-payment-agents/{ica}/payment-instructions` If a Buyer Payment Agent includes a value for the `requestedExecutionDate` field, the payment instruction is converted to a future dated payment in support of Mastercard Track for travel. The Supplier Payment Agent must be enabled for future dated payments in order for the payment instruction to proceed as a future dated payment. 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. The BPA can set a flag to note whether the `cvv` field is required. ## 3. Review the status and error codes associated with this request. {#3-review-the-status-and-error-codes-associated-with-this-request} Once you submit the payment instruction, you will receive the following status from Business Payment Service: | Status | Description | Usage | |----------|--------------------------------------------------------------------|-----------------------------------------------------------------| | RECEIVED | Payment instruction is received by Track Business Payment Service. | This is a free text field that the Buyer Payment Agent can set. | When you submit a card payment instruction, you may receive one or more of the following error codes either if required data is missing or if the data you provided is incorrect. | Reason code | Description | |----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | NO_BUYER_ID | Enter a valid Buyer identifier for the transaction. | | INVALID_BUYER_ID | Invalid Buyer identifier, `` is either not valid or associated to your profile. | | INACTIVE_BUYER_ID | Buyer Id is not active. | | NO_SUPPLIER_ID | Enter a valid Supplier identifier for the transaction. | | INVALID_SUPPLIER_ID | Invalid Supplier identifier, discover the current Supplier in the BPS or contact the Buyer to find the correct Supplier identifier. | | INACTIVE_SUPPLIER_ID | Supplier Id is not active. | | NO_PAYMENT_METHOD | Enter a valid payment method for the transaction. | | INVALID_PAYMENT_METHOD | Enter a valid payment method. The value provided does not match the valid value list. | | NO_PAY_AMOUNT\* | Enter an instructed amount for the transaction. **NOTE: You may receive this reason code if the `amount` object listed in the `instructedAmount` array is missing from the payload OR if the `instructedAmount` array is missing from the payload.** | | INVALID_AMT_FORMAT | Invalid amount format specified for `` amount ``. | | INVALID_INSTRUCTED_AMOUNT | Invalid instructed amount, instructed amount reconciliation error. | | NO_CURRENCY | Enter a valid ISO 4217 3-Alpha currency code. | | INVALID_CURRENCY_CODE | Invalid currency code. Please use a valid currency code (ex. USD). | | INVALID_CHARGE_BEARER | Enter a valid charge bearer. The value provided does not match the valid value list. | | NO_CHARGES_AMOUNT | Enter a charges information amount for the charge bearer. | | NO_CHARGES_TYPE | Enter a charges information type. | | INVALID_CHARGES_TYPE | Enter a valid charge type. The value provided does not match the valid value list. | | NO_TAX_AMOUNT | Invalid total tax amount, total tax amount reconciliation error. | | NO_REMITTANCE_INFORMATION | Enter a remittance information. | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | | INVALID_REQUESTED_EXECUTION_DATE | Enter a valid request execution date. Requested execution date must be in YYYY-MM-DD format and not be in the past or greater than 365 days. | | UNSUPPORTED_PAYMENT_SCHEDULE | The Supplier Payment Agent does not support future dated payments at this time. | When you submit a payment instruction request, Business Payment Service requires certain remittance data to pass on to the Supplier Payment Agent. You may receive one or more of the following error codes if remittance data provided is either invalid or missing. | Reason Code | Description | |-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------| | NO_STRUCTURED_REMITTANCE | At least one instance of structured remittance information is required to make a transaction | | NO_REFERRED_DOCUMENT | At least one instance of referred document information is required to make a transaction | | NO_``_NUMBER | Enter a referred document information `` Number. | | NO_DOCUMENT_TYPE | Enter a referred document information type for document `` | | INVALID_DOCUMENT_TYPE | Invalid Document Type, the value provided does not match the valid value list | | INVALID_RELATED_DATE | Invalid `` related date. Please use a numerical YYYY-MM-DD format. This date should not be in the future. | | INVALID_PAYMENT_DUE_DATE | Invalid \[`` payment due date. Please use a numerical YYYY-MM-DD format. | | NO_LINE_DETAIL_ID | Enter a line item identification. | | NO_LINE_DETAIL_DUE_PAYABLE_AMOUNT | Enter a Due Payable amount in line detail ``. | | INVALID_LINE_ITEM_REMITTED_AMT | Invalid line details remitted amount, referred document `` `` line details remitted amount reconciliation error | | NO_REMITTED_AMOUNT | Enter a referred document `` `` remitted amount. | | NO_REFERRED_DOCUMENT_AMT | Enter a referred document amount for `` ``. | | NO_INVOICE_DUE_PAYABLE_AMOUNT\* | Enter a Due Payable amount in invoice `` `` remitted amount. | | INVALID_REMITTED_AMT | Invalid remitted amount, referred document `` `` remitted amount reconciliation error | If you are adjusting a card 1.0 payment for an invoice by including a value for the `adjustment_amount` field, you must also include the `adjustment_code` field in the payment instructions to the Supplier Payment Agent. Note: The following messaging codes only apply if an adjustment is made to the payment amount, and adjustments only apply when a short payment occurs. | Reason code | Description | |-----------------|------------------------------------------------------------------------------------------| | INCORRECT_AMT | The invoice amount is incorrect. | | DISC_EARLY_PAY | Discount applied for early payment. | | DISC_TAX_EXEMPT | Discount applied for tax exemption. | | DISC_SALES | Discount given by a salesperson. | | DAMAGED_GOODS | Discount applied for damaged goods. | | LATE_GOODS | Discount applied for late delivery of goods. | | LATE_SERVICE | Discount applied for late services. | | FEES | Additional fees applied for convenience or payment processing. | | PREV_PAY_AMT | There was a previous payment made to reduce the balance of the invoice total. | | CM | A credit memo was applied. | | PARTIAL_PAYMENT | This is a partial payment. The total invoice is being paid by more than one transaction. | If the amount paid is below the invoice amount and an adjustment was made to the amount paid, you may receive one of these messaging codes from Business Payment Service. | Message Key | Description | |------------------|------------------------------------------------------------------------------------------------------------------------------------| | NO_ADJ_AMT | Transaction `` declined. The payment amount is not the same as the invoice total. Please add an adjustment amount. | | NO_ADJ_REASON | Transaction `` declined. The payment amount is not the same as the invoice total. Please add an adjustment reason. | | INVALID_ADJ_CODE | Transaction `` adjustment code used is not valid. Please use an adjustment code from the Track BPS codes provided. | You have the option at this step to cancel the future dated payment instruction before the Supplier Payment Agent is notified. 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. | #### 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} There is no action required for the Buyer Payment Agent at this step, however, if the payment instruction is rejected, then the Buyer Payment Agent receives a payment preference event notification. Diagram submitenhancedcard2 ### Supplier payment preferences {#supplier-payment-preferences} Buyer Payment Agents must ensure they are compliant with the Supplier's payment preferences. The following types of preferences are validated in this step: * **Time preferences:** limits the duration of payment acceptance between a Buyer and their Supplier. * **Relationship preferences:** restricts how Buyers can pay each Supplier. * **Amount preferences:** restricts the payment based on total amount of a payment instruction. * **Fee references:** requests an additional fee when making a payment. ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step} If the payment instruction does not conflict with the Supplier's payment preferences, you receive an event notification with the status listed as ACCEPTED. A sample event notification looks like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "Accepted", "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` Note: If the payment instruction does not follow the Supplier's payment preferences, you may receive a warning or rejection. If a warning message is received the payment still processes. A sample ACCEPTED notification with a payment preference warning looks like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "ACCEPTED", "statusReasonInformation": [ { "reasonCode": "MAX_AMT_WARNING", "description": "This transaction is in transit. Supplier ID flags all Payment Method transactions that exceed the maximum allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly." } ], "createdDate": "2020-11-12T15:23:41.207Z", "updatedDate": "2020-11-12T15:23:41.207Z" } } ``` If the payment instruction conflicts with the Supplier's payment preferences, you receive an event notification with the status listed as REJECTED. A sample payment rejected event notification looks like: * JSON ```JSON { "eventId": "459a7g1a-0b8a-43b9-b35d-6489e6daee92", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "paymentMethod": "CARD", "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "MAX_AMT_REJECTED", "description": "Transaction rejected. The transaction amount exceeds the maximum allowed via `Payment Method` by this Supplier." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 2. Review the status and error codes associated with this step. {#2-review-the-status-and-error-codes-associated-with-this-step} You will receive an event notification with the following status: | 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. | | REJECTED | Payment instruction is Rejected by Business Payment Service based on the Supplier's Payment preferences. | 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 submit payment instructions that violate the Supplier's payment preferences, you may receive the following warning or rejection 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 | `` flags all `` transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | CARD_REJECTED | Transaction rejected. `` is not accepted by this Supplier. | | 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. | | NO_CUSTOMER_NUMBER_REJECT | Supplier `Supplier ID` requires that Customer Number is included for all invoices when making `Payment Method` payments. Resubmit with Customer Number included. | | 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. | | CUSTOMER_NUMBER_REJECTED | Transaction rejected. `Payment Method` transactions from customer account number `Customer Number` will not be accepted by this Supplier. | | MAX_INSTRUCTED_AMT_WARNING | This transaction is in transit. `` flags all `` transactions that exceed the maximum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MAX_INSTRUCTED_AMT_REJECTED | Transaction rejected. The transaction amount exceeds the maximum instructed amount allowed via `` by this Supplier. | | MIN_INSTRUCTED_AMT_WARNING | This transaction is in transit. `` flags all `` transactions less than the minimum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MIN_INSTRUCTED_AMT_REJECTED | Transaction rejected. The transaction amount is less than the minimum instructed amount allowed via `` by this Supplier. | | BUYER_ID_WARNING | This transaction is in transit. `` flags all `` transactions from ``. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | BUYER_ID_REJECTED | Transaction rejected. `` transactions from `` are not accepted by this Supplier. | | FLAT_AMOUNT_WARNING | This transaction is in transit. `` flags `` payments that do not include a `` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | FLAT_AMOUNT_REJECTED | Supplier `` requires that `` payments include a `` for acceptance. Resubmit with the `` charge. | | PERCENT_AMT_WARNING | This transaction is in transit. `` flags `` payments that do not include a `` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | PERCENT_AMT_REJECTED | Supplier `` requires that `` payments to include a `` for acceptance. Resubmit with the `` charge. | | TIME_REJECTED | This transaction was rejected. One or more invoices exceeds the number of days after invoice date that a `` payment can be made. | | MAX_DAYS_AFTER_RELATED_DATE_REJECT | Supplier `` requires that `` payments are made no later than `<# of Days After Invoice Date>` calendar days after the related date. Resubmit with another payment method. | | 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_REJECT | Supplier `` requires that `` payments include a `` fee when made `<# of Days After Invoice Date>` calendar days after the invoice date. Resubmit with the `` fee. | | 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 preference violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | FEE_FLAT_DAYS_AFTER_INVOICE_REJECT | Supplier `` requires that `` payments include a `` fee when made `<# of Days After Invoice Date>` calendar days after the invoice date. Resubmit with the `` fee. | | 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 preference violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | NO_RELATED_DATE_REJECT | Supplier `` requires that related date is included for all invoices when making `` payments. Resubmit with related dates included. | | NO_RELATED_DATE_WARNING | This transaction is in transit. Supplier `` flags payments which do not include related dates for all invoices when making `` payments. | You have the option at this step to cancel the future dated payment instruction before the Supplier Payment Agent is notified. 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. | #### Click Next. {#click-next-1} ## The Buyer Payment Agent updates the payment instructions with encrypted card details {#the-buyer-payment-agent-updates-the-payment-instructions-with-encrypted-card-details} Diagram submitenhancedcard3 ## 1. Update the payment instruction with encrypted card details. {#1-update-the-payment-instruction-with-encrypted-card-details} 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 /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}/card-details` ## 2. Review the error codes associated with this step. {#2-review-the-error-codes-associated-with-this-step} When submitting a card payment instruction, you may receive one or more of the following error codes if you provided either invalid or missing card details. Note: If the payment instruction was submitted as a future dated payment, the Buyer Payment Agent must include values for the `currency` and `effectiveDate` fields. | Reason code | Description | |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit | | NO_CARD_DATA | Enter card data. | | NO_PAN | Enter a Primary Account/Card Number. | | FAILED_MOD10_CHECK | The provided primary account number did not pass the Mod10 validation | | INVALID_PAN | Invalid primary account number. Please use a valid primary account number. | | NO_CARDHOLDER_NAME | Enter a cardholder name. | | INVALID_CARDHOLDER_NAME | Invalid cardholder name | | NO_CVV | Enter a Card Verification Value. | | INVALID_CVV | Invalid Card Verification Value. Please use a valid Card Verification Value numerical minimum length is 3 and maximum length is 4. | | NO_EXPIRY_DATE | Enter a Expiry Date. | | INVALID_EXPIRY_DATE | Invalid Expiry Date, Please use ISOYearMonth format | | EXPIRED_CARD | Card is expired | | INVALID_REQUEST | Invalid request, the current workflow status of the payment instruction does not permit this update. Please check the status of the payment and update the payment instruction | | INVALID_CURRENCY_CODE | Invalid currency code. Please use a valid currency code (ex. USD). | | INVALID_EFFECTIVE_DATE | From date and to date are required for effective date. | | TO_DATE_OUT_OF_RANGE | The validity field ToDate is less than the RequestedExecutionDate. | | INVALID_DATE_FORMAT | Enter date value in YYYY-MM-DD format. | | EFFECTIVE_DATE_OUT_OF_RANGE | Requested Execution Date must fall between Effective From Date and Effective To Date. | You have the option at this step to cancel the future dated payment instruction. 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. | #### 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} There is no action required for the Buyer Payment Agent at this step. Diagram submitenhancedcard4 #### Click Next. {#click-next-3} ## Business Payment Service sends a payment notification to the Buyer Payment Agent once the Supplier Payment Agent acknowledges the payment notification {#business-payment-service-sends-a-payment-notification-to-the-buyer-payment-agent-once-the-supplier-payment-agent-acknowledges-the-payment-notification} There is no action required for the Buyer Payment Agent at this step, however, the Buyer Payment Agent will receive an event notification with the status of the payment instruction. Diagram submitenhancedcard5 ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step-1} When the Supplier Payment Agent acknowledges the payment instruction event notification, you will receive an event notification. This could look like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "SUBMITTED", "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 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 future dated payment instruction. 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. | #### Click Next. {#click-next-4} ## The Supplier Payment Agent sends the card payment authorization status APPROVED, REJECTED, or DECLINED to Business Payment Service {#the-supplier-payment-agent-sends-the-card-payment-authorization-status-approved-rejected-or-declined-to-business-payment-service} There is no action required for the Buyer Payment Agent at this step. Diagram submitenhancedcard6 #### Click Next. {#click-next-5} ## Business Payment Service sends the payment status update to the Buyer Payment Agent {#business-payment-service-sends-the-payment-status-update-to-the-buyer-payment-agent} Diagram submitenhancedcard7 ## 1. Review the sample event notifications associated with this step. {#1-review-the-sample-event-notifications-associated-with-this-step} Business Payment Service sends the Buyer Payment Agent an event notification when the status is updated by the Supplier Payment Agent. This event notification could look like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "APPROVED", "transactionIdentification": { "approvalCode": "214636", "retrievalReferenceNumber": "54946469666", "transactionReference": "4494944994949", "transactionDateTime": "2020-02-13T11:32:28Z" }, "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } } ``` A declined status event notification can look like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "DECLINED", "statusReasonInformation": [ { "reasonCode": "INSUFFICIENT_FUNDS", "description": "Transaction 7667609d-9acb-466c-9116-c6db30c733b5 has failed, due to insufficient funds" } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` A rejected status event notification can look like: * JSON ```JSON { "eventId": "07f7134b-0feb-431e-8983-be3f1e99a453", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2021-05-19T16:09:46.702Z", "data": { "transactionId": "9d40b3e6-1a79-44a6-9e84-afb4117d2c29", "paymentMethod": "CARD", "createdDate": "2021-05-19T16:08:53.917Z", "updatedDate": "2021-05-19T16:09:12.068Z", "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "INVOICE_NOT_SUPPORTED", "description": "Transaction 9d40b3e6-1a79-44a6-9e84-afb4117d2c29 is rejected. The accepting Supplier Payment Agent does not support one or more invoices." } ] } } ``` ## 2. Review the status and error codes associated with this step. {#2-review-the-status-and-error-codes-associated-with-this-step-1} When a Supplier Payment Agent updates the payment instruction status you may receive one of the following payment status update codes from Business Payment Service: | Status | Description | Usage | |----------|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | 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. | | 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. | If the Supplier Payment Agent updates the payment instruction status to `DECLINED`, you will receive one of the following reason codes from Business Payment Service. | 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 the Supplier Payment Agent updates the payment instruction status to `REJECTED`, you will receive one of the following reason codes from Business Payment Service. | Reason code | Description | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SUPPLIER_SYSTEM_DOWN | Unable to find an updated and accurate account number for the Supplier. | | 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. | If the Buyer Payment Agent attempts to cancel a future dated payment, you will receive one of the following reason codes from Business Payment Service. | Reason code | Description | |------------------------|------------------------------------------| | INVALID_CANCEL_REQUEST | Payment instruction status is not valid. | #### Click Next. {#click-next-6} ## The Supplier Payment Agent reconciles the payment and updates the status to SETTLED {#the-supplier-payment-agent-reconciles-the-payment-and-updates-the-status-to-settled} There is no action required for the Buyer Payment Agent at this step. Diagram submitenhancedcard8 #### Click Next. {#click-next-7} ## Business Payment Service sends the reconciliation payment status to the Buyer Payment Agent {#business-payment-service-sends-the-reconciliation-payment-status-to-the-buyer-payment-agent} Diagram submitenhancedcard9 ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step-2} Business Payment Service notifies the Buyer Payment Agent with an event notification when the payment instruction is reconciled by the Supplier Payment Agent. This event notification could look like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "CARD_PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "CARD", "status": "SETTLED" "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 2. Review the status codes associated with this step. {#2-review-the-status-codes-associated-with-this-step} 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 | |---------|--------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | 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. |