# Account to account payment instructions source: https://developer.mastercard.com/mastercard-buyer-payment-agent/documentation/tutorials-and-guides/a2a-tutorial/index.md ## Overview {#overview} Business Payment Service allows Buyer Payment Agents to send payment instructions using the credit transfer (TRF) payment rail and any local instrument. Buyer Payment Agents and their buyers can now specify the payment method, payment rail, and country for their payment data, which enables them to know exactly how and on what rail they switch the data funds. Business Payment Service generates end-to-end IDs to link the payment instructions coming through Business Payment Service with the payment coming through TRF. This allows Supplier Payment Agents and their suppliers to reconcile payments more easily and efficiently. > > #### What you will learn {#what-you-will-learn} > > * How to submit an account to account (A2A) payment instruction > * How to update an A2A 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} ![Payment instruction structure](https://static.developer.mastercard.com/content/mastercard-buyer-payment-agent/uploads/paymentinstruction.png "Payment Instruction Flow") #### Remittance data structure {#remittance-data-structure} ![Remittance data structure](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 create and process an A2A payment instruction from end-to-end. ## Next steps {#next-steps} Click **Next** to get started. ## The Buyer Payment Agent initiates a payment instruction request. {#the-buyer-payment-agent-initiates-a-payment-instruction-request} Diagram submita2a1 ## 1. Review the payment instruction structure. {#1-review-the-payment-instruction-structure} Before submitting a payment instruction, familiarize yourself with the `invoiceRemittedAmount` and `instructedAmount` payment structures. Note that `chargeBearer` and `chargesInformation > amount` are only applicable for card payment instructions. ![alt text](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: With the August 2021 release, existing Buyer Payment Agents can continue to submit ACH and RTP as payment methods until they switch to the ICA version of the endpoints. All new customers onboarded after August 2021 will submit A2A payment instructions with the credit transfer (TRF) value for `paymentMethod`. 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: `POST /buyer-payment-agents/{ica}/payment-instructions` With the February 2022 release, any `buyerId` or `supplierId` entered in the payment instruction request payload with leading or trailing spaces will be trimmed. Valid local instruments are: | ISO country code | Payment method | Local instrument | Name | Description | ISO currency code | Payment system | |------------------|----------------|------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|-------------------|----------------| | US | TRF | CCD | Cash Concentration Or Disbursement Corporate Counterparty | Transaction is related to cash concentration or disbursement corporate counterparty. | USD | NACHA | | US | TRF | CTX | Corporate Trade Exchange | The transaction is related to corporate trade exchange. | USD | NACHA | | US | TRF | RTP | US Instant Credit Transfer | The transaction is related to an Instant Credit Transfer. | USD | TCH | | EU | TRF | ONCL | Overnight | Transaction is related to overnight clearing. | EUR | SEPA | | EU | TRF | PERI | Payment with ERI | Credit transfer contains Extended Remittance Information (ERI) as defined within the applicable scheme. | EUR | SEPA | | EU | TRF | SDCL | Same Day | Transaction is related to same day clearing. | EUR | SEPA | | EU | TRF | INST | Instant Credit Transfer | The transaction is related to an Instant Credit Transfer. Use a case example: SEPA Instant Credit Transfer (SCT Inst) | EUR | SEPA | | GB | TRF | FPS | UK Instant Credit Transfer | The transaction is related to an Instant Credit Transfer. | GBP | FPS | | AU | TRF | BECS | Bulk Electronic Clearing System | Bulk Electronic Clearing System | AUD | BECS | ## 3. Optional: Cancel a payment instruction before Business Payment Service sends it to the Supplier Payment Agent {#3-optional-cancel-a-payment-instruction-before-business-payment-service-sends-it-to-the-supplier-payment-agent} The Buyer Payment Agent can cancel an A2A payment instruction with any local instrument at this step. However, if the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be canceled at any point of the payment instruction lifecycle. The workflow for cancelling a payment instruction when the Buyer Payment Agent initiates the payment instruction, looks like: Diagram cancela2astep1 Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `CANCELLED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to CANCELLED looks like: * JSON ```JSON { "status": "CANCELLED", "statusReasonInformation": [ { "reasonCode": "CANCELLED_BY_BUYER_AGENT", "description": "Please contact the Buyer for more information." } ] } ``` ## 4. Review the status and error codes associated with this request. {#4-review-the-status-and-error-codes-associated-with-this-request} When you submit an A2A payment instruction, you may receive one or more of the following error codes either if the 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. | | INVALID_LOCAL_INSTRUMENT | Enter a valid local instrument. The value provided does not match the valid value list. Valid values are CCD, CTX, FPS, BECS, RTP, INST and WEB. | | LOCAL_INSTRUMENT_NOT_SUPPORTED | Enter TRF as the payment method. Local instruments cannot be used with ACH, card or RTP. | | NO_LOCAL_INSTRUMENT | Enter a local instrument. A local instrument is required when the payment method is account to account transfers (TRF). | | UNSUPPORTED_LOCAL_INSTRUMENT | Enter supported local instrument. The local instrument used for the transaction is not supported by the agent or Supplier. | | 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\* | Enter a valid currency. Payment instructions with local instrument `x` only support the currency `y`. **Note: You may receive this error code if you entered an invalid SEPA local instrument and currency combination. The SEPA local instruments (ONCL, PERI, SDCL, and INST) can only be used to switch data between European countries where the euro is the main currency.** | | 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 charge information amount for the charge bearer. | | NO_CHARGES_TYPE | Enter a charge 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. | | PAYMENT_METHOD_NOT_SUPPORTED | Enter a valid payment method. This end point does not support the value provided. Valid payment methods are TRF and CARD. | 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 the 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 the Business Payment Service. | Error code | 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 payment instruction before the Supplier Payment Agent is notified. To do so, you can use the following status update code: | Method | Status | Description | |--------|-----------|--------------------------------------------------| | TRF | CANCELLED | Payment is cancelled by the 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. | Once you submit the payment instruction, you will receive the following status from BPS: | Status | Description | Usage | |----------|-----------------------------------------------|-------------------------------------------------------------------| | RECEIVED | Payment instruction is received by Track BPS. | This status is sent by BPS in receipt of the payment instruction. | #### 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, the Business Payment Service sends the payment instruction status update notification to the Buyer Payment Agent. There is no action required for the Buyer Payment Agent at this step, however, the Buyer Payment Agent can cancel the payment instruction. Diagram submita2a2 ### 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 the total amount of a payment instruction. * **Fee preferences:** 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} A sample event notification with an ACCEPTED response looks like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "ACCEPTED", "updatedDate": "2020-11-12T15:23:41.207Z" } } { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "TRF", "status": "ACCEPTED", "createdDate": "2020-11-12T15:23:41.207Z", "updatedDate": "2020-11-12T15:23:41.207Z" } } ``` A sample event notification with an ACCEPTED response and a payment preference warning looks like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "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, the Buyer Payment Agent receives 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": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "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. Optional: Cancel a payment instruction before Business Payment Service sends it to the Supplier Payment Agent {#2-optional-cancel-a-payment-instruction-before-business-payment-service-sends-it-to-the-supplier-payment-agent} The Buyer Payment Agent can cancel an A2A payment instruction with any local instrument at this step. If the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be canceled at any point of the payment instruction lifecycle and the agent receives the CANCELLATION_NOT_ALLOWED error code with the description "Cancellation is not allowed for transactions where ipu value is true and requestedExecutionDate is in future." The workflow for cancelling a payment instruction when the Business Payment Service validates the payment instruction against the Supplier's payment preferences, looks like: Diagram cancela2astep2 Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `CANCELLED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to CANCELLED looks like: * JSON ```JSON { "status": "CANCELLED", "statusReasonInformation": [ { "reasonCode": "CANCELLED_BY_BUYER_AGENT", "description": "Please contact the Buyer for more information." } ] } ``` ## 3. Review the status and error codes associated with this step. {#3-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 the 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 the 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 reason codes do not affect the payment flow. If a warning message is received, the payment still processes. | Reason code | Description | |----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ACH_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | ACH_REJECTED | Transaction rejected. `` is not accepted by this Supplier. | | RTP_WARNING | This transaction is in transit. `` flags all `` transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | RTP_REJECTED | Transaction rejected. `` is not accepted by this Supplier. | | TRF_WARNING | This transaction is in transit. `` flags all TRF transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | TRF_REJECTED | Transaction rejected. TRF 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 the 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 through `` 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 through `` 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 the 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 control 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 control 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 payment instruction before the Supplier Payment Agent is notified. To do so, you can use the following status update code: | Method | Status | Description | |--------|-----------|--------------------------------------------------| | TRF | CANCELLED | Payment is cancelled by the 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} ## Business Payment Service sends the payment instruction to the Supplier Payment Agent to request the Supplier bank account information {#business-payment-service-sends-the-payment-instruction-to-the-supplier-payment-agent-to-request-the-supplier-bank-account-information} There is no action required for the Buyer Payment Agent at this step, however, the Buyer Payment Agent can cancel the payment instruction. Diagram submita2a3 The Buyer Payment Agent can cancel an A2A payment instruction with any local instrument at this step. ## Optional: Cancel a payment instruction before receiving bank account details {#optional-cancel-a-payment-instruction-before-receiving-bank-account-details} If the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be canceled at any point of the payment instruction lifecycle and the agent receives the CANCELLATION_NOT_ALLOWED error code with the description "Cancellation is not allowed for transactions where the ipu value is true and requestedExecutionDate is in future." The workflow for cancelling a payment instruction when the Business Payment Service sends the payment instruction to the Supplier Payment Agent, looks like: Diagram cancela2astep3 Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `CANCELLED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to CANCELLED looks like: * JSON ```JSON { "status": "CANCELLED", "statusReasonInformation": [ { "reasonCode": "CANCELLED_BY_BUYER_AGENT", "description": "Please contact the Buyer for more information." } ] } ``` #### Click Next. {#click-next-2} ## The Supplier Payment Agent updates the payment instruction with the Supplier's encrypted bank account details {#the-supplier-payment-agent-updates-the-payment-instruction-with-the-suppliers-encrypted-bank-account-details} There is no action required for the Buyer Payment Agent at this step. Diagram submita2a4 Note: The Supplier Payment Agent can continue to update the bank account details for future dated payment instruction when the payment instruction status is PENDING. An example payment instruction rejection looks like: * JSON ```JSON { "eventId": "459a7g1a-0b8a-43b9-b35d-6489e6daee92", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "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 Supplier Payment Agent." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` #### Click Next. {#click-next-3} ## Business Payment Service sends the payment instruction with the bank account details and the Business Payment Service-generated end-to-end ID to the Buyer Payment Agent to process the payment {#business-payment-service-sends-the-payment-instruction-with-the-bank-account-details-and-the-business-payment-service-generated-end-to-end-id-to-the-buyer-payment-agent-to-process-the-payment} Diagram submita2a5 ## 1. Review the end-to-end ID format requirements and sample event notification. {#1-review-the-end-to-end-id-format-requirements-and-sample-event-notification} The end-to-end ID will vary by local instrument. Review the format requirements based on the local instrument. | Local instrument | Country | End-to-end ID length | Data type | |---------------------|--------------------------------------|----------------------|----------------------------------------------------------------------| | CCD CTX | US | 15 | alphanumeric | | RTP | US | 35 | alphanumeric | | FPS | UK | 31 | alphanumeric with special characters LLVAR with 2-digit field header | | BECS | AU | 18 | alphanumeric | | ONCL PERI SDCL INST | Single Euro Payments Area (Eurozone) | 15 | alphanumeric | Business Payment Service sends the payment instruction as an event notification. A sample event notification looks like: * JSON ```JSON { "eventId": "6aaf8785-eb1f-4e5e-a879-a1ef69e862f8", "eventType": "SUPPLIER_BANK_ACCOUNT_RECEIVED", "eventCreatedDate": "2020-05-15T14:52:00.273Z", "data": { "transactionId": "6aaf8785-eb1f-4e5e-a879-a1ef69e862f8", "endToEndId": "6aaf8785-eb1f-4e5e-a879-a1ef69e862f", "buyerId": "matest.pay@track", "supplierId": "matest@track", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "instructedAmount": { "amount": 200.5, "currency": "USD" }, "tax": { "totalTaxAmount": 25 }, "remittanceInformation": { "structured": [ { "referredDocumentInformation": [ { "number": "3521264364", "type": "CINV", "relatedDate": {}, "paymentDueDate": {}, "lineDetails": [ { "identifications": [ { "number": "5489549615", "type": { "code": "ASNB", "proprietary": "string" }, "relatedDate": {} } ], "quantity": 1, "unitOfMeasure": "1A", "description": "string", "amount": { "duePayableAmount": 3000, "discountAppliedAmounts": [ { "type": { "code": "APDS", "proprietary": "string" }, "amount": 0 } ], "taxAmounts": [ { "type": { "code": "CITY", "proprietary": "string" }, "amount": 0 } ], "adjustmentAmountAndReasons": [ { "amount": 100, "creditDebitIndicator": "CREDIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 0, "creditNoteAmount": 0 } } ], "referredDocumentAmount": { "duePayableAmount": 0, "discountAppliedAmounts": [ { "type": { "code": "APDS", "proprietary": "string" }, "amount": 0 } ], "taxAmounts": [ { "type": { "code": "CITY", "proprietary": "string" }, "amount": 0 } ], "adjustmentAmountAndReasons": [ { "amount": 100, "creditDebitIndicator": "CREDIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 0, "creditNoteAmount": 0 } } ], "supplierReferenceInformation": { "type": { "code": "string", "amount": 0 }, "issuer": "ISO", "reference": "RF18 5390 0754 7034" }, "invoicer": { "name": "ACME Inc.", "organisationIdentifications": [ { "identification": "82-2981873", "type": "TXID" } ] }, "invoicee": { "name": "Contoso Inc.", "organisationIdentifications": [ { "identification": "82-2981873", "type": "TXID" } ] }, "additionalRemittanceInformation": [ "Data1:abc", "Data2:xyz", "Data3:lmn", "DataN:nnn" ] } ] }, "status": "PENDING", "encryptedSupplierBankAccount": { "encryptedValue": "GWe+JReXeS0rRyTYRQLQosLGPjzwu4KgzrUil8NeimVx2GlPMokImFKgyMRzajNVWKfceGedyTJKAz2guODI1ZrL2Um2HLY4FYhj4IloBNnqFZE4wOTFw26iz9+pGPK0w6aQYkIkYaEOELQ8WfPxud8QUVc6pqwjsTarmsb+BLcfDvkkUiPL6NZd4YgahR8k", "iv": "y4Fjzs9W7Mo7dYjU7o85ng==", "encryptedKey": "kbxvW4kMiUT1fZITZ/30IHFY9iq7Az+AclsaJKVHe8e9hJ2id+9s39wsNs3xPMSMenhOITA+ti+QKl3t70DC3aA6tLSisUJEigFN4NfukXasWTa2F6yBmDUVGYps1VW930/dlYuWBV1PkE9Gdpozft5NPk23grDRYIICm+yM5hriU2G0Wlag6IRyCiHsKqX01qndIPCINNbgrXFqE7ZmAg+S9Vs+yQC2kd01lb7RnZHmUpRbHnBl3SKu9flmbgdPPmd0PwWyzxAMfhoQqENk7BqC4lUojf/UfHjfMeoI/d1Qh6NYmMf9sjj9SBDiFVfDIVw56U9CtrsVUgbSVV9r4Q==", "oaepPaddingDigestAlgorithm": "SHA256", "publicKeyFingerprint": "70632bc104e31f204fdc59f9e40fb3f1c84f4938699e475abcefdd6b293888ed" }, "createdDate": "2020-05-15T14:52:00.273Z", "updatedDate": "2020-05-15T14:52:00.273Z" } } ``` A sample rejected status event notification looks like: * JSON ```JSON { "eventId": "6aaf2c8e-6ba4-45b3-9753-07a049a766dc", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2021-05-19T16:17:29.511Z", "data": { "transactionId": "2ca2668c-76b2-4a0a-afdf-d62c06e2ca25", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "createdDate": "2021-05-19T16:17:01.849Z", "updatedDate": "2021-05-19T16:17:02.392Z", "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "INVOICE_NOT_SUPPORTED", "description": "Transaction 2ca2668c-76b2-4a0a-afdf-d62c06e2ca25 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} You will receive an event notification with one of the following statuses: | Status | Description | Usage | |----------|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | PENDING | Payment instruction is pending payment. | Business Payment Service sends this status to the Supplier Payment Agent after the account details are added. | | 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 the Supplier Payment Agent rejects your payment instruction, you will also receive one of the following reason codes: | Reason code | Description | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SUPPLIER_ACCT_NOT_FOUND | Unable to find an updated and accurate account number for the Supplier. | | ACCOUNT_CLOSED | The supplier's account has been closed. | | 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. The `` 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. | ## 3. Reconcile the payment outside of Business Payment Service. {#3-reconcile-the-payment-outside-of-business-payment-service} This activity happens outside of the Business Payment Service. Once the payment is reconciled, return to Business Payment Service to complete the remaining steps. #### Click Next. {#click-next-4} ## Buyer Payment Agent updates the payment instruction status {#buyer-payment-agent-updates-the-payment-instruction-status} Diagram submita2a6 ## 1. Update the payment instruction status. {#1-update-the-payment-instruction-status} 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 /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` ## 2. Optional: Payment instruction cancellation, failure, and reversal {#2-optional-payment-instruction-cancellation-failure-and-reversal} At this step, the Buyer Payment Agent can mark the payment instruction as: * `CANCELLED` with any local instrument * `PAYMENT_FAILED` with any local instrument * `REVERSAL_REQUESTED` with CCD or CTX as the local instrument ## 2.1. Optional: Cancel a payment instruction after receiving bank account details {#21-optional-cancel-a-payment-instruction-after-receiving-bank-account-details} If the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be canceled at any point of the payment instruction lifecycle and the agent receives the CANCELLATION_NOT_ALLOWED error code with the description "Cancellation is not allowed for transactions where the ipu value is true and requestedExecutionDate is in future." The workflow for cancelling a payment instruction when the Buyer Payment Agent updates the payment instruction status, looks like: Diagram cancela2astep6 Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `CANCELLED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to CANCELLED looks like: * JSON ```JSON { "status": "CANCELLED", "statusReasonInformation": [ { "reasonCode": "CANCELLED_BY_BUYER_AGENT", "description": "Please contact the Buyer for more information." } ] } ``` ## 2.2. Optional: Mark a payment instruction failure. {#22-optional-mark-a-payment-instruction-failure} A Buyer Payment Agent can mark an A2A payment instruction and any local instrument with the `PAYMENT_FAILED` status after receiving the payment failure status from the payment rail. If the payment instruction fails on the rails, the Supplier Payment Agent is notified. This is the only step within the A2A payment instruction lifecycle that a payment can be marked as `PAYMENT_FAILED`. The workflow for marking a payment failure looks like: Diagram a2apaymentfailstep6 Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `PAYMENT_FAILED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to PAYMENT_FAILED looks like: * JSON ```JSON { "status": "PAYMENT_FAILED", "statusReasonInformation": [ { "reasonCode": "ACCOUNT_ISSUES", "description": "Please contact the Buyer for more information." } ] } ``` ## 2.3. Optional: Request a payment reversal after receiving SUBMITTED status {#23-optional-request-a-payment-reversal-after-receiving-submitted-status} The workflow for requesting an A2A payment instruction reversal when the Buyer Payment Agent updates the payment instruction status looks like: Diagram a2areversalstep6 The Buyer Payment Agent can request a payment reversal for payment instructions with the local instrument CCD or CTX at several points during the lifecycle of the payment instruction. If the Buyer Payment Agent requests a payment reversal, the Supplier Payment Agent is notified. If the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be reversed at any point of the payment instruction lifecycle and receive the REVERSAL_NOT_ALLOWED error code with the description "Reversal is not allowed for transactions where the ipu value is true and requestedExecutionDate is in future." ### 2.3.1. The Buyer Payment Agent first requests a payment reversal {#231-the-buyer-payment-agent-first-requests-a-payment-reversal} Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example swagger call to show `REVERSAL_REQUESTED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to REVERSAL_REQUESTED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_REQUESTED", "statusReasonInformation": [ { "reasonCode": "ERRONEOUS_PAYMENT" } ] } ``` ### 2.3.2. The Buyer Payment Agent then indicates REVERSAL_COMPLETED or REVERSAL_NOT_COMPLETED {#232-the-buyer-payment-agent-then-indicates-reversal_completed-or-reversal_not_completed} A sample payload for updating the status to REVERSAL_COMPLETED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_COMPLETED", "statusReasonInformation": [ { "reasonCode": "DUPLICATE_PAYMENT" } ] } ``` A sample payload for updating the status to REVERSAL_NOT_COMPLETED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_NOT_COMPLETED", "statusReasonInformation": [ { "reasonCode": "REVERSAL_NOT_HONORED" } ] } ``` ## 3. Review the status and error codes associated with this request. {#3-review-the-status-and-error-codes-associated-with-this-request} When updating the payment instruction, you will include one of the following statuses: | Status | Method | Local instrument | Description | |--------------------|--------|-------------------------------------------------|--------------------------------------------------------------| | PAYMENT_INITIATED | TRF | BECS, CCD, CTX, ONCL, PERI, and SDCL | Payment is initiated by the Buyer Payment Agent. | | PAYMENT_DELIVERED | TRF | FPS, RTP, and INST | Payment is delivered by the Buyer Payment Agent. | | CANCELLED | TRF | CCD, CTX, ONCL, PERI, INST, SDCL, BECS, and FPS | Payment is cancelled by the Buyer Payment Agent. | | PAYMENT_FAILED | TRF | CCD, CTX, ONCL, PERI, INST, SDCL, BECS, and FPS | Payment failed on the payment rail. | | REVERSAL_REQUESTED | TRF | BECS, CCD, CTX, ONCL, PERI, and SDCL | A payment reversal was requested by the Buyer Payment Agent. | When updating the status of a payment instruction, you need to provide a reason code. The below reason codes are appropriate for the indicated status. | Reason code | Status | Description | |--------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | CANCELLED_BY_BUYER_AGENT | CANCELLED | Please contact the Buyer for more information. | | ACCOUNT_ISSUES | PAYMENT_FAILED, REVERSAL_REQUESTED, REVERSAL_COMPLETED | Please contact the Buyer for more information. | | ERRONEOUS_PAYMENT | REVERSAL_REQUESTED | The Buyer initiated a reversal of funds. Please contact your Buyer for further information if needed. | | DUPLICATE_PAYMENT | REVERSAL_REQUESTED, REVERSAL_COMPLETED | The payment reversal was not completed and the funds were not sent back to the Buyer. Please call your Buyer for further information if needed. | | REVERSAL_NOT_HONORED | REVERSAL_NOT_COMPLETED | The payment reversal was not completed and the funds were not sent back to the Buyer. Please call your Buyer for further information if needed. | When you update an account to account (A2A) payment instruction, you may receive one or more of the following error codes either if the required data is missing or if the data you provided is incorrect. | Reason code | Description | |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit | | NO_ENDTOEND_ID | Missing end to end identifier | | INVALID_ENDTOEND_ID | Invalid end to end identifier, the end to end identifier must match the BPS-generated end to end identifier | | NO_STATUS | Missing payment instruction status | | INVALID_STATUS | Payment instruction status is not valid | | 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-5} ## Business Payment Service sends the payment status update to the Supplier Payment Agent {#business-payment-service-sends-the-payment-status-update-to-the-supplier-payment-agent} There is no action required for the Buyer Payment Agent at this step. Diagram submita2a7 #### Click Next. {#click-next-6} ## 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} Diagram submita2a7-5 ## 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, the Buyer Payment Agent receives an event notification. A sample event notification for this step looks like: * JSON ```JSON { "eventId": "7667609d-9acb-466c-9116-c6db30c733b5", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "7667609d-9acb-466c-9116-c6db30c733b5", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "SUBMITTED", "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 2. Review the status and code associated with this step. {#2-review-the-status-and-code-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 | |-----------|----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | SUBMITTED | Payment instruction is submitted to the 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. | #### Click Next. {#click-next-7} ## The Supplier Payment Agent reconciles the payment and updates the status to FUNDS_RECEIVED or FUNDS_NOT_RECEIVED {#the-supplier-payment-agent-reconciles-the-payment-and-updates-the-status-to-funds_received-or-funds_not_received} There is no action required for the Buyer Payment Agent at this step. Diagram submita2a8 #### Click Next. {#click-next-8} ## 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 submita2a9 ## 1. Review the sample event notifications associated with this step. {#1-review-the-sample-event-notifications-associated-with-this-step} Possible event notifications for this step look like: ### FUNDS_RECEIVED event notification {#funds_received-event-notification} * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "FUNDS_RECEIVED", "settlementTimeIndication": { "creditDateTime": "2020-07-16T11:32:28Z" }, "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ### FUNDS_NOT_RECEIVED event notification {#funds_not_received-event-notification} * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "FUNDS_NOT_RECEIVED", "statusReasonInformation": [ { "reasonCode": "SUPPLIER_NO_RECEIPT_OF_FUNDS", "description": "Contact the Supplier directly to obtain more details." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` Note: With the August 2021 release, existing Buyer Payment Agents can continue to submit ACH and RTP as payment methods until they switch to the ICA version of the endpoints. All new customers onboarded after August 2021 will submit A2A payment instructions with the credit transfer (TRF) value for `paymentMethod`. ## 2. Optional: Request a payment reversal after receiving FUNDS_RECEIVED status. {#2-optional-request-a-payment-reversal-after-receiving-funds_received-status} The Buyer Payment Agent can request for payment instruction reversal for CCD and CTX local instruments at this step. The workflow for requesting for A2A payment instruction reversal, when Business Payment Service notifies the Buyer Payment Agent of the reconciliation status, looks like: Diagram a2areversalstep9 If the Buyer Payment Agent requests a payment reversal, the Supplier Payment Agent is notified. If the Buyer Payment Agent included a value for the `ipu` field, then the payment instruction cannot be reversed at any point of the payment instruction lifecycle and receive the REVERSAL_NOT_ALLOWED error code with the description "Reversal is not allowed for transactions where the ipu value is true and requestedExecutionDate is in future." ### 2.1. The Buyer Payment Agent first requests a payment reversal. {#21-the-buyer-payment-agent-first-requests-a-payment-reversal} Note: The example JSON shows the status `PAYMENT_INITIATED`. To specify A2A as the payment method, update the example of the swagger call to show `REVERSAL_REQUESTED` as the payment status before clicking **Execute**. API Reference: `PUT /buyer-payment-agents/{ica}/payment-instructions/{transaction_id}` A sample payload for updating the status to REVERSAL_REQUESTED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_REQUESTED", "statusReasonInformation": [ { "reasonCode": "ERRONEOUS_PAYMENT" } ] } ``` ### 2.2. The Buyer Payment Agent then indicates REVERSAL_COMPLETED or REVERSAL_NOT_COMPLETED. {#22-the-buyer-payment-agent-then-indicates-reversal_completed-or-reversal_not_completed} A sample payload for updating the status to REVERSAL_COMPLETED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_COMPLETED", "statusReasonInformation": [ { "reasonCode": "DUPLICATE_PAYMENT" } ] } ``` A sample payload for updating the status to REVERSAL_NOT_COMPLETED looks like: * JSON ```JSON { "endToEndId": "ii7ITHdCGZpcDYv", "status": "REVERSAL_NOT_COMPLETED", "statusReasonInformation": [ { "reasonCode": "REVERSAL_NOT_HONORED" } ] } ``` ## 3. Review the status and reason codes associated with this step. {#3-review-the-status-and-reason-codes-associated-with-this-step} You may receive the following statuses from the Business Payment Service throughout the A2A payment instruction flow. | Status | Description | Usage | |--------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | FUNDS_RECEIVED | Payment instruction marked funds received 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. | | FUNDS_NOT_RECEIVED | Payment instruction marked funds not received by Supplier Payment Agent. | This status is updated by the Supplier Payment Agent when the funds have not been received by the Supplier Payment Agent. | If you receive the status update `FUNDS_NOT_RECEIVED`, you will also receive the following status reason code: | Reason code | Description | |------------------------------|-------------------------------------------------------| | SUPPLIER_NO_RECEIPT_OF_FUNDS | Contact the Supplier directly to obtain more details. | You have the option to request a reversal at this step. To do so, you can include the following status: | Method | Status | Description | |--------|--------------------|--------------------------------------------------------------| | ACH | REVERSAL_REQUESTED | A payment reversal was requested by the Buyer Payment Agent. | When updating the status of a payment instruction to REVERSAL_REQUESTED, you must provide a reason code. | Reason code | Status | Description | |----------------------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | ACCOUNT_ISSUES | PAYMENT_FAILED, REVERSAL_REQUESTED, REVERSAL_COMPLETED | Please contact the Buyer for more information. | | ERRONEOUS_PAYMENT | REVERSAL_REQUESTED | The Buyer initiated a reversal of funds. Please contact your Buyer for further information if needed. | | DUPLICATE_PAYMENT | REVERSAL_REQUESTED, REVERSAL_COMPLETED | The ACH payment reversal was not completed and the funds were not sent back to the Buyer. Please call your Buyer for further information if needed. | | REVERSAL_NOT_HONORED | REVERSAL_NOT_COMPLETED | The ACH payment reversal was not completed and the funds were not sent back to the Buyer. Please call your Buyer for further information if needed. |