natwest-poc.pages.dev Open in urlscan Pro
188.114.96.3  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Skip to main content
SolutionsDevelopersNewsAbout Us
search-small Search
Lock icon Sign in
close-plain-xsmall
Back Back to all API products


VARIABLE RECURRING PAYMENTS

Skip table of content
Overview
Documentation
SDKs
Show
Show
NatWest

Version
Version
3.1.11 (Latest)

Download API Spec (JSON)Test in the API sandbox
Table of ContentsShow Table of Contents
 * Introduction
   * Introduction
 * Prerequisites plus-xsmall
   * Partner Access plus-xsmall
   * Regulatory Access plus-xsmall
   * Discretionary Access plus-xsmall
 * Customer Consent plus-xsmall
   * Making a VRP Request plus-xsmall
   * Registering a VRP Request plus-xsmall
   * Obtaining an Access Token to Register Intent plus-xsmall
     * Example plus-xsmall
   * Registering a VRP Request plus-xsmall
     * Example plus-xsmall
   * Confirming the VRP Request plus-xsmall
     * Generating the Authorisation Code plus-xsmall
     * The OAuth Authorisation Request plus-xsmall
     * Example plus-xsmall
     * Authorisation Endpoint Response plus-xsmall
     * Example plus-xsmall
   * Exchanging an Authorisation Code for an Access Token plus-xsmall
     * Code Verifier and PKCE plus-xsmall
     * Example plus-xsmall
   * Submitting a Payment Request against the VRP Consent plus-xsmall
     * Examples plus-xsmall
     * Access Token Validity Period plus-xsmall
 * Security Considerations plus-xsmall
   * TLS Requirements plus-xsmall
     * Ciphers plus-xsmall
     * Mutual TLS plus-xsmall
   * Message Signing plus-xsmall
   * API Endpoints plus-xsmall
     * Required Headers plus-xsmall
     * Refreshing an Access Token plus-xsmall
     * Access and Refresh Token Validity Period plus-xsmall
 * Domestic VRP Consents plus-xsmall
   * Control Parameters plus-xsmall
 * Domestic VRPs plus-xsmall
   * Domestic VRPs plus-xsmall
 * API Specification plus-xsmall
   * POSTCreate a domestic VRP consent
   * GETRetrieve a domestic VRP consent
   * DELETEDelete a domestic VRP
   * POSTConfirm availability of funds for a VRP
   * POSTCreate a domestic VRP
   * GETRetrieve a domestic VRP
   * GETRetrieve a domestic VRP

Product overview


INTRODUCTION

The Variable Recurring Payments (VRP) API enables applications to make ad-hoc
payments directly from a customer's account. Customers remain in control,
providing approval for each beneficiary with specified limits.

There is a special use case for VRP known as 'sweeping'. In this scenario, a
sweep is a consent where the creditor is the same legal entity as the debtor and
the debtor account is a current account. For all other VRP use cases, the VRP
Type will be Other.

Throughout the documentation we presume you are a developer wanting to build an
application "the client application" to initiate payment requests.


PREREQUISITES


PARTNER ACCESS

All of our APIs are available for consumption by our business partners. If you
are not already a partner and want to become one, please get in touch via the
contact us page to request access.


REGULATORY ACCESS

Regulatory users are automatically granted access to this API for the sweeping
use case. The steps to gain access are:

 * You must be registered with the relevant competent authority as a Payment
   Initiation Services Provider (PISP). In the UK that is the Financial Conduct
   Authority (FCA).
 * You must have valid transport and signing certificates in place. These can be
   obtained from the UK Open Banking Implementation Entity (OBIE).
 * You must be onboarded with NatWest Group as a third-party provider. This can
   be done via the dynamic client registration endpoint.


DISCRETIONARY ACCESS

For non-sweeping use cases, information on gaining access to the API will be
added here soon.


CUSTOMER CONSENT

Gathering customer consent is the first step of the API journey. Each customer
must consent to allow you to initiate payments to a certain beneficiary. Consent
is an agreement between you as the application owner and the customer.

Once consent is agreed between you and the customer, the client application can
initiate a payment request without the customer being present.

The design of the API ensures that a customer's credentials are never shared
with you, so they can be reassured that their credentials remain confidential at
all times.


MAKING A VRP REQUEST

The process of gaining confirmation of payment request from a customer is a
multi-step process. You must complete each of the steps below in order to
initiate a payment request.

 * Step 1. You use your certificate based credentials to obtain an Access Token.
 * Step 2. You use this Access Token to register with us your intent to make a
   payment on behalf of a customer.
 * Step 3. The customer is redirected by you to our authentication portal where
   they view and authenticate the VRP consent.
 * Step 4. The customer views the VRP request before confirming (or declining)
   it.
 * Step 5. The customer is redirected back to your site or application and you
   receive an authorisation code.
 * Step 6. You exchange this authorisation code for an Access Token specific to
   the VRP request record.
 * Step 7. You use that Access Token to submit payments.


REGISTERING A VRP REQUEST

The process of registering a payment request with us via an API call is known as
registering an intent. The intent payload includes details of the VRP consent to
be made.


OBTAINING AN ACCESS TOKEN TO REGISTER INTENT

Firstly, you authenticate with us using your client transport certificate and
obtain an Access Token via the OAuth Client Credentials Flow. This token is used
later to register payment requests.

