Skip to content
ZTLDeveloper Portal

Cancel payment

POST
/api/v2/payments/cancel
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/v2/payments/cancel \
  --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 '{ "paymentId": "7c628b2e-9094-4bf8-af23-1d517c6fc4f5", "callbackUrl": "https://www.google.com", "preferredScaMethod": "Redirect" }'

Cancels a payment. May required approval (dependent on bank and payment status).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
consent-id
required
string format: uuid
Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address
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
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

Section titled “Request Body”
Media typeapplication/json
object
paymentId
required

Payment id to be cancelled

string
Example
7c628b2e-9094-4bf8-af23-1d517c6fc4f5
callbackUrl
required

Callback url for redirect authentication

string
Example
https://www.google.com
preferredScaMethod

Prefered sca method. Qr only supported in Sweden.

string
Allowed values: Redirect Qr

Responses

Section titled “Responses”

200

Section titled “200”

Payment cancellation created, check status

Media typeapplication/json
object
id

An ID that can be used to identify the cancellation attempt

string format: uuid
sca
One of:
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
cancellationRequestStatus
required

Status of the cancellation, note that this is not the same as payment status.

  • ACCEPTED the cancellation has been successfully
  • REJECTED the cancellation was rejected
  • AUTHORIZATION_REQUIRED the cancellation requires approval/signing
string
Allowed values: ACCEPTED REJECTED AUTHORIZATION_REQUIRED
currentPaymentStatus
required

Latest status of the payment after the cancellation request has been accounted for

object
status
required
  • Unsigned The user must approve the transaction.
  • InProgress The payment is ongoing.
  • Completed The payment has been completed by the bank.
  • Rejected The bank rejected the payment.
  • Cancelled The payment has been cancelled.
  • CustomerActionRequired The payment requires further action from the user. See statusReason for details.
string
Allowed values: Unsigned InProgress Completed Rejected Cancelled CustomerActionRequired
statusReason
  • PartlySigned Indicates that the payments needs additional signing. This requirement may be set up for the bank account.
  • SmsConfirmationRequired The user needs additional confirmation with responding SMS received. Only used by a few banks
  • InsufficientFunds The payment has been stopped by the bank due to lack of funds
string
Allowed values: PartlySigned SmsConfirmationRequired InsufficientFunds
statusReasonText

Payment status reason, unmapped reason text from bank.

string
timestamp
required

Timestamp when the status was fetched from bank

string
reason

Additional information

string
Example
{
  "sca": {
    "type": "redirect",
    "url": "https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4"
  },
  "cancellationRequestStatus": "ACCEPTED",
  "currentPaymentStatus": {
    "status": "Unsigned",
    "statusReason": "PartlySigned",
    "timestamp": "2024-03-19T09:34:57.657733682+01:00"
  },
  "reason": null
}

400

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Headers”
ztl-request-id
string format: uuid

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

Example
3a797348-ef0c-4f52-b821-fdfcdb98c4d9