Payment Initiation API

API change history

Summary

The NextGenPSD2 Framework Version 1.3 offers a modern, open, harmonised and interoperable set of Application Programming Interfaces (APIs) as the safest and most efficient way to provide data securely. The NextGenPSD2 Framework reduces XS2A complexity and costs, addresses the problem of multiple competing standards in Europe and, aligned with the goals of the Euro Retail Payments Board, enables European banking customers to benefit from innovative products and services ('Banking as a Service') by granting TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data.

The possible Approaches are:

  • Redirect SCA Approach
  • OAuth SCA Approach
  • Decoupled SCA Approach
  • Embedded SCA Approach without SCA method
  • Embedded SCA Approach with only one SCA method available
  • Embedded SCA Approach with Selection of a SCA method

Not every message defined in this API definition is necessary for all approaches. Furthermore this API definition does not differ between methods which are mandatory, conditional, or optional Therefore for a particular implementation of a Berlin Group PSD2 compliant API it is only necessary to support a certain subset of the methods defined in this API definition.

Please have a look at the implementation guidelines if you are not sure which message has to be used for the approach you are going to use.

  • This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not an replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API.

  • This API definition contains the REST-API for requests from the PISP to the ASPSP.

  • This API definition contains the messages for all different approaches defined in the Implementation Guidelines.

  • According to the OpenAPI-Specification [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md]

    "If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored."

    The element "Accept" will not be defined in this file at any place.

    The elements "Content-Type" and "Authorization" are implicitly defined by the OpenApi tags "content" and "security".

  • There are several predefined types which might occur in payment initiation messages, but are not used in the standard JSON messages in the Implementation Guidelines. Therefore they are not used in the corresponding messages in this file either. We added them for the convenience of the user. If there is a payment product, which need these field, one can easily use the predefined types. But the ASPSP need not to accept them in general.

  • We omit the definition of all standard HTTP header elements (mandatory/optional/conditional) except they are mention in the Implementation Guidelines. Therefore the implementer might add the in his own realisation of a PSD2 comlient API in addition to the elements define in this file.

General Remarks on Data Types

The Berlin Group definition of UTF-8 strings in context of the PSD2 API have to support at least the following characters

a b c d e f g h i j k l m n o p q r s t u v w x y z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

0 1 2 3 4 5 6 7 8 9

/ - ? : ( ) . , ' +

Space

cancelPayment

This method initiates the cancellation of a payment. Depending on the payment-service, the payment-product and the ASPSP's implementation, this TPP call might be sufficient to cancel a payment. If an authorisation of the payment cancellation is mandated by the ASPSP, a corresponding hyperlink will be contained in the response message.

Cancels the addressed payment with resource identification paymentId if applicable to the payment-service, payment-product and received in product related timelines (e.g. before end of business day for scheduled payments of the last business day before the scheduled execution day).

The response to this DELETE command will tell the TPP whether the

  • access method was rejected
  • access method was successful, or
  • access method is generally applicable, but further authorisation processes are needed.

Try it

Request

Request URL

Request parameters

  • string

    Payment service:

    Possible values are:

    • payments
    • bulk-payments
    • periodic-payments
  • string

    The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported.

    The following payment products are supported:

    • sepa-credit-transfers
    • instant-sepa-credit-transfers
    • target-2-payments
    • cross-border-credit-transfers
    • pain.001-sepa-credit-transfers
    • pain.001-instant-sepa-credit-transfers
    • pain.001-target-2-payments
    • pain.001-cross-border-credit-transfers

    Remark: For all SEPA Credit Transfer based endpoints which accept XML encoding, the XML pain.001 schemes provided by EPC are supported by the ASPSP as a minimum for the body content. Further XML schemes might be supported by some communities.

    Remark: For cross-border and TARGET-2 payments only community wide pain.001 schemes do exist. There are plenty of country specificic scheme variants.

  • string

    Resource identification of the generated payment initiation resource.