When requesting a token you must pass one or more of the OAuth Scopes you have
been granted. You may register multiple intents (potentially containing
different scopes) using a single Access Token. Remember to attach your transport
cert to the request.

EXAMPLE

Example Request:

POST https://secure1t.natwest.com/as/token.oauth2 HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded;
Charset: ISO-8859-1
Body: grant_type=client_credentials&client_id=7xPKBspndegEsfR2f2Fss2s&scope=payments

                              

Copy
                                  code
                            
                          
                        
                      

In this case the requested scope is payments. This is the scope you require to
make a payment (as opposed to access account data). You must pass the client_id
you obtained during the original registration as part of this request. See
Prerequisites for details.

Corresponding Response:

HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8
Content-Length: 102

{
    "access_token": "Wdi7eSGbZn58nKGdRsg3MjKzE4c7",
    "token_type": "Bearer",
    "expires_in": 599
}

                      

Copy
                          code
                    
                  
                
              

The value of the access_token field in the body of this response is used to
register a Payment Request during the next step.


REGISTERING A VRP REQUEST

Once authenticated, you must make an HTTP POST request to the
domestic-vrp-consents endpoint to register your intent to request a VRP consent
on behalf of the customer. This request contains details of the consent you wish
to make with the customer, including:

 * Creditor Account
 * Limits on amounts

At this stage the VRP Request is in the AwaitingAuthorisation state. It cannot
be used until it is confirmed by the customer.

The VRP Request endpoint is protected by Mutual TLS. The Access Token you
received during the previous stage must be passed as the Authorisation header
with every request to this endpoint.

EXAMPLE

Example Sweeping domestic-vrp-consents request:

POST https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrp-consents HTTP/1.1
Authorization: Bearer Wdi7eSGbZn58nKGdRsg3MjKzE4c7
x-fapi-financial-id: 0015800000jfwxXAAQ
x-fapi-auth-date: Sun, 16 Sep 2018 11:43:31 UTC
x-fapi-customer-ip-address: 1.2.3.4
x-fapi-interaction-id: 855f6b6f-5f84-4d02-8946-8a3fd0ed6601
Content-Type: application/json
Accept: application/json


{
	"Data": {
		"ReadRefundAccount": "No",
		"ControlParameters": {
			"ValidFromDateTime": "2021-09-22T14:31:35.288+01:00",
			"ValidToDateTime": "2022-12-31T14:31:35.287+01:00",
			"MaximumIndividualAmount": {
				"Amount": "100",
				"Currency": "GBP"
			},
			"PeriodicLimits": [
				{
					"PeriodType": "Month",
					"PeriodAlignment": "Calendar",
					"Amount": "1000",
					"Currency": "GBP"
				},
				{
					"PeriodType": "Year",
					"PeriodAlignment": "Calendar",
					"Amount": "10000",
					"Currency": "GBP"
				}
			],
			"vrpType": [
				"UK.OBIE.VRPType.Sweeping"
			],
			"PSUAuthenticationMethods": [
				"UK.OBIE.SCANotRequired"
			]
		},
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345687654321",
				"Name": "Joe Bloggs"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		}
	},
	"Risk": {
		
	}
}


              

Copy code
            
          
        
      

Example Response:

HTTP/1.1 201 Created
x-fapi-interaction-id: 855f6b6f-5f84-4d02-8946-8a3fd0ed6601
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Content-Length: 495
Date: Mon, 07 Jan 2019 17:37:29 GMT


{
	"Data": {
		"ConsentId": "6710128983094680bbe01eed6e9e8d71",
		"CreationDateTime": "2021-10-18T13:16:55.502Z",
		"Status": "AwaitingFurtherAuthorisation",
		"StatusUpdateDateTime": "2021-10-18T13:16:55.502Z",
		"ControlParameters": {
			"ValidFromDateTime": "2021-09-22T14:31:35.288+01:00",
			"ValidToDateTime": "2022-12-31T14:31:35.287+01:00",
			"MaximumIndividualAmount": {
				"Amount": "100",
				"Currency": "GBP"
			},
			"PeriodicLimits": [
				{
					"PeriodType": "Month",
					"PeriodAlignment": "Calendar",
					"Amount": "1000",
					"Currency": "GBP"
				},
				{
					"PeriodType": "Year",
					"PeriodAlignment": "Calendar",
					"Amount": "10000",
					"Currency": "GBP"
				}
			],
			"vrpType": [
				"UK.OBIE.VRPType.Sweeping"
			],
			"PSUAuthenticationMethods": [
				"UK.OBIE.SCANotRequired"
			]
		},
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "Joe Bloggs"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		},
		"DebtorAccount": {
			"SchemeName": "UK.OBIE.SortCodeAccountNumber",
			"Identification": "12345612345678",
			"Name": "Joe Bloggs"
		}
	}
  "Risk": {

  },
  "Links": {
    "Self": "https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrp-consents/6710128983094680bbe01eed6e9e8d71"
  },
  "Meta": {
    "TotalPages": 1
  }
}

      

Copy code
    
  
  
  

Example Other domestic-vrp-consents request:

POST https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrp-consents HTTP/1.1
Authorization: Bearer Wdi7eSGbZn58nKGdRsg3MjKzE4c7
x-fapi-financial-id: 0015800000jfwxXAAQ
x-fapi-auth-date: Sun, 16 Sep 2018 11:43:31 UTC
x-fapi-customer-ip-address: 1.2.3.4
x-fapi-interaction-id: 855f6b6f-5f84-4d02-8946-8a3fd0ed6601
Content-Type: application/json
Accept: application/json


