Payment approval status

GET

/api/v2/payments/approve/{id}

Code sample: Shell / cURL

curl --request GET \
  --url https://api.ztlpay.io/api/v2/payments/approve/7c628b2e-9094-4bf8-af23-1d517c6fc4f5 \
  --header 'Authorization: Bearer <token>' \
  --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'

• Production environment
• Sandbox environment for testing

Approval status indicates the status of a started payment approval. If the QR Sca approach are used, this endpoint gives updated QR picture. This picture is only valid for a short time, so a new picture has to be fetched every 1 second. QR is only available in Sweden.

Authorizations

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

Parameters

Path Parameters

id

required

string format: uuid

Id received when creating an approval for payments

Example

7c628b2e-9094-4bf8-af23-1d517c6fc4f5

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

Responses

200

Approval status

Media typeapplication/json

object

id

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

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

qr

qr

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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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

Media typeapplication/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