# Balance API
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/balance-api/index.md

Alert: If you are a Customer contracted with MTS EU or MTS UK, please proceed to [Balance API Specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-balance-api/index.md) and [Balance API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-balance-api/index.md) respectively to ensure compliance with the relevant jurisdiction based Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2).

You can use this API to obtain account details including balances if you are contracted with a MTS legal entity and enabled for [prefunding settlement or collateral settlement](https://developer.mastercard.com/cross-border-services/documentation/api-ref/settlement-model/index.md).

## Environment Domains {#environment-domains}

#### Retrieve All Accounts and Balances {#retrieve-all-accounts-and-balances}

* Sandbox/MTF
* Production

```Sandbox/MTF
https://sandbox.api.mastercard.com/send/partners/{partner_id}/crossborder/accounts
```

```Production
https://api.mastercard.com/send/partners/{partner_id}/crossborder/accounts
```

#### Retrieve Account Balances by Account ID {#retrieve-account-balances-by-account-id}

* Sandbox
* Production

```Sandbox
https://sandbox.api.mastercard.com/send/partners/{partner_id}/crossborder/accounts/{account_id}
```

```Production
https://api.mastercard.com/send/partners/{partner_id}/crossborder/accounts/{account_id}
```

Note: **Sandbox** and **MTF** environments share the same url but are differentiated by partner id.

## API {#api}

[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-swagger.yaml)

### Retrieve All Accounts and Balances {#retrieve-all-accounts-and-balances-1}


API Reference: `GET /send/partners/{partner_id}/crossborder/accounts`

### Retrieve Account Balances by Account ID {#retrieve-account-balances-by-account-id-1}


API Reference: `GET /send/partners/{partner_id}/crossborder/accounts/{account_id}`

* **Formats supported** : JSON   
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :   
  content-type : Format of the inbound content being submitted. example: application/ json   
  content-length: Length of the inbound content body in octets.

## API Convention {#api-convention}

Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.

## Payload Encryption {#payload-encryption}

All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by Mastercard.   

For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md)

## Sandbox Testing {#sandbox-testing}

You can make API calls to the Sandbox server from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required OAuth 1.0a Authorization Header.
Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID.   
Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID.   
For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to a specific Customer; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, Customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Customer.

### Test cases {#test-cases}

The Sandbox server returns simulated, static responses.

#### Retrieve all Active Accounts {#retrieve-all-active-accounts}

You can use the following test cases to produce specific responses.

| Status  |                                         Test Case                                         |                                 Action                                 |
|---------|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| Success | Retrieve all active Accounts return message "Returned response with all active accounts". | Send request to Balance API with include_balance=false in the request. |

#### Retrieve all Active Accounts Balances {#retrieve-all-active-accounts-balances}

You can use the following test cases to produce specific responses.

| Status  |                                             Test Case                                             |                                Action                                 |
|---------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| Success | Retrieve reserved and available balances for all active accounts (queuedBalance is not included). | Send Request to Balance API with the include_balance=true in request. |

#### Retrieve Account Balances by Account Id {#retrieve-account-balances-by-account-id}

You can use the following test cases to produce specific responses.

|           Status            |                                                                                          Test Case                                                                                          |                                Action                                 |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| Success                     | Retrieve balances (other than queuedBalance) of Single Account by Account Id with balance included having return message "Returned response with active account number with all balances" . | Send request to Balance API with accountId.                           |
| Success for Prefund queuing | Retrieve balances of Single Account by Account Id with balance included having return message "Returned response with active account number with all balances including queuedBalance".     | Send request to Balance API with accountId acct_ssq                   |
| Rejected                    | Retrieve balances of Single Account by Account Id with Invalid Input value having return message "Rejected response Invalid Input Value with error code 082000".                            | Send request to Balance API with invalid accountId acct++@bc .        |
| Rejected                    | Retrieve balances of Single Account by Account Id with Invalid Input length having return message "Rejected response Invalid Input Length with error code 072000".                          | Send request to Balance API with input value more than 30 characters. |
| Rejected                    | Retrieve balances of Single Account by Error code having return message "Rejected response PROVIDER_NOT_ENABLED_PRE_FUND with error code 130192".                                           | Send request to Balance API with accountId ERR_130192.                |
| Rejected                    | Retrieve balances of Single Account by Error Code having return message "Rejected response SETTLEMENT_ACCOUNT_NOT_FOUND with error code 130193".                                            | Send request to Balance API with accountId ERR_130193.                |

## Sample Request {#sample-request}

### Retrieve all Active Accounts {#retrieve-all-active-accounts}

No Request body

### Retrieve all Active Accounts Balances {#retrieve-all-active-accounts-balances}