{
	"Data": {
		"ReadRefundAccount": "No",
		"ControlParameters": {
			"ValidFromDateTime": "2021-09-22T14:31:35.288+01:00",
			"ValidToDateTime": "2022-12-31T14:31:35.287+01:00",
			"MaximumIndividualAmount": {
				"Amount": "100",
				"Currency": "GBP"
			},
			"MaximumCumulativeAmount": {
				"Amount": "10000",
				"Currency": "GBP"
			},
			"MaximumCumulativeNumberOfPayments": 200,
			"PeriodicLimits": [
				{
					"PeriodType": "Month",
					"PeriodAlignment": "Calendar",
					"Amount": "1000",
					"Currency": "GBP",
					"NumberOfPayments": 20
				},
				{
					"PeriodType": "Year",
					"PeriodAlignment": "Calendar",
					"Amount": "10000",
					"Currency": "GBP"
				}
			],
			"VRPType": [
				"UK.OBIE.OTHER"
			],
			"PSUAuthenticationMethods": [
				"UK.OBIE.SCANotRequired"
			]
		},
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345687654321",
				"Name": "John Doe"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		}
	},
	"Risk": {
		
	}
}


  

Copy code
  
  
  
  

Example Response:

HTTP/1.1 201 Created
x-fapi-interaction-id: 855f6b6f-5f84-4d02-8946-8a3fd0ed6601
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Content-Length: 495
Date: Mon, 07 Jan 2019 17:37:29 GMT


{
	"Data": {
		"ConsentId": "6710128983094680bbe01eed6e9e8d71",
		"CreationDateTime": "2021-10-18T13:16:55.502Z",
		"Status": "AwaitingFurtherAuthorisation",
		"StatusUpdateDateTime": "2021-10-18T13:16:55.502Z",
		"ControlParameters": {
			"ValidFromDateTime": "2021-09-22T14:31:35.288+01:00",
			"ValidToDateTime": "2022-12-31T14:31:35.287+01:00",
			"MaximumIndividualAmount": {
				"Amount": "100",
				"Currency": "GBP"
			},
			"MaximumCumulativeAmount": {
				"Amount": "10000",
				"Currency": "GBP"
			},
			"MaximumCumulativeNumberOfPayments": 200,
			"PeriodicLimits": [
				{
					"PeriodType": "Month",
					"PeriodAlignment": "Calendar",
					"Amount": "1000",
					"Currency": "GBP",
					"NumberOfPayments": 20
				},
				{
					"PeriodType": "Year",
					"PeriodAlignment": "Calendar",
					"Amount": "10000",
					"Currency": "GBP"
				}
			],
			"VRPType": [
				"UK.OBIE.OTHER"
			],
			"PSUAuthenticationMethods": [
				"UK.OBIE.SCANotRequired"
			]
		},
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "John Doe"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		},
		"DebtorAccount": {
			"SchemeName": "UK.OBIE.SortCodeAccountNumber",
			"Identification": "12345612345678",
			"Name": "Joe Bloggs"
		}
	}
  "Risk": {

  },
  "Links": {
    "Self": "https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrp-consents/6710128983094680bbe01eed6e9e8d71"
  },
  "Meta": {
    "TotalPages": 1
  }
}

  

Copy code
  
  
  
  


CONFIRMING THE VRP REQUEST

The next step is to obtain confirmation from the customer. To achieve this you
redirect the customer to our authentication portal where they log in using their
banking credentials, view your VRP request and confirm or decline it. The
request is now in the Authorised state.

Next, an Authorisation Code is generated by us, and the customer is redirected
back to you. The Authorisation Code is provided to you as part of that redirect.

The process is detailed below, step by step.

GENERATING THE AUTHORISATION CODE

The address of our Authorisation endpoint is available in the Open Banking
directory and can be verified there. This endpoint is HTTPS, protected with TLS
and HSTS.

During this stage you redirect the customer's browser or mobile app to our
Authentication portal to initiate the process of obtaining the customer's
confirmation. When making the request the client application constructs and
passes us a Redirect URI.

A detailed summary of our authorisation servers (including use of Universal
Links / Application links) can be found here.

THE OAUTH AUTHORISATION REQUEST

The URL you construct and invoke at this stage has a specific form. It must
contain:

 * Your client_id
 * A response_type of 'code id_token'.
 * A code_challenge_method and code_challenge query parameter (see PKCE RFC)
 * An OpenID Connect object in the request query parameter in the form of a
   signed JWT.
 * A nonce query parameter, optional parameter used to mitigate against replay
   attacks

The signed JWT must contain a set of mandatory claims including the Intent ID
obtained as part of the Payment Request API invocation and a redirect_uri
parameter.

The location of the Redirect URI is used to return the customer to you once
consent has been granted using our authentication portal. The root of the
Redirect URI must match that registered by you at registration time. See
Prerequisites for details on registration.

You must sign the JWT containing all the claims using the signing certificate
("sig" key) issued by your Competent Authority, namely the OBIE in the UK. See
the example request below and the Open ID Connect Specification for details.

Note:- At this time the NatWest Authorisation endpoint only supports use of
RSA256 for JWT signing.

EXAMPLE

Example Authorisation Request. This example uses
https://developer.natwest.com/dummy_redirect.htm as an example Redirect URI:

