# Quick Start Guide
source: https://developer.mastercard.com/automatic-billing-updater/documentation/abu-quick-start/index.md

## Overview {#overview}

Follow this guide to set up access to the ABU API, create and configure your Mastercard Developers project, obtain Sandbox credentials, and begin testing the integration. When ready, you can use the same project to request access to the Production environment.

### Notes {#notes}

The examples in this guide use Python. If you're integrating in another language, see Mastercard's [OAuth signing libraries and sample code on GitHub](https://github.com/Mastercard?q=oauth) for equivalents in other languages and frameworks.

## Checklist {#checklist}

| # |        Step         |                                    What to do                                    |
|---|---------------------|----------------------------------------------------------------------------------|
| 1 | Request Access      | Confirm eligibility and complete the required onboarding process for ABU access. |
| 2 | Log In              | Create or sign in to your Mastercard Developers account.                         |
| 3 | Project             | Create a Mastercard Developers project and obtain Sandbox credentials.           |
| 4 | Sandbox Integration | Generate and configure your API client for Sandbox testing.                      |
| 5 | Testing             | Test your implementation in the Sandbox environment.                             |
| 6 | Go Live             | Request Production access and download Production credentials.                   |

## Step 1: Request Access {#step-1-request-access}

Before creating a Mastercard Developers project, confirm that your organization is eligible to use the ABU API and complete any required onboarding activities.

### Who Can Use the ABU API? {#who-can-use-the-abu-api}

The ABU API is available only to registered Acquirers, Large Card-on-File/Recurring Payment Merchants and Payment Facilitators

#### Mastercard Acquirers {#mastercard-acquirers}

1. Submit a signed ABU customer form available on Mastercard Connect (Form 806).
2. Depending on your business requirements, you may use:
   * ABU bulk file requests
   * The ABU API
   * Both options

See the [ABU Program Guide](https://trc-techresource.mastercard.com/r/bundle/m_mab_en-us/page/d/en-US) on Mastercard Connect for additional information.

#### Large Credential-on-File/Recurring Payment Merchants and Payment Facilitators {#large-credential-on-filerecurring-payment-merchants-and-payment-facilitators}

1. Contact your acquirer about leveraging the ABU API through their existing ABU integration.
2. Alternatively, very large merchants and Service Providers may qualify for a direct ABU connection.
3. Contact your Mastercard representative for more information about this option.

### Check Available Resources {#check-available-resources}

In the meantime, review the resources available on Mastercard Developers to familiarize yourself with the ABU API:

1. [API Overview](https://developer.mastercard.com/automatic-billing-updater/documentation)
2. API Technical documentation, including:
   * [API Reference](https://developer.mastercard.com/automatic-billing-updater/documentation/api-reference/index.md)
   * [Security](https://developer.mastercard.com/automatic-billing-updater/documentation/api-basics/index.md)
   * [Use Cases](https://developer.mastercard.com/automatic-billing-updater/documentation/usecases/index.md)
   * [FAQs \& Support](https://developer.mastercard.com/automatic-billing-updater/documentation/support/index.md)

## Step 2: Create or Sign In to Your Mastercard Developers Account {#step-2-create-or-sign-in-to-your-mastercard-developers-account}

1. [Create a Mastercard Developers account](https://developer.mastercard.com/account/sign-up).
2. Validate your account by following the link sent to your email.
3. If you already have an account, [sign in](https://developer.mastercard.com/account/log-in) to Mastercard Developers.

## Step 3: Create a Project and Obtain Sandbox Credentials {#step-3-create-a-project-and-obtain-sandbox-credentials}

Create a Mastercard Developers project and obtain the credentials required to begin testing in the Sandbox environment.

### Create a Project {#create-a-project}

1. Go to your [My Projects](https://developer.mastercard.com/dashboard) page and click **Create new project**.

![abu-quick-start](https://static.developer.mastercard.com/content/automatic-billing-updater/documentation/images/CreateProject.png)

2. Enter a project name.
3. Select **Automatic Billing Updater (ABU)** as the API.
4. Invite members to your project as collaborators

### Project Credentials {#project-credentials}

5. On the Project Credentials page, create a key alias and keystore password for your OAuth keys, store them securely, and click **Create Project**.

![abu-project-credentials](https://static.developer.mastercard.com/content/automatic-billing-updater/documentation/images/ProjectCredentials.png)

6. Download the OAuth 1.0a key file and store it securely and click **Open Project**.

![abu-download-keys](https://static.developer.mastercard.com/content/automatic-billing-updater/documentation/images/DownloadKeys.png)

## Step 4: Sandbox Integration {#step-4-sandbox-integration}

### Generate Your Own API Client {#generate-your-own-api-client}

1. Open the [API Reference](https://developer.mastercard.com/automatic-billing-updater/documentation/api-reference/index.md).
2. Download the API specification (OpenAPI). ![abu-Download-APISpecs](https://static.developer.mastercard.com/content/automatic-billing-updater/documentation/images/DownloadSpecs.png)
3. Generate and configure an API client for the ABU API.
4. Configure your client using our client libraries.

Mastercard uses OAuth 1.0a to authenticate your application. Mastercard provides [client authentication libraries](https://github.com/Mastercard?q=oauth) in several languages that you can integrate into your project or use as reference OAuth 1.0a implementations.

This guide uses Python to demonstrate how to use the Mastercard authentication library. For other languages, follow the README files on GitHub.

1. Install the `oauth signer` and the Python `requests` library using `pip`, via your command terminal:

   ```cmd
   pip install mastercard-oauth1-signer requests
   ```

2. Create a Python file called `ABU.py`. Once the file is created, add the following imports:

   ```python
   import requests
   from requests.auth import AuthBase

   import oauth1.authenticationutils as authenticationutils
   from oauth1.signer import OAuthSigner
   ```

3. Create a helper class using `AuthBase` from the `Requests` library that automatically signs all of the HTTP requests we send:

   ```python
   # MCSigner
   # Helper class for signing request objects
   class MCSigner(AuthBase):
       def __init__(self, consumer_key, signing_key):
           self.signer = OAuthSigner(consumer_key, signing_key)

       def __call__(self, request):
           self.signer.sign_request(request.url, request)
           return request
   ```

4. Use the `load_signing_key` function to create a signing key using the .p12 key file that you downloaded from Mastercard Developers and your keystore password:

   ```python
   signing_key = authenticationutils.load_signing_key('./path/to/projectname-sandbox.p12', 'keystorepassword')
   ```

5. Use the `MCSigner` helper class to create our HTTP request signer using the consumer key of your Mastercard Developers project:

   ```python
   base_url = 'https://sandbox.api.mastercard.com/abu/accounts/inquiries' # URL for ABU Pull Static Sandbox
   consumer_key = 'consumer key'
   signer = MCSigner(consumer_key, signing_key)
   ```

We now have everything we need to authenticate a request.

## Step 5: Testing {#step-5-testing}

ABU provides a **static Sandbox environment** that returns predefined mock responses to simulate ABU behavior. During testing, the response returned by the API is determined by the `accountNumber` (PAN) included in the request.

Different test PAN values generate different responses, allowing you to validate how your integration handles each possible ABU account update reason code.

#### Test Making an Account Inquiry {#test-making-an-account-inquiry}

Making a test account inquiry is the simplest way to validate your ABU integration because it does not require onboarding to the Push subscription service or configuring an endpoint. Once your Sandbox project has been created and your API client is authenticated, you can begin testing immediately using the ABU static Sandbox environment.
Because the Sandbox is static, the response returned is determined by the `accountNumber` included in the request.

##### Endpoint {#endpoint}

    POST https://sandbox.api.mastercard.com/abu/accounts/inquiries

##### Example Request {#example-request}

The following example uses a Sandbox test PAN that returns an account expiration date update.

```json
{
 "requestId": "323e304f-1cfc-4f0d-ac07-e6037ce09925",
 "customer": {
 "ica": "1111",
 "merchantId": "000000000002535",
 "subMerchantId": "000000000000001"
 },
 "account": {
 "accountNumber": "5573491171027315",
 "expiryDate": "1228"
 }
}
```

##### Example Response {#example-response}

```json
{
 "account": {
 "accountNumber": "5573491171027315",
 "expiryDate": "1229"
 },
 "responseIndicator": "EXPIRY"
}
```

In this example, ABU returns an `EXPIRY` response indicator, indicating that the account expiration date has changed. The updated expiration date is returned in the response payload.

##### Make your first call {#make-your-first-call}

The following script combines the signing setup from Step 4 with the request above, so you can run your first Sandbox call in one step. Replace the keystore path, the keystore password, the consumer key, and the `ica` and `merchantId` values with your own, then run it.

```python
import requests
from requests.auth import AuthBase

import oauth1.authenticationutils as authenticationutils
from oauth1.signer import OAuthSigner


class MCSigner(AuthBase):
    def __init__(self, consumer_key, signing_key):
        self.signer = OAuthSigner(consumer_key, signing_key)

    def __call__(self, request):
        self.signer.sign_request(request.url, request)
        return request


signing_key = authenticationutils.load_signing_key('./path/to/projectname-sandbox.p12', 'keystorepassword')
signer = MCSigner('your consumer key', signing_key)

url = 'https://sandbox.api.mastercard.com/abu/accounts/inquiries'
payload = {
    "requestId": "323e304f-1cfc-4f0d-ac07-e6037ce09925",
    "customer": {
        "ica": "1111",
        "merchantId": "000000000002535",
        "subMerchantId": "000000000000001"
    },
    "account": {
        "accountNumber": "5573491171027315",
        "expiryDate": "1228"
    }
}

response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'}, auth=signer)

print(response.status_code)
print(response.json())
```

A successful first call prints HTTP status code `200` followed by the response payload shown above, where `responseIndicator` is `EXPIRY`. If you receive a `401` instead, check your consumer key and keystore password. See [Error Codes and Payload Formats](https://developer.mastercard.com/automatic-billing-updater/documentation/codes-and-formats/index.md) for the full list of reason codes.

#### Push Testing {#push-testing}

ABU also provides mock data for Push notifications. Before Push testing can begin, your organization must be onboarded to the ABU service.

For a complete walkthrough of Sandbox testing, see the [Sandbox Testing Tutorial](https://developer.mastercard.com/automatic-billing-updater/documentation/testing/).

## Step 6: Go Live {#step-6-go-live}

After you have completed testing in the static Sandbox environment you are ready to go live.

1. Within your ABU project, select **Request Production Access**.
2. Enter your Key Alias and Keystore Password.
3. Save your Key Alias and Keystore Password for future reference.
4. (Optional) Upload an existing CSR
5. Confirm and download your Production Keys

Note: Production Keys are generated instantaneously, but they still need to be approved for production environment access before you can go live. Once your production access request has been reviewed, you will receive a notification confirming your access has been approved or denied.

## Expected Timelines {#expected-timelines}

|                                    ABU Implementation Activity                                    | Estimated Timeline |
|---------------------------------------------------------------------------------------------------|--------------------|
| Execute ABU Customer Form                                                                         | 3 business days    |
| Assign Customer Implementation Manager                                                            | 2 to 3 weeks       |
| Set up customer identifier and configuration parameters in the ABU test environment (Sandbox/MTF) | 2 to 3 weeks       |
| Create API cryptographic keys and develop API integration                                         | Customer dependent |
| Test API connectivity                                                                             | Customer dependent |
| Set up customer identifier and configuration parameters in the Production environment             | 2 to 3 weeks       |

Note: Implementation activities marked as **Customer dependent** vary based on the customer's internal development, testing, and deployment timelines.

## Escalation Paths {#escalation-paths}

If your production access request is delayed or you need assistance at any stage:

* **Primary Support** : contact the ABU Onboarding Team at [abu_onboarding@mastercard.com](mailto:abu_onboarding@mastercard.com)
* **Your Mastercard Representative**: if you have an assigned Account Manager, contact them directly for priority escalation.

<br />

Include your project name, CID, and a description of the issue when reaching out.

## Next Steps {#next-steps}

### Error Codes \& Payload Formats {#error-codes--payload-formats}

Understand the response codes and payload formats returned by ABU.
[Learn more →](https://developer.mastercard.com/automatic-billing-updater/documentation/codes-and-formats/index.md)

### Security \& Authentication {#security--authentication}

Learn how to authenticate and securely connect to the ABU API.
[Learn more →](https://developer.mastercard.com/automatic-billing-updater/documentation/api-basics/index.md)

### Sandbox Testing {#sandbox-testing}

Explore supported test PANs, expected responses, and account update reason codes.
[Learn more →](https://developer.mastercard.com/automatic-billing-updater/documentation/testing/index.md)

### API Reference {#api-reference}

Review endpoint definitions, request schemas, and response models.
[Learn more →](https://developer.mastercard.com/automatic-billing-updater/documentation/api-reference/index.md)