No Request body

### Retrieve Account Balances by Account Id {#retrieve-account-balances-by-account-id-2}

No Request body

## Sample Responses {#sample-responses}

### Retrieve all Active Accounts {#retrieve-all-active-accounts-1}

A few examples of successful Retrieve calls are provided below:

#### Successful Balance API Response : {#successful-balance-api-response-}

* JSON

```JSON
[
  {
    "accountId": "acct_1001",
    "accountState": "ACTIVE"
  },
  {
    "accountId": "acct_1002",
    "accountState": "ACTIVE"
  }
]
```

### Retrieve all Active Accounts Balances {#retrieve-all-active-accounts-balances-1}

A few examples of successful Retrieve calls are provided below:

#### Successful Balance API Response when not opted for Prefund queuing: {#successful-balance-api-response-when-not-opted-for-prefund-queuing}

* JSON

```JSON
[
  {
    "accountId": "acct_1001",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00-04:00",
    "balanceAsOfTimestamp": "2021-07-12T08:16:34-04:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "10000.75",
        "currency": "USD"
      },
      "processedAmount": {
        "amount": "2000.25",
        "currency": "USD"
      },
      "reservedBalance": {
        "amount": "100.00",
        "currency": "USD"
      },
      "availableBalance": {
        "amount": "8000.50",
        "currency": "USD"
      },
      "settlementAccountBalance":{
         "amount": "8100.50",
         "currency": "USD"
      },
      "thresholdAmount": {
        "amount": "100.00",
        "currency": "USD"
      }
    }
  },
  {
    "accountId": "acct_1002",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00+09:00",
    "balanceAsOfTimestamp": "2021-07-12T21:16:34+09:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "7000",
        "currency": "JPY"
      },
      "processedAmount": {
        "amount": "7600",
        "currency": "JPY"
      },
      "reservedBalance": {
        "amount": "100",
        "currency": "JPY"
      },
     "availableBalance": {
        "amount": "-600",
        "currency": "JPY"
      },
      "settlementAccountBalance":{
        "amount": "-500",
        "currency": "JPY"
      },
      "thresholdAmount": {
        "amount": "-1000",
        "currency": "JPY"
      }
    }
  },
  {
    "accountId": "acct_1003",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00+03:00",
    "balanceAsOfTimestamp": "2021-07-12T15:16:34+03:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "15000.570",
        "currency": "BHD"
      },
      "processedAmount": {
        "amount": "2000.230",
        "currency": "BHD"
      },
      "reservedBalance": {
        "amount": "100.170",
        "currency": "BHD"
      },
      "availableBalance": {
        "amount": "13000.340",
        "currency": "BHD"
      },
      "settlementAccountBalance":{
        "amount": "13100.510",
        "currency": "BHD"
      }
    }
  }
]
```

#### Successful Balance API Response when opted for Prefund queuing: {#successful-balance-api-response-when-opted-for-prefund-queuing}

* JSON

```JSON
[
  {
    "accountId": "acct_1001",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00-04:00",
    "balanceAsOfTimestamp": "2021-07-12T08:16:34-04:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "10000.75",
        "currency": "USD"
      },
      "processedAmount": {
        "amount": "2000.25",
        "currency": "USD"
      },
      "reservedBalance": {
        "amount": "100.00",
        "currency": "USD"
      },
      "availableBalance": {
        "amount": "8000.50",
        "currency": "USD"
      },
      "settlementAccountBalance":{
         "amount": "8100.50",
         "currency": "USD"
      },
      "queuedBalance": {
        "amount": "246.02",
        "currency": "USD"
      },
      "thresholdAmount": {
        "amount": "100.00",
        "currency": "USD"
      }
    }
  },
  {
    "accountId": "acct_1002",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00+09:00",
    "balanceAsOfTimestamp": "2021-07-12T21:16:34+09:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "7000",
        "currency": "JPY"
      },
      "processedAmount": {
        "amount": "7600",
        "currency": "JPY"
      },
      "reservedBalance": {
        "amount": "100",
        "currency": "JPY"
      },
     "availableBalance": {
        "amount": "-600",
        "currency": "JPY"
      },
      "queuedBalance": {
        "amount": "246.02",
        "currency": "USD"
      },
      "settlementAccountBalance":{
        "amount": "-500",
        "currency": "JPY"
      },
      "thresholdAmount": {
        "amount": "-1000",
        "currency": "JPY"
      }
    }
  },
  {
    "accountId": "acct_1003",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00+03:00",
    "balanceAsOfTimestamp": "2021-07-12T15:16:34+03:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "15000.570",
        "currency": "BHD"
      },
      "processedAmount": {
        "amount": "2000.230",
        "currency": "BHD"
      },
      "reservedBalance": {
        "amount": "100.170",
        "currency": "BHD"
      },
      "availableBalance": {
        "amount": "13000.340",
        "currency": "BHD"
      },
      "queuedBalance": {
        "amount": "246.02",
        "currency": "USD"
      },
      "settlementAccountBalance":{
        "amount": "13100.510",
        "currency": "BHD"
      }
    }
  }
]
```