GET https://secure1.natwest.com/as/authorization.oauth2?client_id=7xPKBspndegEsfR2f2Fss2s&response_type=code%20id_token&code_challenge_method=S256&code_challenge=GGQfwpOUSD3-TbAC0jbrUR-CdLKuY5grWwGjTP4Hzwk&request=eyJraWQiOiJQWnJ3RUl3VW8ydmhyajBEZU0xOWNLUVNOczQiLCJ0eXAiOiJKV1MiLCJhbGciOiJSUzI1NiJ9.eyJjb25zZW50UmVmSWQiOiJjMjE1OGIwMDIxZWQ0MmJiYjY0ZWUxY2MyZTUzNDc0MSIsInNjb3BlIjoib3BlbmlkIGFjY291bnRzIiwiYWNyX3ZhbHVlcyI6InVybjpvcGVuYmFua2luZzpwc2QyOmNhIiwiaXNzIjoiNnhQVUh4bVNtTjhsZkwyRmJ6dXgzcyIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiYzIxNThiMDAyMWVkNDJiYmI2NGVlMWNjMmU1MzQ3NDEiLCJlc3NlbnRpYWwiOnRydWV9fSwidXNlcmluZm8iOnsiYWNyIjp7ImVzc2VudGlhbCI6dHJ1ZX0sIm9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6ImMyMTU4YjAwMjFlZDQyYmJiNjRlZTFjYzJlNTM0NzQxIiwiZXNzZW50aWFsIjp0cnVlfX19LCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOlwvXC9kZXZlbG9wZXIubmF0d2VzdC5jb21cL2R1bW15X3JlZGlyZWN0Lmh0bSIsInN0YXRlIjoiYWJjZDEyMzQiLCJleHAiOjE1NDIwMTY3NjksIm5vbmNlIjoiOWVkY2MxN2ItOGQxMy00YjgzLTgzZWEtM2RlYjEwNDhlMzQ0IiwiY2xpZW50X2lkIjoiNnhQVUh4bVNtTjhsZkwyRmJ6dXgzcyJ9.gMB_qpu4_2mE-mNTiEyBIlwSuDjIZ60rWLb6kSWavbEOR9p9TBatddVb_M6B1pr6Tz7pr0mgMWn4_i4T5TGewwCNHKbD-pgVLLX4-_R9XD8UBk-a6fUOHEoksWdePN-1WEJ0tapUnvZwPwx_uzjl6deIrYHC5mb6FlRHLGp4XIBKv-plM2-SHf7TR5WXzM0r-XBBUjH5dFWCx5R7TGVnOc7x4kaqu7Cah3js7qv1yAJMoue-BP3oeUeReBlzO-0ziUwbXiAeHeHRpXWlYCqJ5RvBsLQyrOp1P49rUZRdx_mnqnhZWBGAiABALzJ3HDNXEIXm6tSqhmBtZfcsTl-_Cw&nonce=9edcc17b-8d13-4b83-83ea-3deb1048e344 HTTP/1.1
Accept: text/html
Host: secure1.natwest.com
Body: <none>

  

Copy code
  
  
  
  

The request claims are base64url encoded within the request query parameter. For
a full understanding of the contents and structure of this object refer to the
OBIE Security Profile Hybrid Flow. (They can be decoded using JWT.io):

{
  "kid": "12345",
  "typ": "JWS",
  "alg": "RS256"
}
{
  "consentRefId": "4fbcfbb91dab4f27a3a70bea976d8555",
  "scope": "openid payments",
  "acr_values": "urn:openbanking:psd2:ca",
  "iss": "7xPKBspndegEsfR2f2Fss2s",
  "claims": {
    "id_token": {
      "acr": {
        "essential": true
      },
      "openbanking_intent_id": {
        "value": "4fbcfbb91dab4f27a3a70bea976d8555",
        "essential": true
      }
    },
    "userinfo": {
      "acr": {
        "essential": true
      },
      "openbanking_intent_id": {
        "value": "4fbcfbb91dab4f27a3a70bea976d8555",
        "essential": true
      }
    }
  },
  "response_type": "code id_token",
  "redirect_uri": "https://developer.natwest.com/dummy_redirect.htm",
  "state": "abcd1234",
  "exp": 1542016769,
  "nonce": "9edcc17b-8d13-4b83-83ea-3deb1048e344",
  "client_id": "7xPKBspndegEsfR2f2Fss2s"
}

  

Copy code
  
  
  
  

AUTHORISATION ENDPOINT RESPONSE

Once the customer has confirmed the payment request we redirect the customer's
browser to the provided Redirect URI. We append this URL with a hash fragment
containing the Authorisation Code (code) and an id_token in the form of a signed
JWT. The Authorisation Code is exchanged for a set of credentials used to make
the payment from the customer's account.

Note:- At this time the NatWest Authorisation endpoint uses RSA256 for ID Token
signing.

To remain FAPI compliant you must verify the signature of the signed JWT using
the public key available from our JWKS endpoint. The location of our JWKS
endpoint is the value of the jwks_uri attribute available from our .well-known
endpoint.

The value of the sub and openbanking_intent_id claims in this JWT are the
related Intent ID. This enables you to correlate the response with the requested
Intent. Additionally the c_hash and s_hash fields contain, respectively, hashes
of the passed in state parameter and returned code parameter. For more details
on the c_hash see the Open ID Connect documentation. For s_hash see the FAPI
documentation. If included in the request the nonce value will be played back in
the ID Token response.

