Create consent
curl --request POST \ --url https://api.ztlpay.io/api/v2/consents \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'PSU-IP-Address: 192.158.1.38' \ --header 'PSU-User-Agent: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0' \ --data '{ "userId": "example", "bic": "ESSESESS", "callbackUrl": "https://www.google.com", "organizationNumber": "1234567890", "preferredScaMethod": "Qr", "bankBranch": "example" }'Create consent and starts authentication process automatically (SCA details is available in response body). For banks having different branches, please refer to the banks api for available branches. Create a consent for the current API before using account information or payment operations.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Example
192.158.1.38AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don’t use something stored in your DB). This information is used by the banks to manage traffic and handle security.
The forwarded Agent header field of the HTTP request between PSU and TPP.
Example
Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0Request Body
Section titled “Request Body”object
The userId of the account owner providing consent. Different banks use different userId schema, Could be SSN or a userId provided by the bank.
The bank’s international code/address. Also know as Swift code.
Example
ESSESESSSca callback url for Redirect authentication
Example
https://www.google.comThe organization number
Example
1234567890The preferred way to perform authorization. There is no guarantee that bank supports the preferred method.
QrUsed with bank app to scan image.RedirectRedirect link to redirect authorization flow.
Which branch of the bank if multiple. Can be fetched from supported banks endpoint.
Responses
Section titled “Responses”Successfully created consent
object
An ID that will be used to identify the consent. Used in all AIS and PIS calls.
AWAITING_AUTHORIZATIONRequires user approvalVALIDValid consent, can be used for AIS and PIS.REJECTEDConsent creation or authentication failed.EXPIREDConsent has expired, a new consent must be created to replace the expired consent.REVOKEDConsent was revoked either by user or bank. A new consent must be created to replace the revoked consent.
object
Redirect link to redirect authorization flow. After the redirect, the url will contain the query parameter status, with the possible values [success, rejected, cancelled]
Url to start authorization redirect flow
object
Qr image, used with bank app to scan image for authentication
Qr code which can be used to generate Qr image. Can be used to customize image. Might not be available for all banks.
Qr code as image, base64 encoded
DynamicDynamic image, valid for 1 sec. Must be refreshed by fetching updated approval status.StaticStatic image, valid for a longer period dependent on bank. Usually 30 seconds.
Example
{ "id": "B44E9297-934D-4975-8951-7843B16DF63F", "status": "AWAITING_AUTHORIZATION", "sca": { "type": "redirect", "url": "https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4" }}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Bad Request
object
INVALID_USER_IDWrong userIdINVALID_ORGANIZATION_NUMBERWrong Organization NumberINVALID_BICUnsupported BicUNKNOWN_CUSTOMERCustomer does not have an account in the bank, or must specify bankBranchAUTHENTICATION_TEMPORARY_UNAVAILABLEAuthentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "failure": "INVALID_USER_ID", "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Forbidden
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Conflict
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Internal server error
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9Service unavailable
object
Unique RequestId, please provide this Id in case of support requests
The underlying reason for the error
Example
{ "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9", "message": "Invalid account"}Headers
Section titled “Headers”Unique RequestId, please provide this Id in case of support requests
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9