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 immediately before an RTP or payout operation to ensure the payer or beneficiary details are valid. If you cache a successful response, scope it to the same authenticated user and transaction and expire it after no more than five minutes.

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

Privacy and abuse prevention

Account information and title fetch responses can reveal an account holder’s name from an IBAN, conventional account number, or alias such as a mobile number. The absence of a Safepay-enforced rate limit does not make these APIs suitable for unrestricted directory lookup. Keep all calls on your backend. Never expose your aggregator secret or proxy these endpoints directly to a browser or mobile application. Allow a lookup only when all of the following are true:

The end user is authenticated and has started a payment, payout, beneficiary-addition, or account-verification flow.
The identifier has passed format validation and the user has explicitly submitted it. Do not call lookup APIs on every keystroke, provide search or autocomplete, or support bulk enumeration.
The result is bound to that user and transaction. Show only the minimum account-title detail required for confirmation and do not make results visible to another user.
Identifiers and account titles are redacted from application, analytics, and support logs. Retain them only for the transaction or another documented legal or operational need.

Recommended starting limits

Safepay does not currently prescribe or enforce a numeric account-lookup quota. Until a contractual limit is provided, apply these controls at your own edge as a starting point:

Scope	Suggested starting control
Authenticated user	60 lookup requests per minute and 300 per hour
Source IP or device	120 lookup requests per minute across users
Same normalized identifier	10 requests per 15 minutes per user; reuse a recent result instead of querying again
Aggregator	A global ceiling based on expected payment traffic, with an alert on unusual volume or a spike in distinct identifiers

These values are abuse-prevention guidance, not a Safepay service quota or throughput entitlement. Tighten them for higher-risk or unauthenticated surfaces and tune them using your legitimate traffic after a security review. Count attempts whether they succeed or fail, and apply the strictest applicable limit. When a caller exceeds your limit, return 429 Too Many Requests with Retry-After from your application without forwarding the request to Safepay. Add a cooldown or step-up challenge when one user, IP, or device probes many distinct identifiers. Use consistent user-facing errors so lookup failures cannot be used to efficiently enumerate registered aliases.

Do not treat an account-title match as proof that the end user owns or controls the account. It confirms directory information only; use the authorization or verification controls required by your product flow.

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

Privacy and abuse prevention

Recommended starting limits

Title fetch example

Title fetch v2 (account number)

Account info + alias lookup

Title fetch via alias

See also

​Privacy and abuse prevention

​Recommended starting limits

​Title fetch example

​Title fetch v2 (account number)

​Account info + alias lookup

​Title fetch via alias

​See also

Privacy and abuse prevention

Recommended starting limits

Title fetch example

Title fetch v2 (account number)

Account info + alias lookup

Title fetch via alias

See also