EXAMPLE

Example Authorisation Response

https://developer.natwest.com/dummy_redirect.htm#code=vRZs_yPSuzsap3BIW9w7CmzgEgJ3MFCsLVkAAAAE&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ikg4OVBtWGx0VXVlVmFLLS1uVlNZM2c2SlBxYyJ9.eyJzdWIiOiJjMjE1OGIwMDIxZWQ0MmJiYjY0ZWUxY2MyZTUzNDc0MSIsImF1ZCI6IjZ4UFVIeG1TbU44bGZMMkZienV4M3MiLCJqdGkiOiJkdmZoUXhlV3ZxNzZnc082OXhLRjcwIiwiaXNzIjoiaHR0cHM6Ly9pYW0tYXV0aG4tc2l0LW53Yi5tYW5hZ2VkdGVzdC5jb20iLCJpYXQiOjE1NDIwMTY0NzgsImV4cCI6MTU0MjAxNjc3OCwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjoiYzIxNThiMDAyMWVkNDJiYmI2NGVlMWNjMmU1MzQ3NDEiLCJub25jZSI6IjllZGNjMTdiLThkMTMtNGI4My04M2VhLTNkZWIxMDQ4ZTM0NCIsImF1dGhfdGltZSI6MTU0MjAxNjQ3OCwiY19oYXNoIjoiazB1QlhqbF9pdF9tT2JvRE5wSTR1USIsInNfaGFzaCI6IjZjN25Hcmt5X2Voak00MEl2azNwM3cifQ.AycZlfTkTuHhEW_7GyWU_h12XszrNzs4Z47tPA9xPRcjpPG-ret7oNhi1pMlO2uiC7VcXPd_uwg_6V7KbKEj8CkpZ3IRibAMgF12OhNUaYRL8Kboopic9JpvU4SH0wgR4_SfixusjQYm2a7MsT11FFA7vvzZzKDh0mW8NRkin3tZ4PWoD-4NAuO8OFHtQ5ZTCSNqwASXdQlUyuiNYW1xq26irLhmD5E4u6g02urcKB5BCGsqEByVddYlqNB2TwNyJBz3kW033X__icIWEe9isJHqtXhe-7y2wrEHVLwDVTZzN2Z5dXPVJB82JEsXl_qeVTdpDJNdZB7n1HeIIBB6jA&state=abcd1234


  

Copy code
  
  
  
  

The response claims are encoded within the id_token query parameter. (They can
be decoded using JWT.io):

{
  "sub": "c2158b0021ed42bbb64ee1cc2e534741",
  "aud": "7xPKBspndegEsfR2f2Fss2s",
  "jti": "dvfhQxeWvq76gsO69xKF70",
  "iss": "https://secure1t.natwest.com",
  "iat": 1542016478,
  "exp": 1542016778,
  "openbanking_intent_id": "c2158b0021ed42bbb64ee1cc2e534741",
  "nonce": "9edcc17b-8d13-4b83-83ea-3deb1048e344",
  "auth_time": 1542016478,
  "c_hash": "k0uBXjl_it_mOboDNpI4uQ",
  "s_hash": "6c7nGrky_ehjM40Ivk3p3w"
}

  

Copy code
  
  
  
  


EXCHANGING AN AUTHORISATION CODE FOR AN ACCESS TOKEN

In this step the token endpoint is used via an OAuth Hybrid Flow to exchange the
authorisation code generated during the consent process for an Access Token.
This endpoint is protected by Mutual TLS. On submission of an authorisation code
it returns:

 * An Access Token;
 * A Refresh Token;
 * A signed JWT containing, amongst other things, the Intent ID corresponding to
   the returned Access Token;

Note:- At this time the NatWest Authorisation endpoint uses RSA256 for ID Token
signing.

You can use the latter to correlate the response with the request. To that end,
the sub and openbanking_intent_id claims contain the related Intent ID.
Additionally the c_hash and s_hash fields contain, respectively, hashes of the
passed in state and code parameters. For more details on the c_hash see the Open
ID Connect documentation. For s_hash see the FAPI documentation.

The Access Token has fixed validity. See Access Token/Refresh Token Exchange for
details on obtaining a new token once the original expires.

CODE VERIFIER AND PKCE

The token endpoint requires each request to include a code_verifier as per the
PKCE RFC to prevent man-in-the-middle attacks.

EXAMPLE

Example Request:

POST https://secure1t.natwest.com/as/token.oauth2 HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Body: code_verifier=RczZn-l7WMCUIiKQLNcWBXHVNfb1_IR25rGwY1nNAt8&code_challenge_method=S256&code=vRZs_yPSuzsap3BIW9w7CmzgEgJ3MFCsLVkAAAAE&grant_type=authorization_code&redirect_uri=https://developer.natwest.com/dummy_redirect.htm&client_id=7xPKBspndegEsfR2f2Fss2s

  

Copy code
  
  
  
  

Example Response:

HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8
Content-Length: 868
Date: Mon, 12 Nov 2018 09:54:38 GMT

