API Reference
HomeGuidesAPI ReferenceChangelogDiscussions
Log InAPI Reference

Common

Suggest Edits

GET /ob/banks (https://docs.exthand.com/reference/get_ob-banks)

Purpose
Retrieves the list of all the banks currently supported. Can be used with a country code to retrieve all the supported banks of the provided country. Each bank will have a connectorId which is the ID that must be provided to other endpoints to connect to that bank.

Request

  • Method: GET
  • URL: /ob/banks?countryCode=BE
  • Parameters: None
  • Query Parameters
    • countryCode: 2 letter country code to get list of banks from specific country (optional)
  • Headers: None
  • Request Body: None

Response

  • Headers: None
  • Response Body
[
  {
    "fullname": "string",
    "connectorID": 0,
    "logoURL": "string",
    "countryISO": "string",
    "verStable": "string",
    "status": 0,
    "bankGroup": "string"
  }
]

Example
Get all supported banks from the Netherlands. We get a list of two banks, Bank 1 and Bank 2, each with their own information about them and unique "connectorId".

  • Call: GET /ob/banks?countryCode=NL
  • Response Body
[
  {
    "fullname": "Bank 1",
    "connectorID": 1,
    "logoURL": "http://url.to/logoNL1",
    "countryISO": "NL",
    "verStable": null,
    "status": 0,
    "bankGroup": null
  },
  {
    "fullname": "Bank 2",
    "connectorID": 4,
    "logoURL": "http://url.to/logoNL2",
    "countryISO": "NL",
    "verStable": null,
    "status": 1,
    "bankGroup": null
  }
]

GET /ob/gw/tc/latest (https://docs.exthand.com/reference/get_ob-gw-tc-latest)

Purpose
In our philosophy to be transparent for the PSU, you can get the terms & conditions through the API, display them and ask the user to accept them.
You will receive a simple HTML content that you can format with simple CSS.
You must ensure that the user has always accepted our latest terms & conditions before doing AIS. PIS doesn't require the terms & conditions to be accepted.
We are checking that at each call.

Request

  • Method: GET
  • URL: /ob/gw/tc/latest?language=EN
  • Parameters: None
  • Query Parameters
    • language: 2 letter ISO code for language. "EN" will be used by default if other not provided or provided language not available (optional)
  • Headers: None
  • Request Body: None

Response

  • Headers: None
  • Response Body:
{
  "tc": "string",
  "privacy": "string",
  "version": 0,
  "language": "string",
  "availableLanguages": [
    "string"
  ]
}

Example

Gets the latest Terms and Conditions. An object is returned with the privacy notice, the Terms and Conditions, the version number, the language it's written in (English by default since we did not specify a language) and a list of available languages that can be used to perform this call to retrieve the Terms and Conditions.

  • Call: GET /ob/gw/tc/latest
  • Response Body
{
	"availableLanguages":
	[
		"EN", "FR"
	],
	"language": "EN",
	"version": 1,
	"privacy": "Privacy Notice",
	"tc": "Terms and Conditions"
}

POST /ob/gw/users (https://docs.exthand.com/reference/post_ob-gw-users)

Purpose
In order to request account access or to do a payment for a user, you must first register him into our gateway. User must contain at least your unique ID for that user in the field "externalRef" and either email or phone number.
Of course you must have validated the email and/or the mobile phone number (international format).
For this user to be valid, you must also ask him to accept our latest terms & conditions. See Terms & Conditions.
This user is what we refer as a PSU.
If you register the user with the same identifiable data we will return you the same PSU id. See the specific page.
The userContext field in the answer has to be treated as a blackbox and stored in you storage along with the psuid. You will need theml later.

Request

  • Method: POST
  • URL: /ob/gw/users
  • Parameters: None
  • Query Parameters: None
  • Headers: None
  • Request Body
{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "cellPhone": "string",
  "vatId": "string",
  "externalRef": "string",
  "dateOfBirth": "2023-11-08T09:01:40.385Z",
  "validatedVersionTC": 0
}

Response

  • Headers: None
  • Response Body
{
  "psuid": "string",
  "action": "string",
  "url": "string",
  "userContext": "string",
  "scope": "string"
}

Example
Create a user named John Doe with a ID in your application ("externalRef") of 001234. It returns an object with a "psuId" (our internal identification of the user) and a "userContext" for that user. It may also contain an "action", for example, in the case the user has not accepted our most recent Terms and Conditions the "action" property will reflect that. The "url" property will then be a URL to perform the corresponding action.
The "scope" reflects the type of actions the user can perform with the current registration. It depends if you provided validatedVersionTC. With -> AIS & PIS, without -> PIS. See latest T&C above.

  • Call: POST /ob/gw/users
  • Request Body
{
	"firstName": "John",
	"lastName": "Doe",
	"email": "[email protected]",
	"cellPhone": "12345678",
	"vatId": "555555555",
	"externalRef": "001234",
	"dateOfBirth": "1994-11-07",
	"validatedVersionTC": 1
}
  • Response Body
{
	"psuid": "3d72e5b9-888a-4d58-a344-1ea286018f8d",
	"action": "OK",
	"url": null,
	"userContext": "{\"userId\":\"001234\",\"idPSU\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\"}",
	"scope": "AIS_PIS"
}

GET /ob/gw/users/{id} (https://docs.exthand.com/reference/get_ob-gw-users-id)

Purpose
Retrieves a user by id. The user must have already been registered.
The id is the PsuId field you get when registering the user.

Request

  • Method: GET
  • URL: /ob/gw/users/{id}
  • Parameters:
    • id: ID of the PSU
  • Query Parameters: None
  • Headers: None
  • Request Body: None

Response

  • Headers: None
  • Response Body
{
  "psuid": "string",
  "scope": "string"
}

Example
Gets the user John Doe we created in the previous endpoint.

  • Call: GET /ob/gw/users/3d72e5b9-888a-4d58-a344-1ea286018f8d
  • Response Body
{
  "psuid": "3d72e5b9-888a-4d58-a344-1ea286018f8d",
  "scope": "PIS"
}

PUT /ob/gw/users/{id} (https://docs.exthand.com/reference/put_ob-gw-users-id)

Purpose
Update your internal user data in our gateway.
Just don't send the data you don't want to update.

Request

  • Method: PUT
  • URL: /ob/gw/users/{id}
  • Parameters:
    • id: ID of the PSU
  • Query Parameters: None
  • Headers: None
  • Request Body
{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "cellPhone": "string",
  "vatId": "string",
  "externalRef": "string",
  "dateOfBirth": "2023-11-08T09:27:14.830Z",
  "validatedVersionTC": 0
}

Response

  • Headers: None
  • Response Body
{
  "psuid": "string",
  "action": "string",
  "url": "string",
  "userContext": "string",
  "scope": "string"
}

Example
Updates the user named John Doe we already created, that has a "psuId" of 3d72e5b9-888a-4d58-a344-1ea286018f8d, with a new phone number and email. It returns an object with the "psuId" and a "userContext" for that user. It may also contain an "action", for example, in the case the user has not accepted our most recent Terms and Conditions the "action" property will reflect that. The "url" property will then be a URL to perform the corresponding action.
The "scope" reflects the type of actions the user can perform with the current registration.

  • Call: PUT /ob/gw/users/3d72e5b9-888a-4d58-a344-1ea286018f8d
  • Request Body
{
	"firstName": "John",
	"lastName": "Doe",
	"email": "[email protected]",
	"cellPhone": "987654321",
	"vatId": "555555555",
	"externalRef": "001234",
	"dateOfBirth": "1994-11-07",
	"validatedVersionTC": 1
}
  • Response Body
{
	"psuid": "3d72e5b9-888a-4d58-a344-1ea286018f8d",
	"action": "Needs to accept Terms and Conditions",
	"url": "http://accept.terms/andconditions",
	"userContext": "{\"userId\":\"001234\",\"idPSU\":\"3d72e5b9-888a-4d58-a344-1ea286018f8d\"}",
	"scope": "PIS"
}

GET /ob/gw/users/{id}/tc/latest (https://docs.exthand.com/reference/get_ob-gw-users-id-tc-latest)

Purpose
Gets PSU's latest accepted Terms and Conditions.

Request

  • Method: GET
  • URL: /ob/gw/users/{id}/tc/latest
  • Parameters:
    • id: ID of the PSU
  • Query Parameters: None
  • Headers: None
  • Request Body: None

Response

  • Headers: None
  • Response Body: int32 (version of PSU's accepted Terms and Conditions)

Example
Gets the latest accepted Terms and Conditions for the user John Doe we already created. The response returns the version number 1.

  • Call: GET /ob/gw/users/3d72e5b9-888a-4d58-a344-1ea286018f8d/tc/latest
  • Response Body: 1

Updated 5 months ago