Account validation utilities

Reduce payment failures by validating customer bank details before submitting RTP or payout requests. Safepay exposes two utility endpoints under your aggregator:

Endpoint	Purpose	Key request parameters
GET /title-fetch	Returns the registered account title for a Raast IBAN.	`iban` (query)
GET /title-fetch/v2	Returns the registered account title for a conventional account number.	`account_number`, `bank_name` (query)
GET /account-info	Retrieves metadata for an IBAN or alias, optionally combining title fetch.	`iban` or `alias_*` params; `with_title_fetch` flag

Call these endpoints before RTP or payout operations to ensure the payer or beneficiary details are valid. Cache responses briefly to avoid extra latency.

GET /account-info accepts optional JSON body parameters (iban, with_title_fetch). Use query parameters if your HTTP client does not support GET bodies.

Title fetch example

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/title-fetch?iban={{customer_iban}}" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

const res = await fetch(
  `${process.env.SAFEPAY_BASE_URL}/v1/aggregators/${process.env.SAFEPAY_AGGREGATOR_ID}/title-fetch?iban=${encodeURIComponent(customerIban)}`,
  {
    headers: {
      'X-SFPY-AGGREGATOR-SECRET-KEY': process.env.SAFEPAY_SECRET_KEY ?? '',
    },
  },
);

if (!res.ok) {
  throw new Error(`Title fetch failed with status ${res.status}`);
}

const titlePayload: {
  iban: string;
  title: string;
  bank: string;
  verified_at: string;
} = await res.json();

Title fetch v2 (account number)

Use GET /title-fetch/v2 when you have a conventional account number and bank name instead of an IBAN.

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/title-fetch/v2?account_number={{account_number}}&bank_name={{bank_name}}" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

const params = new URLSearchParams({
  account_number: accountNumber,
  bank_name: bankName,
});

const res = await fetch(
  `${process.env.SAFEPAY_BASE_URL}/v1/aggregators/${process.env.SAFEPAY_AGGREGATOR_ID}/title-fetch/v2?${params}`,
  {
    headers: {
      'X-SFPY-AGGREGATOR-SECRET-KEY': process.env.SAFEPAY_SECRET_KEY ?? '',
    },
  },
);

if (!res.ok) {
  throw new Error(`Title fetch v2 failed with status ${res.status}`);
}

const titlePayload: {
  data: {
    statusCode: number;
    acctitle: string;
    acctype: string;
    iban?: string;
  };
} = await res.json();

Account info + alias lookup

Use the account-info endpoint when you only have the customer’s Raast alias.

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/account-info?alias_type=RAAST_ID&alias_value={{customer_alias}}&with_title_fetch=true" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

const accountInfoResponse = await fetch(
  `${process.env.SAFEPAY_BASE_URL}/v1/aggregators/${process.env.SAFEPAY_AGGREGATOR_ID}/account-info?alias_type=RAAST_ID&alias_value=${encodeURIComponent(customerAlias)}&with_title_fetch=true`,
  {
    headers: {
      'X-SFPY-AGGREGATOR-SECRET-KEY': process.env.SAFEPAY_SECRET_KEY ?? '',
    },
  },
);

if (!accountInfoResponse.ok) {
  throw new Error(`Account info lookup failed: ${accountInfoResponse.status}`);
}

const accountInfo: {
  iban?: string;
  alias_type?: 'RAAST_ID' | 'PHONE' | 'EMAIL';
  alias_value?: string;
  title?: string;
  bank?: string;
} = await accountInfoResponse.json();

Title fetch via alias

Use GET /title-fetch/alias when you have a Raast alias and need the account title quickly.

cURL

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/title-fetch/alias?alias_type=RAAST_ID&alias_value={{customer_alias}}&with_title_fetch=true" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

Getting started

Integration guides

Use Cases

Concepts

Reference

Title fetch example

Title fetch v2 (account number)

Account info + alias lookup

Title fetch via alias

See also

​Title fetch example

​Title fetch v2 (account number)

​Account info + alias lookup

​Title fetch via alias

​See also

Title fetch example

Title fetch v2 (account number)

Account info + alias lookup

Title fetch via alias

See also