{
    "access_token": "zlJojElfSalTBc1CKVwi3adSHPpr",
    "refresh_token": "EhRx3DsdmpU4J8ISVBeVYj5v5l2I2oDorfEVgbPcft",
    "scope": "openid payments",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ikg4OVBtWGx0VXVlVmFLLS1uVlNZM2c2SlBxYyJ9.eyJzdWIiOiJjMjE1OGIwMDIxZWQ0MmJiYjY0ZWUxY2MyZTUzNDc0MSIsImF1ZCI6IjZ4UFVIeG1TbU44bGZMMkZienV4M3MiLCJqdGkiOiJkdmZoUXhlV3ZxNzZnc082OXhLRjcwIiwiaXNzIjoiaHR0cHM6Ly9pYW0tYXV0aG4tc2l0LW53Yi5tYW5hZ2VkdGVzdC5jb20iLCJpYXQiOjE1NDIwMTY0NzgsImV4cCI6MTU0MjAxNjc3OCwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjoiYzIxNThiMDAyMWVkNDJiYmI2NGVlMWNjMmU1MzQ3NDEiLCJub25jZSI6IjllZGNjMTdiLThkMTMtNGI4My04M2VhLTNkZWIxMDQ4ZTM0NCIsImF1dGhfdGltZSI6MTU0MjAxNjQ3OCwiY19oYXNoIjoiazB1QlhqbF9pdF9tT2JvRE5wSTR1USIsInNfaGFzaCI6IjZjN25Hcmt5X2Voak00MEl2azNwM3cifQ.AycZlfTkTuHhEW_7GyWU_h12XszrNzs4Z47tPA9xPRcjpPG-ret7oNhi1pMlO2uiC7VcXPd_uwg_6V7KbKEj8CkpZ3IRibAMgF12OhNUaYRL8Kboopic9JpvU4SH0wgR4_SfixusjQYm2a7MsT11FFA7vvzZzKDh0mW8NRkin3tZ4PWoD-4NAuO8OFHtQ5ZTCSNqwASXdQlUyuiNYW1xq26irLhmD5E4u6g02urcKB5BCGsqEByVddYlqNB2TwNyJBz3kW033X__icIWEe9isJHqtXhe-7y2wrEHVLwDVTZzN2Z5dXPVJB82JEsXl_qeVTdpDJNdZB7n1HeIIBB6jA",
    "token_type": "Bearer",
    "expires_in": 599
}

  

Copy code
  
  
  
  

The response claims are base64url encoded within the value of id_token in the
response body. (They can be decoded using JWT.io):

{
  "alg": "RS256",
  "kid": "abcd-1234"
}
{
  "sub": "c2158b0021ed42bbb64ee1cc2e534741",
  "aud": "7xPKBspndegEsfR2f2Fss2s",
  "jti": "dvfhQxeWvq76gsO69xKF70",
  "iss": "https://secure1t.natwest.com",
  "iat": 1542016478,
  "exp": 1542016778,
  "openbanking_intent_id": "c2158b0021ed42bbb64ee1cc2e534741",
  "nonce": "9edcc17b-8d13-4b83-83ea-3deb1048e344",
  "auth_time": 1542016478,
  "c_hash": "k0uBXjl_it_mOboDNpI4uQ",
  "s_hash": "6c7nGrky_ehjM40Ivk3p3w"
}

  

Copy code
  
  
  
  


SUBMITTING A PAYMENT REQUEST AGAINST THE VRP CONSENT

Once the VRP consent has been confirmed and you have the necessary tokens, you
may submit a payment request via the APIs. Payment tokens are per consent and
must correspond to the specific API request.

The API specifications further down this page contain request/response examples,
including tokens, for each endpoint.

EXAMPLES

Example domestic-vrps request:

POST https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrps HTTP/1.1
Accept: application/json
Authorization: Bearer zlJojElfSalTBc1CKVwi3adSHPpr
x-fapi-interaction-id: 77f38da0-9172-42a9-99b9-2ab1045accf2
x-fapi-customer-ip-address: 127.0.0.1
x-fapi-financial-id: 0015800000jfwxXAAQ
x-idempotency-key: dd31a7b3-ea04-4288-b06a-8437f6aca739
Content-Type: application/json

{
	"Data": {
		"ConsentId": "6710128983094680bbe01eed6e9e8d71",
		"PSUAuthenticationMethod": "UK.OBIE.SCANotRequired",
		"vrpType": "UK.OBIE.VRPType.Sweeping",
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "Joe Bloggs"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		},
		"Instruction": {
			"InstructionIdentification": "12345687654319",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "10",
				"Currency": "GBP"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "Joe Bloggs"
			}
		}
	},
	"Risk": {
		
	}
}

  

Copy code
  
  
  
  

Example Response:

HTTP/1.1 201 Created
x-fapi-interaction-id: 77f38da0-9172-42a9-99b9-2ab1045accf2
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Content-Length: 522

{
	"Data": {
		"DomesticVRPId": "16e53daf65a44484928a3d66b82b122a",
		"ConsentId": "6710128983094680bbe01eed6e9e8d71",
		"CreationDateTime": "2021-10-18T14:05:43.993+01:00",
		"Status": "AcceptedSettlementCompleted",
		"StatusUpdateDateTime": "2021-10-18T14:05:43.993+01:00",
		"Initiation": {
			"DebtorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "12345612345678",
				"Name": "Joe Bloggs"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "Joe Bloggs"
			},
			"RemittanceInformation": {
				"Unstructured": "UNSTRUCTURED",
				"Reference": "REFERENCE"
			}
		},
		"Instruction": {
			"InstructionIdentification": "12345687654319",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "10",
				"Currency": "GBP"
			},
			"CreditorAccount": {
				"SchemeName": "UK.OBIE.SortCodeAccountNumber",
				"Identification": "00000012345678",
				"Name": "Joe Bloggs"
			}
		},
		"DebtorAccount": {
			"SchemeName": "UK.OBIE.SortCodeAccountNumber",
			"Identification": "12345612345678",
			"Name": "Joe Bloggs"
		}
	}
  "Links": {
    "Self": "https://api.natwest.com/open-banking/v3.1/pisp/domestic-vrps/16e53daf65a44484928a3d66b82b122a"
  },
  "Meta": {
    "TotalPages": 1
  }
}

  

