# API Reference source: https://developer.mastercard.com/automatic-billing-updater/documentation/api-reference/index.md ## Environment Domains {#environment-domains} * Sandbox * Production ```Sandbox https://sandbox.api.mastercard.com/ ``` ```Production https://api.mastercard.com/ ``` ## API Specifications {#api-specifications} API Specification: `https://static.developer.mastercard.com/content/automatic-billing-updater/swagger/ABURestAPI.yaml` #### Notes on API request parameters {#notes-on-api-request-parameters} | Parameter | Description | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `merchantId` | Valid identifier for the merchant or payment facilitator registered with ABU that is storing the payment account information Note: You must first register the merchant with ABU before making the API call. Populating this `merchantId` field in the API request call with an unrecognized merchant ID will result in an error. Details on merchant registration are available in the [ABU Reference Guide](https://techdocs.mastercard.com/bundle/m_MAB) on Mastercard Connect | | `accountNumber` | The primary account number (PAN) for the payment account being subscribed | | `expiryDate` | The expiration date associated with the account number | | `subMerchantId` | Valid identifier for registered ABU submerchant, if applicable. This field only applies for payment facilitators so that account updates can be obtained for your submerchants. Warning: Payment facilitators must register your customers (entities ultimately consuming the account lifecycle update and transacting on the payment account) with ABU as submerchants. You must first register the submerchant ID before making the API call. Populating this `subMerchantId` field in the API request call when the payment facilitator and/or the submerchant ID have not been registered with ABU will result in an error. Details on submerchant registration are available in the [ABU Reference Guide](https://techdocs.mastercard.com/bundle/m_MAB) on Mastercard Connect | | `ica` | A customer identifier assigned by Mastercard associated to the enrolled ABU customer | ### Push subscription model {#push-subscription-model} Note: The account you are subscribing to must not be expired. You will receive an error when subscribing to a PAN with an expiration date that is greater than 12 months old. You may choose to automatically receive account update notifications for payment credentials stored in your systems. To do this, you must subscribe to 'watch' an account. Notifications for all your subscribed accounts will then be sent via API to a designated endpoint whenever account updates are received from issuers. API Specification: `/swagger/ABU - Push API specification.yaml` Tip: The `requestId` data that you provide in the initial account subscription request will be reflected in notifications that ABU sends for this account. * This data can be used to trace which subscription request is associated with subsequent notifications received from ABU. * If the initial subscription request is made by a submerchant (i.e. it contains a `subMerchantId`), then `requestId` will be nested within the submerchant information. Otherwise ABU will return `requestId` at the merchant level. Alert: You must respond to a notifications API call from ABU with either HTTP status code 200 (OK) or 204 (No Content). Otherwise ABU will assume the request has failed and retry the API call. ##### Notifications API retry strategy {#notifications-api-retry-strategy} ###### Retry strategy for tokenized accounts {#retry-strategy-for-tokenized-accounts} In the event of failure to send an account notification for network tokens (i.e. when the subscribed account is a tokenized Mastercard Digital Enablement Service (MDES) credential), ABU will retry up to 8 times and terminate 48 hours (2 days) after the initial notification attempt. The times between retries are as follows: * 1st retry attempt: 1 second after initial notification attempt was not successful * 2nd retry attempt: 30 seconds after 1st retry * 3rd retry attempt: 60 seconds (1 minute) after 2nd retry * 4th retry attempt: 120 seconds (2 minutes) after 3rd retry * 5th to 8th retry attempts: 12 hours after each prior attempt ###### Retry strategy for non-tokenized accounts {#retry-strategy-for-non-tokenized-accounts} Generally, ABU will try to send the notification up to 3 times in quick succession. The time between retries is as follows: * **1st retry attempt:** 30 seconds after initial notification attempt was not successful * **2nd retry attempt:** 1 minute after 1st retry If after 3 attempts there is still no HTTP 200 status response, ABU will attempt to send the notification 3 more times beginning the following day at 10pm US Central time for a further 4 days. This means that ABU will make attempts to send the notification for a total of up to 5 days (for a total of up to 15 attempts). After the 3rd attempt on the 5th day, the notification is marked as a failure and will no longer be retried. ### Error responses {#error-responses} See error codes and responses [here](https://developer.mastercard.com/automatic-billing-updater/documentation/codes-and-formats/index.md). ## Sandbox Testing {#sandbox-testing} ABU supports your ABU API integration by providing mock responses to simulate ABU behavior for your API calls. You must be onboarded to ABU's test environment before you can receive mock responses from ABU at your defined client endpoints. Test cases and simulated responses can be found [here](https://developer.mastercard.com/automatic-billing-updater/documentation/testing/index.md).