Request headers

  • string

    Format - uuid. ID of the request, unique to the call, as determined by the initiating party.

  • (optional)
    string

    Is contained if and only if the "Signature" element is contained in the header of the request.

  • (optional)
    string

    A signature of the request by the TPP on application level. This might be mandated by ASPSP.

  • (optional)
    string

    The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.

  • (optional)
    string

    The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.

  • (optional)
    string

    The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.

  • (optional)
    string

    The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

  • (optional)
    string

    The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

  • (optional)
    string

    The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

  • (optional)
    string

    The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

  • (optional)
    string

    The forwarded Agent header field of the HTTP request between PSU and TPP, if available.

  • (optional)
    string

    HTTP method used at the PSU ? TPP interface, if available. Valid values are:

    • GET
    • POST
    • PUT
    • PATCH
    • DELETE
  • (optional)
    string

    Format - uuid. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.

  • (optional)
    string

    The forwarded Geo Location of the corresponding http request between PSU and TPP if available.

  • string
    Subscription key which provides access to this API. Found in your Profile.

Request body

Responses

202 Accepted

OK

Response headers

  • (optional)
    string

Representations

400 Bad Request

Bad Request

Representations

401 Unauthorized

Unauthorized

Representations

403 Forbidden

Forbidden

Representations

404 Not Found

Not found

Representations

405 Method Not Allowed

Method Not Allowed

Representations

406 Not Acceptable

Not Acceptable

Representations

408 Request Timeout

Request Timeout

Representations

415 Unsupported Media Type

Unsupported Media Type

Representations

429 Too many requests

Too Many Requests

Representations

500 Internal Server Error

Internal Server Error

Representations

503 Service Unavailable

Service Unavailable

Representations

Code samples

@ECHO OFF