Copy code
  
  
  
  

ACCESS TOKEN VALIDITY PERIOD

Access tokens to submit a payment request are valid for 10 minutes. If the token
has expired after this period a new one can be obtained by using the associated
refresh token. Access tokens can only be used for the specific VRP consent that
they have been granted for. There is no time limit on a refresh token.


SECURITY CONSIDERATIONS

The APIs are protected by a number of standards-based controls both at the
application level and the network level.


TLS REQUIREMENTS

All endpoints are secured using Transport Layer Security (TLS1.2). Browser-based
journeys are HTTPS with HSTS.

CIPHERS

The Open Banking Directory will only support the generation of certificates
using RSA.

The FAPI Read Write Specification specifies the algorithms that should be used
for TLS (Section 8.5) and for digital signatures (Section 8.6).

In accordance with Section 8.5, only the following ciphers will be supported for
TLS:

 * TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
 * TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
 * TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
 * TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

MUTUAL TLS

All API endpoints (excluding the authorisation journey) require you to
authenticate yourself using mTLS by passing your X.509 digital certificate. You
must send the entire certificate chain with the certificate otherwise the
request will be rejected.


MESSAGE SIGNING

The Payment Initiation APIs mandate that all inbound requests must be digitally
signed by the API consumer and all responses likewise are signed by us. This is
to assure the request and responses originated by the private key holder and
that no message tampering has occurred.


API ENDPOINTS

Each API endpoint delivering customer data is protected by the following
controls:

 * Mutual Transport Layer Security (TLS1.2)
 * Access Token - The OAuth Access Token must be valid and belong to the client
   application initiating the request.
 * Access confirmation - The Access Token and Intent ID sent with each request
   must correlate with one another.
 * Scope - The scope of the Access Token must correspond to the scope required
   to access that particular API endpoint. In the case of the Payments API this
   is the payments scope.

REQUIRED HEADERS

You must pass our unique financial ID with every request in the
x-fapi-financial-id header. The financial ID for NatWest is 0015800000jfwxXAAQ.

We recommend passing a globally unique x-fapi-interaction-id header to be used
as a correlation ID. This should be unique for each and every interaction we us.
If no x-fapi-interaction-id header is passed, we will generate one. The
generated value will be a GUID. In either case the value of this header will be
returned in the response.

Note:- Please include the x-fapi-interaction-id in any support requests. It will
greatly expedite the investigation.

REFRESHING AN ACCESS TOKEN

Each Access Token lasts for only a limited period. Once expired, the Refresh
Token must be used to generate a new Access Token. This can happen any number of
times however aeach refresh token can only be used once, it will return a new
refresh token to be used the nexct time. Tokens are refreshed using the Token
endpoint. This endpoint is protected by Mutual TLS.

Example Refresh Request:

POST https://secure1t.natwest.com/as/token.oauth2 HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Body: grant_type=refresh_token&client_id=7xPKBspndegEsfR2f2Fss2s&refresh_token=EhRx3DsdmpU4J8ISVBeVYj5v5l2I2oDorfEVgbPcft


  

Copy code
  
  
  
  

Example Response:

HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8
Content-Length: 102


{
  "access_token": "x2gZxLWT3QkzAcXPrRMJVZXDGfJG",
  "token_type": "Bearer",
  "expires_in": 599
}

  

Copy code
  
  
  
  

ACCESS AND REFRESH TOKEN VALIDITY PERIOD

Each Access Token lasts 10 minutes. There is no time limit on a refresh token.


DOMESTIC VRP CONSENTS

For VRP Consents the following should be noted:

 * You must supply creditor details and remittance info in the consent creation.
 * The only supported payment scheme is UK.OBIE.SortCodeAccountNumber.
 * VRP Consents can not be amended or changed. To change the terms you must
   cancel the existing consent and create a new one.
 * For non-sweeping use cases an optional merchant name field can be included.
   This is the everyday business name that the customer interacts with (as
   opposed to the TPP name). This may be different to the registered company
   name. It will be used to help the customer identify the final transaction
   beneficiary.
 * VRP Consents can be revoked by a customer via the NatWest Consent Store, in
   this case an event will be sent via the event API. A consent revoked in this
   way may be re-authorised using an OAuth Authorisation Request as per the
   original authorisation request.
 * VRP Consents can also be revoked using the "DELETE" function of the
   /Domestic-Vrp-Consents endpoint. Consents revoked in this way cannot be
   re-authorised.
 * For more information about the changes to revocation consult the Open Banking
   Documentation. One idiosyncrasy is that a consent revoked via our Consent
   Store will remain in "Authorised" status when retrieved via the GET
   /Domestic-Vrp-Consents endpoint. A consent revoked via the DELETE
   /Domestic-Vrp-consents endpoint will not be retrievable.


