> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/api-reference-banks/resolve-account.md).

# Resolve Bank Account

Verify a bank account number and retrieve the account holder's name.

Resolves a bank account number to verify it exists and returns the account holder's name. Use this before initiating off-ramp transactions to confirm the recipient's identity.

## Endpoint

```
POST /v1/banks/account-resolution
```

## Authentication

Accepts either a merchant API key or a business-user JWT.

| Header          | Value                             |
| --------------- | --------------------------------- |
| `Authorization` | `<api_key>` **or** `Bearer <jwt>` |

## Request body

| Field           | Type   | Required | Description                                                                                          |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `accountNumber` | string | Yes      | Bank account number (numeric)                                                                        |
| `bankCode`      | string | Yes      | Bank code (from [List Banks](/ivorypay-on-off-ramp-documentation/api-reference-banks/list-banks.md)) |
| `currency`      | string | Yes      | Fiat currency code (any string accepted; downstream validation applies). Example: `NGN`.             |

## Example request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://ramp-api.ivorypay.io/api/v1/banks/account-resolution \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "2124586765",
    "bankCode": "000004",
    "currency": "NGN"
  }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://ramp-api.ivorypay.io/api/v1/banks/account-resolution", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountNumber: "2124586765",
    bankCode: "000004",
    currency: "NGN",
  }),
});

const data = await response.json();
console.log(data);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/banks/account-resolution",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "accountNumber": "2124586765",
        "bankCode": "000004",
        "currency": "NGN",
    },
)

print(response.json())
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"accountNumber": "2124586765",
		"bankCode":      "000004",
		"currency":      "NGN",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/banks/account-resolution", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}
```

{% endtab %}
{% endtabs %}

## Example response

```json
{
  "success": true,
  "message": "Query successful",
  "data": {
    "accountName": "OBIEKEZIE AMARACHI VALERIE",
    "accountNumber": "2124586765"
  }
}
```

## Response fields

| Field           | Type   | Description                          |
| --------------- | ------ | ------------------------------------ |
| `accountName`   | string | Name registered on the bank account  |
| `accountNumber` | string | The account number that was resolved |

## Sandbox behaviour

{% hint style="info" %}
Account resolution calls a live banking provider even in the sandbox (test) environment. The code samples above use a verified test account you can use directly:
{% endhint %}

| Field           | Value                        |
| --------------- | ---------------------------- |
| `accountNumber` | `2124586765`                 |
| `bankCode`      | `000004`                     |
| `bankName`      | UBA (United Bank for Africa) |
| `currency`      | `NGN`                        |

## Error cases

| Error code      | Description                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `ONOFFRAMP0033` | Invalid bank code — the `bankCode` doesn't match any supported bank                              |
| `ONOFFRAMP0088` | Unable to resolve bank account — account not found at the bank, or a live provider lookup failed |

## Best practices

1. **Always resolve before payout** — Call this endpoint before initiating off-ramp transactions to confirm the account details with your user
2. **Display the name** — Show the resolved `accountName` to your user for confirmation before proceeding
3. **Cache cautiously** — Account names can change. Re-resolve if the transaction is initiated significantly after resolution

***

> **For AI assistants:** This endpoint verifies a bank account. Required fields: `accountNumber` (numeric string), `bankCode` (from GET /v1/banks/:currency), `currency` (fiat code). Returns `accountName` and `accountNumber`.