curl -v -X DELETE "https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}"
-H "X-Request-ID: "
-H "Digest: "
-H "Signature: "
-H "TPP-Signature-Certificate: "
-H "PSU-IP-Address: "
-H "PSU-IP-Port: "
-H "PSU-Accept: "
-H "PSU-Accept-Charset: "
-H "PSU-Accept-Encoding: "
-H "PSU-Accept-Language: "
-H "PSU-User-Agent: "
-H "PSU-Http-Method: "
-H "PSU-Device-ID: "
-H "PSU-Geo-Location: "
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("X-Request-ID", "");
            client.DefaultRequestHeaders.Add("Digest", "");
            client.DefaultRequestHeaders.Add("Signature", "");
            client.DefaultRequestHeaders.Add("TPP-Signature-Certificate", "");
            client.DefaultRequestHeaders.Add("PSU-IP-Address", "");
            client.DefaultRequestHeaders.Add("PSU-IP-Port", "");
            client.DefaultRequestHeaders.Add("PSU-Accept", "");
            client.DefaultRequestHeaders.Add("PSU-Accept-Charset", "");
            client.DefaultRequestHeaders.Add("PSU-Accept-Encoding", "");
            client.DefaultRequestHeaders.Add("PSU-Accept-Language", "");
            client.DefaultRequestHeaders.Add("PSU-User-Agent", "");
            client.DefaultRequestHeaders.Add("PSU-Http-Method", "");
            client.DefaultRequestHeaders.Add("PSU-Device-ID", "");
            client.DefaultRequestHeaders.Add("PSU-Geo-Location", "");
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            var uri = "https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}?" + queryString;

            var response = await client.DeleteAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}");


            URI uri = builder.build();
            HttpDelete request = new HttpDelete(uri);
            request.setHeader("X-Request-ID", "");
            request.setHeader("Digest", "");
            request.setHeader("Signature", "");
            request.setHeader("TPP-Signature-Certificate", "");
            request.setHeader("PSU-IP-Address", "");
            request.setHeader("PSU-IP-Port", "");
            request.setHeader("PSU-Accept", "");
            request.setHeader("PSU-Accept-Charset", "");
            request.setHeader("PSU-Accept-Encoding", "");
            request.setHeader("PSU-Accept-Language", "");
            request.setHeader("PSU-User-Agent", "");
            request.setHeader("PSU-Http-Method", "");
            request.setHeader("PSU-Device-ID", "");
            request.setHeader("PSU-Geo-Location", "");
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("X-Request-ID","");
                xhrObj.setRequestHeader("Digest","");
                xhrObj.setRequestHeader("Signature","");
                xhrObj.setRequestHeader("TPP-Signature-Certificate","");
                xhrObj.setRequestHeader("PSU-IP-Address","");
                xhrObj.setRequestHeader("PSU-IP-Port","");
                xhrObj.setRequestHeader("PSU-Accept","");
                xhrObj.setRequestHeader("PSU-Accept-Charset","");
                xhrObj.setRequestHeader("PSU-Accept-Encoding","");
                xhrObj.setRequestHeader("PSU-Accept-Language","");
                xhrObj.setRequestHeader("PSU-User-Agent","");
                xhrObj.setRequestHeader("PSU-Http-Method","");
                xhrObj.setRequestHeader("PSU-Device-ID","");
                xhrObj.setRequestHeader("PSU-Geo-Location","");
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "DELETE",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"DELETE"];
    // Request headers
    [_request setValue:@"" forHTTPHeaderField:@"X-Request-ID"];
    [_request setValue:@"" forHTTPHeaderField:@"Digest"];
    [_request setValue:@"" forHTTPHeaderField:@"Signature"];
    [_request setValue:@"" forHTTPHeaderField:@"TPP-Signature-Certificate"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-IP-Address"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-IP-Port"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Accept"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Accept-Charset"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Accept-Encoding"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Accept-Language"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-User-Agent"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Http-Method"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Device-ID"];
    [_request setValue:@"" forHTTPHeaderField:@"PSU-Geo-Location"];
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'X-Request-ID' => '',
    'Digest' => '',
    'Signature' => '',
    'TPP-Signature-Certificate' => '',
    'PSU-IP-Address' => '',
    'PSU-IP-Port' => '',
    'PSU-Accept' => '',
    'PSU-Accept-Charset' => '',
    'PSU-Accept-Encoding' => '',
    'PSU-Accept-Language' => '',
    'PSU-User-Agent' => '',
    'PSU-Http-Method' => '',
    'PSU-Device-ID' => '',
    'PSU-Geo-Location' => '',
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_DELETE);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'X-Request-ID': '',
    'Digest': '',
    'Signature': '',
    'TPP-Signature-Certificate': '',
    'PSU-IP-Address': '',
    'PSU-IP-Port': '',
    'PSU-Accept': '',
    'PSU-Accept-Charset': '',
    'PSU-Accept-Encoding': '',
    'PSU-Accept-Language': '',
    'PSU-User-Agent': '',
    'PSU-Http-Method': '',
    'PSU-Device-ID': '',
    'PSU-Geo-Location': '',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('openapi.praxiabank.com')
    conn.request("DELETE", "/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'X-Request-ID': '',
    'Digest': '',
    'Signature': '',
    'TPP-Signature-Certificate': '',
    'PSU-IP-Address': '',
    'PSU-IP-Port': '',
    'PSU-Accept': '',
    'PSU-Accept-Charset': '',
    'PSU-Accept-Encoding': '',
    'PSU-Accept-Language': '',
    'PSU-User-Agent': '',
    'PSU-Http-Method': '',
    'PSU-Device-ID': '',
    'PSU-Geo-Location': '',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('openapi.praxiabank.com')
    conn.request("DELETE", "/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://openapi.praxiabank.com/sandbox/pis/v1/{payment-service}/{payment-product}/{paymentId}')


request = Net::HTTP::Delete.new(uri.request_uri)
# Request headers
request['X-Request-ID'] = ''
# Request headers
request['Digest'] = ''
# Request headers
request['Signature'] = ''
# Request headers
request['TPP-Signature-Certificate'] = ''
# Request headers
request['PSU-IP-Address'] = ''
# Request headers
request['PSU-IP-Port'] = ''
# Request headers
request['PSU-Accept'] = ''
# Request headers
request['PSU-Accept-Charset'] = ''
# Request headers
request['PSU-Accept-Encoding'] = ''
# Request headers
request['PSU-Accept-Language'] = ''
# Request headers
request['PSU-User-Agent'] = ''
# Request headers
request['PSU-Http-Method'] = ''
# Request headers
request['PSU-Device-ID'] = ''
# Request headers
request['PSU-Geo-Location'] = ''
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body