CONTROL PARAMETERS

 * If no "from date" is specified the from date will be the date of
   authorization.

 * If no "to date" is specified the VRP Consent will be active until manually
   cancelled.

 * For all VRPs a periodic limit must be specified.

 * For sweeping you may only specify
   
   * Maximum Individual Amount
   * Periodic "Amount" limits

 * For the discretionary/Other VRP you may also use:
   
   * Maximum Cumulative Amount
   * Maximum Cumulative Number of Payments
   * Periodic "Number of Payments" limits


DOMESTIC VRPS

For VRPs the following should be noted.

 * All creditor and remittance information must exactly match the consent.

 * All VRPs will be put through as Faster Payments. CHAPS payments are not
   supported.

 * Payments to another person, business or account with another bank

 * If you are making a payment after 6.30pm, on a weekend, or a Bank holiday,
   the payment will normally leave your account immediately and be available in
   the recipient bank account within a few hours.

 * The date displayed when making the payment and on your statement will be the
   next working day.

Download API Spec (JSON)


OBIE VRP PROFILE

 3.1.11 

OAS3

VRP OpenAPI Specification

Terms of service
the developer - Website
open-licence
Servers
https://api.natwest.com/open-banking/v3.1/pisp - Natwest API
Authorize



DOMESTIC VRP CONSENTS


POST/domestic-vrp-consents
Create a domestic VRP consent
GET/domestic-vrp-consents/{ConsentId}
Retrieve a domestic VRP consent
DELETE/domestic-vrp-consents/{ConsentId}
Delete a domestic VRP
POST/domestic-vrp-consents/{ConsentId}/funds-confirmation
Confirm availability of funds for a VRP


DOMESTIC VRPS


POST/domestic-vrps
Create a domestic VRP
GET/domestic-vrps/{DomesticVRPId}
Retrieve a domestic VRP
GET/domestic-vrps/{DomesticVRPId}/payment-details
Retrieve a domestic VRP

SCHEMAS

OBError1
OBErrorResponse1
OBDomesticVRPConsentResponse
OBDomesticVRPConsentRequest
OBDomesticVRPControlParameters
OBDomesticVRPInitiation
OBCashAccountDebtorWithName
OBCashAccountCreditor3
OBBranchAndFinancialInstitutionIdentification6
OBDomesticVRPRequest
OBDomesticVRPResponse
OBDomesticVRPDetails
OBVRPFundsConfirmationRequest
OBVRPFundsConfirmationResponse
OBPAFundsAvailableResult1
OBCharge2
OBExternalStatus2Code
OBChargeBearerType1Code
OBDomesticVRPInstruction
OBVRPRemittanceInformation
OBExternalAccountIdentification4Code
OBExternalFinancialInstitutionIdentification4Code
OBExternalAccountType1Code
OBExternalExtendedAccountType1Code
OBExternalLocalInstrument1Code
OBActiveOrHistoricCurrencyAndAmount
ActiveOrHistoricCurrencyCode
OBActiveCurrencyAndAmount_SimpleType
OBExternalPaymentChargeType1Code
OBPostalAddress6
OBAddressTypeCode
Department
SubDepartment
StreetName
BuildingNumber
PostCode
TownName
CountrySubDivision
CountryCode
OBVRPStatusReasonCode
OBVRPConsentType
OBVRPAuthenticationMethods
OBVRPInteractionTypes
OBRisk1
Links
MetaData
OBErrorCode


TEST IN THE API SANDBOX

NatWest
581BEE5A-6C71-4D77-8A80-543BD61F66CF@1x
 * Sandbox
 * Terms and conditions
 * More about NatWest Group
 * Accessibility
 * Cookie policy
 * Privacy notice
 * Service interruptions

© 2024 NatWest Group





WE CARE ABOUT YOUR PRIVACY

We use cookies to ensure our website works properly. To help us improve our
service, we collect data to understand how people use our site. By allowing all
cookies, we can enhance your experience even further. This means helping you
find information more quickly and tailoring content or marketing to your needs.
Select “Allow All Cookies” to agree or “Manage Preferences” to manage cookie
settings. You can find out more by viewing our Cookie Policy

Allow All Cookies
Manage Preferences



PRIVACY PREFERENCE CENTER

When you visit any website, it may store or retrieve information on your
browser, mostly in the form of cookies. This information might be about you,
your preferences or your device and is mostly used to make the site work as you
expect it to. The information does not usually directly identify you, but it can
give you a more personalized web experience. Because we respect your right to
privacy, you can choose not to allow some types of cookies. Click on the
different category headings to find out more and change our default settings.
However, blocking some types of cookies may impact your experience of the site
and the services we are able to offer.
More information
Allow All Cookies


MANAGE CONSENT PREFERENCES

STRICTLY NECESSARY COOKIES

Always Active

These cookies are necessary for the website to function and cannot be switched
off in our systems. They are usually only set in response to actions made by you
which amount to a request for services, such as setting your privacy
preferences, logging in or filling in forms. You can set your browser to block
or alert you about these cookies, but some parts of the site will not then work.
These cookies do not store any personally identifiable information.

Cookies Details‎
Back Button


PERFORMANCE COOKIES



Search Icon
Filter Icon

Clear
checkbox label label
Apply Cancel
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label

 * 
   
   View Cookies
   
    * Name
      cookie name

Confirm My Choices

Your Privacy [`dialog closed`]