Document toolboxDocument toolbox

Header

01 Create a new basis check

Owned by Andrei Galitski
Last updated: Apr 08, 2021 by Bernd Hochmuth
2 min read
URL

/api/v1/checks

HTTP MethodPOST
Short descriptionValidates client-id and secret and if valid - creates new check (flow). Returns redirect URL to the first page of the flow.
Request
NameTypeMandatoryDescription

client-id

stringYES

finapi client id. To be able to use GiroIden one need valid finapi client-id and client-secret.

client-secretstringYESfinapi client secret. To be able to use GiroIden one need valid finapi client-id and client-secret.

cancel-url

stringYES

Caller  MUST provide this URL. User will be sent to the url if he or she clicks on "Cancel" in the GiroIdent flow.

The urls supports placeholder for check-id: "{check-id}" which will be replaced with actual check-id generated by GiroIdent.

Here's an example: https://www.acme.com/giroident-cancel?check={check-id}

result-url

stringYES

Caller  MUST provide this URL. User will be redirected to this page after he or she completes the  GiroIdent flow.

The urls supports placeholder for check-id: "{check-id}" which will be replaced with actual check-id generated by GiroIdent.

Here's an example: https://www.acme.com/giroident-result?check={check-id}

first-name

stringYESUser's first name.

last-name

stringYESUser's last name.

iban

stringNO

User's iban. This is an optional parameter. If either IBAN,BLZ or Bank-Id is provided and GiroIdent finds the bank identified, user will be redirected to the bank-login page.

If any 2 of this 3 parameters are provided following priority is used:

  1. Bank-id
  2. IBAN
  3. BLZ

Meaning that if for example Bank-ID and IBAN are provided - GiroIdent will use Bank-Id.

If neither of 3 parameters are provided user will be redirected to bank - selection page.

blz

stringNO

BLZ of user's bank. 

See iban for detailed description.

bank-id

stringNO

Depricated field, will be ignored.

external-id

string

NO
Client app specific id to be stored with the check.
Errors
CauseHTTP Code
Bad request.
Raised while resolving a controller method argument.
Thrown when binding errors are considered fatal.
Exception to be thrown when validation on an argument fails.

400

Authentication object has invalid authentication reasons.
Thrown by the security manager to indicate a security violation.


401
Forbidden403
Thrown when can not find entity by request parameters or identifiers.404
An unexpected error occurred. Different finapi errors in responses.500

Description

Validates client-id and secret and if valid - creates new check (flow). Returns redirect URL to the first page of the flow.

Request sample

Response
{
  "client-id": "finapi-1233",
  "client-secret": "1234-secret",
  "cancel-url": "https://www.acme.com/giroident-cancel?check={check-id}",
  "result-url": "https://www.acme.com/giroident-result?check={check-id}",
  "first-name": "Thomas",
  "last-name": "Mustermann"
}

Response

AttributeDescription
check-idUUID for the check. Generated by GiroIdent
redirect-urlURL where Platform should send user to.
Response
{
"check-id": "ed327f56-efd9-4ac4-b0fc-0a23b507c485 ",
"redirect-url": "https://giroident.finapi.io/check/ed327f56-efd9-4ac4-b0fc-0a23b507c485"
}

Footer