### Retrieve Account Balances by Account Id {#retrieve-account-balances-by-account-id-3}

A few examples of successful Retrieve calls are provided below:

#### Successful Balance API Response when not opted for Prefund queuing: {#successful-balance-api-response-when-not-opted-for-prefund-queuing-1}

* JSON

```JSON
{
    "accountId": "acct_1001",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00-04:00",
    "balanceAsOfTimestamp": "2021-07-12T08:16:34-04:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "10000.75",
        "currency": "USD"
      },
      "processedAmount": {
        "amount": "2000.25",
        "currency": "USD"
      },
      "reservedBalance": {
        "amount": "100.00",
        "currency": "USD"
      },
      "availableBalance": {
        "amount": "8000.50",
        "currency": "USD"
      },
      "settlementAccountBalance":{
        "amount": "8100.50",
        "currency": "USD"
      },
      "thresholdAmount": {
        "amount": "100.00",
        "currency": "USD"
      }
    }
  }
```

#### Successful Balance API Response when opted for Prefund queuing: {#successful-balance-api-response-when-opted-for-prefund-queuing-1}

* JSON

```JSON
{
    "accountId": "acct_1001",
    "accountState": "ACTIVE",
    "openingBalanceTimestamp": "08:00:00-04:00",
    "balanceAsOfTimestamp": "2021-07-12T08:16:34-04:00",
    "balanceDetails": {
      "openingBalance": {
        "amount": "10000.75",
        "currency": "USD"
      },
      "processedAmount": {
        "amount": "2000.25",
        "currency": "USD"
      },
      "reservedBalance": {
        "amount": "100.00",
        "currency": "USD"
      },
      "availableBalance": {
        "amount": "8000.50",
        "currency": "USD"
      },
      "queuedBalance": {
        "amount": "246.02",
        "currency": "USD"
      },
      "settlementAccountBalance":{
        "amount": "8100.50",
        "currency": "USD"
      },
      "thresholdAmount": {
        "amount": "100.00",
        "currency": "USD"
      }
    }
  }
```

A few examples of Retrieve failures are provided below:

### Rejected Response With Error Code: {#rejected-response-with-error-code}

#### 1.Invalid Input Value: {#1invalid-input-value}

* JSON

```JSON
{
   "Errors": {
      "Error": {
         "RequestId": "7623048",
         "Source": "Additional Data-1200-Destination Service Tag",
         "ReasonCode": "INVALID_INPUT_VALUE",
         "Description": "Invalid Input Value",
         "Recoverable": "false",
         "Details": {
            "Detail": {
               "Name": "ErrorDetailCode",
               "Value": "082000"
            }
         }
      }
   }
}
```

#### 2.Invalid Input Length: {#2invalid-input-length}

* JSON

```JSON
{
   "Errors": {
      "Error": {
         "RequestId": "7623048",
         "Source": " ",
         "ReasonCode": "INVALID_INPUT_LENGTH",
         "Description": "Invalid Input Length",
         "Recoverable": "false",
         "Details": {
            "Detail": {
               "Name": "ErrorDetailCode",
               "Value": "072000"
            }
         }
      }
   }
}
```

#### 3.Provider Not Enabled Pre Fund: {#3provider-not-enabled-pre-fund}

* JSON

```JSON
{
   "Errors": {
      "Error": {
         "RequestId": "7623048",
         "Source": " ",
         "ReasonCode": "PROVIDER_NOT_ENABLED_PRE_FUND",
         "Description": "Provider Not Enabled Pre Fund",
         "Recoverable": "false",
         "Details": {
            "Detail": {
               "Name": "ErrorDetailCode",
               "Value": "130192"
            }
         }
      }
   }
}
```

#### 4.Settlement Account Not Found: {#4settlement-account-not-found}

* JSON

```JSON
{
  "Errors": {
    "Error": {
      "RequestId": "45736538",
      "Source": "",
      "ReasonCode": "SETTLEMENT_ACCOUNT_NOT_FOUND",
      "Description": "Settlement account not found",
      "Recoverable": "false",
      "Details": {
        "Detail": {
          "Name": "ErrorDetailCode",
          "Value": "130193"
        }
      }
    }
  }
}
```

## Error Codes {#error-codes}

Please refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md).

For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).