# Account to account payment instruction source: https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/a2a-tutorial/index.md ## How account to account (A2A) payments work {#how-account-to-account-a2a-payments-work} 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. This tutorial will show you the end-to-end flow of an account to account (A2A) payment instruction. > > #### What you will learn {#what-you-will-learn} > > * 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-supplier-payment-agent/uploads/paymentinstruction.png "Payment Instruction Flow") #### Remittance data structure {#remittance-data-structure} ![Remittance data structure](https://static.developer.mastercard.com/content/mastercard-supplier-payment-agent/uploads/remittanceinformation.png "Remittance Information Flow") ## What you will achieve {#what-you-will-achieve} At the end of this tutorial you will create and process an A2A payment instruction from end-to-end. ## Next steps {#next-steps} Click **Next** to get started. ## Buyer Payment Agent submits the payment instruction request {#buyer-payment-agent-submits-the-payment-instruction-request} There is no action required for the Supplier Payment Agent at this step. However, you should review the [local instruments](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/a2a-tutorial/index.md#local-instruments) associated with each ISO country code and payment method. A local instrument is a specific type of payment accepted in a given country. Note: Steps 3, 4, 7, and 8 are applicable to the Supplier Payment Agent for receiving a payment instruction and updating the payment status. The Buyer Payment Agent initiates a payment instruction request and can indicate that the payment instruction should be considered for supply chain finance by including a value for the `ipu` and `requestedExecutionDate` fields. Diagram submita2a1 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 instruction with the credit transfer (TRF) value for `paymentMethod`. ## Local instruments {#local-instruments} 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 | Transaction is related to corporate trade exchange. | USD | NACHA | | US | TRF | RTP | US Instant Credit Transfer | 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 | Transaction is related to an Instant Credit Transfer. Use case example: SEPA Instant Credit Transfer (SCT Inst) | EUR | SEPA | | GB | TRF | FPS | UK Instant Credit Transfer | Transaction is related to an Instant Credit Transfer. | GBP | FPS | | AU | TRF | BECS | Bulk Electronic Clearing System | Bulk Electronic Clearing System | AUD | BECS | #### Click Next. {#click-next} ## Business Payment Service validates the payment instruction request against the Supplier payment preferences {#business-payment-service-validates-the-payment-instruction-request-against-the-supplier-payment-preferences} There is no action required for the Supplier Payment Agent at this step. Business Payment Service validates the payment instruction against the Supplier payment preferences. If the payment instruction is rejected, then Business Payment Service sends the payment instruction status update notification to the Buyer Payment Agent. Diagram submita2a2 #### Click Next. {#click-next-1} ## Business Payment Service sends the payment instruction request to the Supplier Payment Agent {#business-payment-service-sends-the-payment-instruction-request-to-the-supplier-payment-agent} Business Payment Service sends the payment instruction to the Supplier Payment Agent to request the Supplier bank account information. Diagram submita2a3 ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step} Business Payment Service sends the payment instruction as an event notification. A sample payment instruction event notification looks like: * JSON ```JSON { "eventId": "459a7g1a-0b8a-43b9-b35d-6489e6d54891", "eventType": "PAYMENT_RECEIVED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "buyerId": "contoso.corp.pay@track", "supplierId": "acme.east@track", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "instructedAmount": { "amount": 2200.5, "currency": "USD" }, "tax": { "totalTaxAmount": 200.5 }, "remittanceInformation": { "structured": [ { "referredDocumentInformation": [ { "number": "3521264364", "type": "CINV", "relatedDate": "2020-07-16", "paymentDueDate": "2020-08-16", "lineDetails": [ { "identifications": [ { "number": "5489549615", "type": { "code": "ASNB", "proprietary": "" }, "relatedDate": "2020-06-20" } ], "quantity": 1, "unitofMeasure": "EA", "description": "Sample Item", "amount": { "duePayableAmount": 3000, "discountAppliedAmounts": [ { "type": { "code": "TDMS", "proprietary": "" }, "amount": 500 } ], "taxAmounts": [ { "type": { "code": "STAT", "proprietary": "" }, "amount": 200.5 } ], "adjustmentAmountsandReasons": [ { "amount": 100, "creditDebitIndicator": "DBIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 2600.5 } } ], "referredDocumentAmount": { "duePayableAmount": 3000, "discountAppliedAmounts": [ { "type": { "code": "TMDS", "proprietary": "" }, "amount": 500 } ], "taxAmounts": [ { "type": { "code": "STAT", "proprietary": "" }, "amount": 200.5 } ], "adjustmentAmountsandReasons": [ { "amount": 100, "creditDebitIndicator": "DBIT", "reason": "DAMAGED_GOODS" } ], "remittedAmount": 2100.5 } } ], "supplierReferenceInformation": { "type": { "code": "SCOR", "proprietary": "" }, "issuer": "ISO", "reference": "RF18 5390 0754 7034" }, "invoicer": { "name": "ACME Inc.", "organisationIdentification": [ { "identification": "82-2981873", "type": "TXID" } ] }, "invoicee": { "name": "Contoso Inc.", "organisationIdentification": [ { "identification": "02-0794278", "type": "TXID" } ] }, "additionalRemittanceInformation": [ "Data1:abc", "Data2:xyz", "Data3:lmn", "DataN:nnn" ] }, { "referredDocumentInformation": [ { "number": "3521264364", "type": "CREN", "relatedDate": "2020-07-16", "paymentDueDate": "2020-08-16", "lineDetails": [ { "identifications": [ { "number": "5489549615", "type": { "code": "ASNB", "proprietary": "" }, "relatedDate": "2020-06-20" } ], "amount": { "creditNoteAmount": 500 } } ], "referredDocumentAmount": { "creditNoteAmount": 500 } } ], "supplierReferenceInformation": { "type": { "code": "SCOR", "proprietary": "" }, "issuer": "ISO", "reference": "RF18 5390 0754 7034" }, "invoicer": { "name": "ACME Inc.", "organisationIdentification": [ { "identification": "82-2981873", "type": "TXID" } ] }, "invoicee": { "name": "Contoso Inc.", "organisationIdentification": [ { "identification": "02-0794278", "type": "TXID" } ] }, "additionalRemittanceInformation": [ ":/:<200>", ":/:<200>" ] } ] }, "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-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 will submit A2A payment instructions with the credit transfer (TRF) value for `paymentMethod`. ## 2. Review the error codes associated with this step. {#2-review-the-error-codes-associated-with-this-step} You may receive one of the following statuses from Business Payment Service throughout the payment lifecycle. | Status | Description | Usage | |-----------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ACCEPTED | Payment instruction is Accepted by Business Payment Service based on the Supplier's Payment preferences. | Business Payment Service sends this status to the Supplier Payment Agent when the payment instruction complies with the Supplier Payment preferences. | | ACCEPTED with WARNING | Payment instruction is conditionally Accepted by Business Payment Service based on the Supplier's Payment preferences. | Business Payment Service sends this status to the Supplier Payment Agent when the payment instruction does not fully comply with the Supplier Payment preferences. The payment instruction still flows through the payment instruction lifecycle. Specific WARNING reason codes are listed in the Payment preference Violation Reason Codes table. | If the Buyer Payment Agent submits payment instruction that violate your Supplier's payment preferences, the payment instruction may be rejected. If the Buyer Payment Agent receives a warning instead of a rejection the Supplier Payment Agent also receives one of the following warning reason codes. Note: The warning messages do not impact 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. | | RTP_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. | | TRF_WARNING | This transaction is in transit. `Supplier ID` flags all TRF transactions. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | NO_CUSTOMER_NUMBER_WARNING | This transaction is in transit. Supplier `Supplier ID` flags payments which do not include Customer Numbers for all invoices when making `Payment Method` payments. | | CUSTOMER_NUMBER_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions from customer account number `Customer Number`. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | MAX_INSTRUCTED_AMT_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions that exceed the maximum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MIN_INSTRUCTED_AMT_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions less than the minimum instructed amount allowed. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | BUYER_ID_WARNING | This transaction is in transit. `Supplier ID` flags all `Payment Method` transactions from `Buyer ID`. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | PERCENT_WARNING | This transaction is in transit. `Supplier ID` flags `Payment Method` payments that do not include a `Fee Amount Percentage %` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | FLAT_AMOUNT_WARNING | This transaction is in transit. `Supplier ID` flags `Payment Method` payments that do not include a `Fee Amount Dollar $` charge. The transaction will be reviewed by the Supplier for acceptance and the status updated accordingly. | | MAX_DAYS_AFTER_RELATED_DATE_WARNING | This transaction is in transit. `` flags `` payments that are made later than `<# of Days After Invoice Date>` calendar days after the related date of the referred document for acceptance due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | FEE_PERCENT_DAYS_AFTER_INVOICE_WARNING | This transaction is in transit. `` flags `` payments include a `` fee when sent `<# of Days After Invoice Date>` calendar days after the invoice date due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | FEE_FLAT_DAYS_AFTER_INVOICE_WARNING | This transaction is in transit. `` flags `` payments include a `` fee when sent `<# of Days After Invoice Date>` calendar days after the invoice date due to a payment control violation. The transaction will be delivered to the Supplier for acceptance and the status updated accordingly. | | NO_RELATED_DATE_WARNING | This transaction is in transit. Supplier `` flags payments which do not include related dates for all invoices when making `` payments. | #### Click Next. {#click-next-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} Diagram submita2a4 ## 1. Create the payment instruction update request. {#1-create-the-payment-instruction-update-request} Alert: The Mastercard assigned ICA is used for agent identification in all service requests for core operations. A customer service provider can use their API credentials to transact on behalf of a customer by providing their customer's ICA number in the request. Direct payment agents can still transact by entering their own ICA when sending a transaction to Mastercard Track™ Business Payment Service. API Reference: `PUT /supplier-payment-agents/{ica}/payment-instructions/{transaction_id}/bank-account-details` Note: The Supplier Payment Agent can continue to update the bank account details for a future dated payment instruction when the payment instruction status is PENDING. An example payment instruction rejection looks like: * JSON ```JSON { "status": "REJECTED", "statusReasonInformation": [ { "reasonCode": "INVALID_INVOICE_DATA", "description": "Transaction is rejected. One or more invoices include information that creates a reconciliation mismatch for the accepting Supplier Payment Agent." } ] } ``` An example unencrypted JSON payload for SEPA looks like: * JSON ```JSON { "supplierBankAccount": { "supplierAccount": { "identification": "BE68539007547034", "schemeName": "IBAN", "accountType": "CACC", "currency": "USD", "name": "Corporate Name Inc" }, "supplierBank": { "financialInstitutionIdentification": { "name": "Bank of America", "bicfi": "BOFIIE2DXXX", "clearingSystemMemberIdentification": { "clearingSystemIdentification": " ITNCC", "memberIdentification": "21212123321" } } } } } ``` When using `localInstrument` with TRF as the `paymentMethod`, either use a business identifier code for financial institutions (BICFI) or one of the following clearing system identifications. | Clearing system identification | Description | Local instrument | Region | |--------------------------------|-----------------------------------------------------------------------------------------|---------------------|--------| | AUBSB | Australian Bank State Branch Code (BSB) | BECS | WHEM | | GBDSC | UK Domestic Sort Code | FPS | EMEA | | USABA | United States Routing Number Fedwire NACHA | CCD CTX RTP | WHEM | | Existing validations | Overnight Payment With Extended Remittance information Same Day Instant Credit Transfer | ONCL PERI SDCL INST | EMEA | ## 2. Review the error codes associated with the request. {#2-review-the-error-codes-associated-with-the-request} You may receive one of the following statuses from Business Payment Service throughout the payment lifecycle. | 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 you opt to reject the payment instruction, you must also include one of the following reason codes: | Status | Description | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SUPPLIER_ACCT_NOT_FOUND | Unable to find an updated and accurate account number for theSupplier | | ACCOUNT_CLOSED | The supplier's account has been closed. | | SUPPLIER_SYSTEM_DOWN | Unable to find an updated and accurate account number for theSupplier. | | NO_PARTIAL_PAYMENT | Supplier `` will not accept partial payments at this time. | | ALT_MOP | Transaction `` has failed, `` needs to use an alternative method of payment for transacting to ``. | | ALT_MOP_NOT_BPS | Transaction `` has failed, `` does not accept BPS payment from this ``. | | UNSUPPORTED_CURRENCY_BY_SUPPLIER | `` has failed, the Supplier does not accept the selected currency. | | INVOICE_NOT_SUPPORTED | Transaction `` is rejected. The accepting Supplier Payment Agent does not support one or more invoices. | | INVALID_INVOICE_DATA | Transaction `` is rejected. One or more invoices include information that creates a reconciliation mismatch for the accepting Supplier Payment Agent. | | INVALID_CREDIT_NOTE_DATA | Transaction `` is rejected. One or more credit notes include information that creates a reconciliation mismatch for the accepting Supplier Payment Agent. | When providing bank account details to Business Payment Service, you may receive one of the following error messages if you submit a request with missing or invalid information. | Error code | Description | |----------------------------------------|---------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit. | | NO_ACCOUNT_NUMBER | Enter a valid bank account number. | | INVALID_BANK_ACCOUNT_ID | Invalid bank account identification, the length is restricted to 17 for US ACH. | | INVALID_BANK_ACCOUNT_ID | Invalid bank account identification, the length is restricted to 34 for US RTP. | | NO_SCHEME_NAME | Enter a valid account identification scheme. | | INVALID_SCHEME_NAME | Invalid scheme name, the value must match the valid value list. | | NO_ACCOUNT_TYPE | Enter a valid account number Type. | | INVALID_ACCOUNT_TYPE | Account Number Type is Invalid. | | NO_ACCOUNT_CURRENCY | Enter a valid account currency in ISO 4217 3-Alpha format. | | INVALID_CURRENCY_CODE | Invalid Currency Code | | NO_ACCOUNT_HOLDER_NAME | Enter a valid account holder name. | | NO_BANK_IDENTIFICATION | Enter Bank Identification. | | NO_SUPPLIER_BANK_NAME | Enter a Bank Name. | | NO_CLEARING_SYSTEM_IDENTIFICATION | Enter a clearing system identification. | | INVALID_CLEARING_SYSTEM_IDENTIFICATION | Invalid Clearing System Identification. | | NO_ROUTING_NUMBER | Enter a member identification/routing number. | | INVALID_ROUTING_NUMBER | Routing Number is Invalid | #### Click Next. {#click-next-3} ## Business Payment Service sends the payment instruction with the Supplier's bank account details and 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-suppliers-bank-account-details-and-business-payment-service-generated-end-to-end-id-to-the-buyer-payment-agent-to-process-the-payment} There is no action required for the Supplier Payment Agent at this step. Diagram submita2a5 #### Click Next. {#click-next-4} ## The Buyer Payment Agent updates the payment instruction status {#the-buyer-payment-agent-updates-the-payment-instruction-status} There is no action required for the Supplier Payment Agent at this step. However, if the Buyer Payment Agent cancels, requests reversal, or the payment instruction fails on the rails, review the optional steps below. Diagram submita2a6 ## 1. Optional: Payment instruction cancellation, failure, and reversal {#1-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 ## 1.1. Optional: Cancel a payment instruction after receiving bank account details {#11-optional-cancel-a-payment-instruction-after-receiving-bank-account-details} The Buyer Payment Agent can opt to cancel the payment instruction after updating the payment instruction with bank account details. The workflow for cancelling a payment instruction when the Buyer Payment Agent updates the payment instruction status, looks like: Diagram cancela2astep6 If the Buyer Payment Agent cancels the payment instruction, the Supplier Payment Agent is notified. 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." A sample event notification for a cancelled payment instruction looks like: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "PAYMENT_CANCELLED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "CANCELLED", "statusReasonInformation": [ { "reasonCode": "CANCELLED_BY_BUYER_AGENT", "description": "Please contact the Buyer for more information." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 1.2. Optional: Payment instruction failure {#12-optional-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. Diagram a2apaymentfailstep6 A sample event notification for a payment failure on the rails looks like: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "PAYMENT_FAILED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "PAYMENT_FAILED", "statusReasonInformation": [ { "reasonCode": "ACCOUNT_ISSUES", "description": "Please contact the Buyer for more information." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ``` ## 1.3. Optional: Request a payment reversal after receiving the SUBMITTED status {#13-optional-request-a-payment-reversal-after-receiving-the-submitted-status} The workflow for requesting an ACH payment instruction reversal at this step, when the Buyer Payment Agent updates the payment instruction status, looks like: Diagram a2areversalstep6 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 receives the REVERSAL_NOT_ALLOWED error code with the description "Reversal is not allowed for transactions where ipu value is true and requestedExecutionDate is in future." A sample event notification for an ACH payment instruction reversal looks like: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_REQUESTED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": " ii7ITHdCGZpcDYv", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "REVERSAL_REQUESTED", "statusReasonInformation": [ { "reasonCode": "ERRONEOUS_PAYMENT", "description": "The Buyer initiated a reversal of funds. Please contact your Buyer for further information if needed." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
When the reversal is completed, you will receive the following event notification: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_COMPLETED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "REVERSAL_COMPLETED", "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
If the reversal is not completed, you will receive the following event notification: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_NOT_COMPLETED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "ACH", "status": "REVERSAL_NOT_COMPLETED", "statusReasonInformation": [ { "reasonCode": " REVERSAL_NOT_HONORED ", "description": " 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." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
## 2. Review the reason codes associated with cancellation, payment failure, and payment reversals. {#2-review-the-reason-codes-associated-with-cancellation-payment-failure-and-payment-reversals} If the Buyer Payment Agent updates the status of an A2A payment to `CANCELLED`, `PAYMENT_FAILED`, or `REVERSAL_REQUESTED`, you may receive one of the following reason codes in the event notification: | 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 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. | #### 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} Diagram submita2a7 ## 1. Review the sample event notification associated with this step. {#1-review-the-sample-event-notification-associated-with-this-step-1} If the Buyer Payment Agent marks the account to account (A2A) payment instruction as `PAYMENT_FAILED`, you will receive an event notification indicating the reason for the failure. A sample status update event notification for this step looks like: * JSON ```JSON { "eventId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "eventType": "PAYMENT_STATUS_UPDATED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "PAYMENT_INITIATED", "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 payment instructions with 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. Review the codes associated with this step. {#2-review-the-codes-associated-with-this-step} You may receive one of the following status codes from Business Payment Service. | Status | Method | Local instrument | Description | |--------------------|--------|-------------------------------------------------|----------------------------------------------------------| | PAYMENT_INITIATED | TRF | BECS, CCD, CTX, ONCL, PERI, and SDCL | Payment is initiated by Buyer Payment Agent. | | PAYMENT_DELIVERED | TRF | FPS, RTP, and INST | Payment is delivered by Buyer Payment Agent. | | CANCELLED | TRF | CCD, CTX, ONCL, PERI, INST, SDCL, BECS, and FPS | Payment is cancelled by 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 Buyer Payment Agent. | If the Buyer Payment Agent updates the status of an A2A payment to `PAYMENT_FAILED`, you may receive one of the following reason codes in the event notification: | Reason code | Status | Description | |----------------|--------------------------------------------------------|------------------------------------------------| | ACCOUNT_ISSUES | PAYMENT_FAILED, REVERSAL_REQUESTED, REVERSAL_COMPLETED | Please contact the Buyer for more information. | #### Click Next. {#click-next-6} ## The Supplier Payment Agent reconciles the payment instruction and updates the status to FUNDS_RECEIVED or FUNDS_NOT_RECEIVED {#the-supplier-payment-agent-reconciles-the-payment-instruction-and-updates-the-status-to-funds_received-or-funds_not_received} Diagram submita2a8 ## 1. Reconcile the payment outside of Business Payment Service. {#1-reconcile-the-payment-outside-of-business-payment-service} This activity happens outside of Business Payment Service. Once the payment is reconciled, return to Business Payment Service to complete the remaining steps. ## 2. Update the payment instruction status to FUNDS_RECEIVED or FUNDS_NOT_RECEIVED. {#2-update-the-payment-instruction-status-to-funds_received-or-funds_not_received} Alert: The Mastercard assigned ICA is used for agent identification in all service requests for core operations. A customer service provider can use their API credentials to transact on behalf of a customer by providing their customer's ICA number in the request. Direct payment agents can still transact by entering their own ICA when sending a transaction to Mastercard Track Business Payment Service. API Reference: `PUT /supplier-payment-agents/{ica}/payment-instructions/{transaction_id}` Possible requests for this call are: * JSON ```JSON { "status": "FUNDS_NOT_RECEIVED", "statusReasonInformation": [ { "reasonCode": "SUPPLIER_NO_RECEIPT_OF_FUNDS", "description": "Contact the Supplier directly to obtain more details" } ] } ``` * JSON ```JSON { "status": "FUNDS_RECEIVED", "settlementTimeIndication": { "creditDateTime": "2020-08-17T17:37:23.230Z" } } ``` ## 3. Review the error codes associated with this step. {#3-review-the-error-codes-associated-with-this-step} When updating the A2A payment instruction in steps 4 and 8, you need to include one of the following status codes. | 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 `FUNDS_NOT_RECEIVED` is used, you must also include the following status reason code: | Reason code | Description | |------------------------------|-------------------------------------------------------| | SUPPLIER_NO_RECEIPT_OF_FUNDS | Contact the Supplier directly to obtain more details. | After you process an A2A payment outside of Business Payment Service, you are required to update the status of the payment. You may receive one or more of the following: | Error code | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_TRANSACTION_ID | Invalid Transaction ID, Transaction does not exist. Please check the ID and resubmit. | | NO_STATUS | Missing payment instruction status. | | INVALID_STATUS | Payment Instruction status is not valid | | NO_REASON_CODE | Missing Reason Code | | INVALID_SETTLEMENT_DATETIME | Invalid date time format, the settlement date time must be expressed in UTC time format (YYYY-MM-DDThh:mm:ss.sssZ) | | 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-7} ## Business Payment Service sends the reconciliation payment instruction status to the Buyer Payment Agent {#business-payment-service-sends-the-reconciliation-payment-instruction-status-to-the-buyer-payment-agent} There is no action required for the Supplier Payment Agent at this step. Diagram submita2a9 ## 1. Optional: Request a payment reversal after receiving FUNDS_RECEIVED status. {#1-optional-request-a-payment-reversal-after-receiving-funds_received-status} The Buyer Payment Agent can request a payment instruction reversal for CCD and CTX local instruments at this step. The workflow for requesting an ACH payment instruction reversal at this step, 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 receives the REVERSAL_NOT_ALLOWED error code with the description "Reversal is not allowed for transactions where ipu value is true and requestedExecutionDate is in future." A sample event notification for an ACH payment instruction reversal looks like: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_REQUESTED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": " ii7ITHdCGZpcDYv", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "REVERSAL_REQUESTED", "statusReasonInformation": [ { "reasonCode": "ERRONEOUS_PAYMENT", "description": "The Buyer initiated a reversal of funds. Please contact your Buyer for further information if needed." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
When the reversal is completed, you will receive the following event notification: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_COMPLETED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "TRF", "paymentTypeInformation": { "localInstrument": "CCD" }, "status": "REVERSAL_COMPLETED", "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
If the reversal is not completed, you will receive the following event notification: * JSON ```JSON { "eventId": "046b6c7f-0b8a-43b9-b35d-6489e6daee91", "eventType": "REVERSAL_NOT_COMPLETED", "eventCreatedDate": "2020-02-13T11:32:28Z", "data": { "transactionId": "459a7g1a-0b8a-43b9-b35d-6489e6daee91", "endToEndId": "6489e6daee91", "paymentMethod": "ACH", "status": "REVERSAL_NOT_COMPLETED", "statusReasonInformation": [ { "reasonCode": " REVERSAL_NOT_HONORED ", "description": " 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." } ], "createdDate": "2020-02-13T11:32:28Z", "updatedDate": "2020-02-13T11:32:28Z" } } ```
## 2. Review the reason codes associated with payment reversal requests. {#2-review-the-reason-codes-associated-with-payment-reversal-requests} If the Buyer Payment Agent updates the status of an A2A payment to `REVERSAL_REQUESTED`, you may receive one of the following reason codes in the event notification: | 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. |