Payment approval

POST

/api/v2/payments/approve

Shell / cURL

curl --request POST \
  --url https://api.ztlpay.io/api/v2/payments/approve \
  --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' \
  --header 'consent-id: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9' \
  --data '{ "payments": [ "175be5fc-4185-4cf1-af70-df34ead1a9ec", "4b24e1e8-f2ba-4d84-86a4-f5d5e4ae9af7" ], "callbackUrl": "https://www.google.com", "preferredScaMethod": "Redirect" }'

Start approval/signing process of a list of unsigned or partlySigned transactions. Can be both domestic and cross-border transactions.

Authorizations

OAuth2Sandbox
api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default
OAuth2Production
api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default

Parameters

Header Parameters

consent-id

required

string format: uuid

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address

required

string

Example

192.158.1.38

AAA 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.

PSU-User-Agent

required

string

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.0

Request Body

application/json

object

payments

required

Array<string>

>= 1 characters unique items

Example

[
  "175be5fc-4185-4cf1-af70-df34ead1a9ec",
  "4b24e1e8-f2ba-4d84-86a4-f5d5e4ae9af7"
]

callbackUrl

required

Sca callback url for redirect authentication

string

Example

https://www.google.com

preferredScaMethod

The preferred way to perform authorization. There is no guarantee that bank supports the preferred method.

string

Allowed values: Redirect Qr

Responses

200

Approval initiated successfully

application/json

object

required

An ID that can be used to identify the approval and check for statuses

string format: uuid

status

required

string

Allowed values: STARTED ACCEPTED REJECTED CANCELLED

sca

There is no guarantee that the used sca approach used by bank matches the preferred sca approach from request.

redirect For redirect, the end user must use the redirect url to start the authentication process
qr The QR image has to be presented to the end user, who has to scan the image with bank authentication app. The qr image needs to be refreshed every second, see approval status for refreshed QR image. Only used in Sweden

object

One of:

redirect
qr

redirect

object

type

required

Redirect link to redirect authorization flow. After the redirect, the url will contain the query parameter status, with the possible values [success, rejected, cancelled]

string

Allowed values: redirect

url

required

Url to start authorization redirect flow

string

object

type

required

Qr image, used with bank app to scan image for authentication

string

Allowed values: qr

qrCode

Qr code which can be used to generate Qr image. Can be used to customize image. Might not be available for all banks.

string

qrImage

required

Qr code as image, base64 encoded

string

qrType

required

Dynamic Dynamic image, valid for 1 sec. Must be refreshed by fetching updated approval status.
Static Static image, valid for a longer period dependent on bank. Usually 30 seconds.

string

Allowed values: Dynamic Static

Example

{
  "id": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5",
  "status": "STARTED",
  "sca": {
    "type": "redirect",
    "url": "https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4"
  }
}

400

Bad Request

application/json

object

failure

INVALID_CONSENT Consent is invalid
AUTHENTICATION_TEMPORARY_UNAVAILABLE Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process
UNSUPPORTED_PRODUCT_BY_BANK Product is not supported by bank
ACCESS_DENIED User does not have sufficient permissions

string

Allowed values: INVALID_CONSENT AUTHENTICATION_TEMPORARY_UNAVAILABLE UNSUPPORTED_PRODUCT_BY_BANK ACCESS_DENIED

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "failure": "INVALID_CONSENT",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid Bban"
}

403

Forbidden

application/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

404

Not found

application/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

409

Conflict

application/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

500

Internal server error

application/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

503

Service unavailable

application/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9