Skip to main content

03. How to Initiate and Authorise a Payment

  • Updated

Initiation and Authorisation of a Payment in Steps

The following is a sample process walkthrough upon the initiation and authorisation of a single payment, where

  • payment-product = sepa-credit-transfers, and, 
  • SCA approach = Embedded SCA approach.

More about the payment product and models can be found on 11. Payment Products and Models. 

Prerequisites

Your certificate must contain the PSP role = PSP_PI.

Step 1 Payment Initiation

On this step, payment initiation request with the payment data is sent to XS2A.

XS2A validates the role from the certificate, PSU-ID and request syntax. If all the validations have been completed successfully, XS2A returns a paymentId.

It means that a payment resource has been created and must be authorised by the PSU.

Created payment resource will be accessible under given paymentId during 30 minutes from the moment of creation. Authorisation of given payment must be completed within this time.

If a payment is not authorised and its validity time has expired, the access to this resource will be cancelled and payment initiation flow will be terminated.

Request

  1. Go to /v1/payments/sepa-credit-transfers. 
  2. Fill in mandatory data
    • Method = POST
    • PSU-ID = one of PSU-IDs from 09. Sandbox Test Accounts and Test Data
    • PSU-IP-Address = valid IP address
    • X-Request-ID = valid UUID
    • payment-product = sepa-credit-transfers
    • payment-service = payments
  3. Fill in payment data according to the payment model
    • it is required to include "@type" element with the name of the payment model

    • payment model must be correspondent to selected payment-product

      Example
      {"@type": "PaymentInitiationSctJson",
      "debtorAccount" : {"iban": "DE54500105173424724776"},
      "instructedAmount": {"currency": "EUR", "amount": "1"},
      "creditorAccount": {"iban": "LU280019400644750000"},
      "creditorName": "creditor_name"}
  4. Execute the request.

Response

HTTP status code: 201 Created

Example
{ "transactionStatus": "RCVD",
"paymentId": string,
"_links": { "self": "/v1/payments/{paymentId}",
"status": "/v1/payments/{paymentId}/status",
"startAuthorisation": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations" }
}

 

Step 2 Payment authorisation initiation

On this step, payment authorisation is initiated.

XS2A validates the role from the certificate, paymentId and request syntax. If all the validations have been completed successfully, XS2A returns an authorisationId inside the "updatePsuAuthentication" link.

It means that an authorisation sub-resource has been created for given paymentId.

Created authorisation sub-resource will be accessible under given authorisationId during 30 minutes from the moment of creation. Authorisation of given payment must be completed within this time.

If a payment is not authorised and its validity time is over the access to this resource will be cancelled and payment initiation flow will be terminated.

Request

  1. Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations or follow the "startAuthorisation" link from the response in Step 1.
  2. Fill in mandatory data
    • Method: POST
    • PSU-ID: same as in Step 1
    • X-Request-ID: valid UUID
    • payment-product: same as in Step 1
    • payment-service: same as in Step 1
    • paymentId: paymentId received in response in Step 1
    • body: no body
  3. Execute the request.

Response

HTTP status code: 200 Ok

Example
{
"scaStatus": "received",
"_links": {"updatePsuAuthentication": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}"}
}
 

Step 3 Provide PSU password

On this step, password from the PSU's side must be provided.

Please, use corresponding password from 10. Sandbox Test Accounts and Test Data.

Request

  1. Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the "updatePsuAuthentication" link from the response in Step 2.
  2. Fill in mandatory data
    • Method: PUT
    • PSU-ID: same as in Step 1
    • X-Request-ID: valid UUID
    • payment-product: same as in Step 1
    • payment-service: same as in Step 1
    • authorisationId: authorisationId received in response in Step 2
    • paymentId: paymentId received in response in Step 1
  3. Fill in psuData 
Example
{
"psuData": {"password": "string"}
}     

     4. Execute the request.

Response

HTTP status code: 200 Ok

Example
{
"scaStatus": "psuAuthenticated",
"scaMethods": [
{
"authenticationType": "SMS_OTP",
"authenticationMethodId": "sms"
},
{
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
}
],
"_links": {"selectAuthenticationMethod": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}",
"scaStatus": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}"}
}
 

Step 4 Select SCA method

PSU was authenticated successfully with its PSU-ID and password in the previous step and now XS2A offers selection of authentication methods.

An authentication method is a format of the 2nd factor that must be provided by PSU in order to complete the authorisation of a payment.

To trigger Decoupled SCA please use authenticationMethodId where "authenticationType" =  "PUSH_OTP” in the response in the Step 3.

Request

  1. Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the "selectAuthenticationMethod" link from the response in Step 3.
  2. Fill in mandatory data
    • Method: PUT
    • PSU-ID: same as in Step 1
    • X-Request-ID: valid UUID
    • payment-product: same as in Step 1
    • payment-service: same as in Step 1
    • authorisationId: authorisationId received in response in Step 2
    • paymentId: paymentId received in response in Step 1

  3. Fill in authenticationMethodId 

    Example
    {
    "authenticationMethodId": "chip"
    }
  4. Execute the request.

Response

HTTP status code: 200 Ok

Note: "authoriseTransaction" link will only be returned if EMBEDDED SCA has been chosen.

Example
{
"scaStatus": "scaMethodSelected",
"chosenScaMethod": {
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
},
"_links": {"scaStatus": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}",
"authoriseTransaction": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}"}
}
 

Step 5 Provide 2nd factor

This is the final step where PSU completes the payment authorisation by providing the 2nd factor.

In real-life operation, a bank will generate and send the 2nd factor to PSU.

In the Sandbox, the behaviour of a bank is simulated: XS2A doesn't generate and sent any challenges but offers default format of authentication data. Please refer to 09. Sandbox Test Accounts and Test Data for full details. 

Request

  1. Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the "authoriseTransaction" link from the response in Step 4.
  2. Fill in mandatory attributes
    • Method: PUT
    • PSU-ID: same as in Step 1
    • X-Request-ID: valid UUID
    • payment-product: same as in Step 1
    • payment-service: same as in Step 1
    • authorisationId: authorisationId received in response in Step 2
    • paymentId: paymentId received in response in Step 1

  3. Fill in scaAuthenticationData according to the authentication method selected in the previous step. Please, see 09.Sandbox Test Accounts and Test Data.

    Example
    { "scaAuthenticationData": "string" }
  4. Execute the request.

Response

HTTP status code: 200 Ok

Example
{
"scaStatus": "finalised",
"_links": {"scaStatus": "/v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId}"}
}
 

Related articles

Powered by Zendesk