# Bankgiro Lookup

This guide shows you how to use our Bankgiro Lookup APIs, designed to provide enhanced data and pre-payment validation on top of our core APIs. These services enable you to build more reliable, user-friendly payment experiences by accessing and verifying additional information related to payment accounts. 

> Requests to the Bankgiro Lookup APIs require an [access token](get_access_token.md) with `scope` set to `paymentinitiation` `corporate`. 

##

### Get Creditor Name

This request allows you to fetch the creditor name linked to a Bankgiro or Plusgiro number before your PSU makes a payment to said creditor. It also verifies that the given OCR reference is valid for this creditor, ensuring that the payment is successfully initiated to the correct recipient.

#### Endpoint 

```http
POST /premium/v1/creditor-name
```

#### Query Parameters

| Name         | Type   | Description                                                     |
| ------------ | ------ | --------------------------------------------------------------- |
| `giroNumber` | string | A Swedish Bankgiro or Plusgiro number.                          |
| `giroType`   | string | The Swedish Giro type. `BANKGIRO` or `PLUSGIRO`.                |
| `ocrRef`     | string | A Giro OCR reference. Must be applied if `invoiceRef` is not.   |
| `invoiceRef` | string | A custom invoice reference. Must be applied if `ocrRef` is not. |

#### Request Headers

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

```bash
curl -X POST "https://api.openbankingplatform.com/premium/v1/creditor-name?giroNumber=1234-5678&giroType=BANKGIRO&ocrRef=1234567890" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-Request-ID: 3dff1f05-4c97-42c0-8bf0-8bacbb2f42f2" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680"
```

#### Response 

```json
{
  "creditorName": "Acme AB"
}
```

:::info

If the creditor account has OCR reference validation enabled and the provided OCR reference is invalid, the response will additionally include a warning message indicating the issue:

:::

```json
"tppMessages": [
  {
    "category": "WARNING",
    "code": "OCR_REF_INVALID",
    "text": "The provided OCR reference is invalid based on the creditor's OCR control requirements"
  }
]
```

### Get Giro Numbers

This request fetches Bankgiro numbers registered to a specific organisation, allowing you to identify and present valid accounts linked to your PSU's organisation.

#### Endpoint

```http
POST /premium/v1/giro-numbers
```

#### Query Parameters

| Name             | Type   | Description                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------ |
| `psuCorporateId` | string | The Corporate ID of the organisation for which to retrieve Giro numbers. |

#### Request Headers

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

```bash
curl -X POST "https://api.openbankingplatform.com/premium/v1/giro-numbers?psuCorporateId=5560160680" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-Request-ID: 3dff1f05-4c97-42c0-8bf0-8bacbb2f42f2" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680"
```

#### Response 

```json
{
  "giros": [
    {
      "giroNumber": "1234-5678",
      "giroType": "BANKGIRO",
      "name": "Acme AB"
    },
    {
      "giroNumber": "1234-5679",
      "giroType": "BANKGIRO",
      "name": "Acme"
    }
  ]
}
```