# # Domestic VRPS - v4.0-draft1

- Overview
- Endpoints
  - POST /domestic-vrps
    - StatusCode
  - GET /domestic-vrps/{DomesticVRPId}
  - GET /domestic-vrps/{DomesticVRPId}/payment-details
- State Model
  - Payment Order
- Data Model
  - OBDomesticVRPInstruction
  - OBDomesticVRPRequest
  - OBDomesticVRPResponse
  - OBDomesticVRPDetails
- Usage Examples

## # Overview

The Domestic VRPs resource is used by a TPP to initiate a domestic payment, under an authorised VRP Consent.

This resource description should be read in conjunction with a compatible Payment Initiation API Profile.

## # Endpoints

Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
domestic-vrps | POST | POST /domestic-vrps | Conditional | payments | Authorization Code | Signed Request Signed Response | Yes | OBDomesticVRPRequest | OBDomesticVRPResponse
domestic-vrps | GET | GET /domestic-vrps/{DomesticVRPId} | Conditional | payments | Client Credentials | Signed Response | No | NA | OBDomesticVRPResponse
domestic-vrps | GET | GET /domestic-vrps/{DomesticVRPId}/payment-details | Optional | payments | Client Credentials | Signed Response | No | NA | OBDomesticVRPDetails

### # POST /domestic-vrps

Once a `domestic-vrp-consents` has been authorised by the PSU, the TPP can proceed to submitting a `domestic-vrps` for processing.

This is done by making a POST request to the `domestic-vrps` endpoint.

This request is an instruction to the ASPSP to begin the domestic single immediate payment journey. The domestic payment must be executed immediately, however, there are some scenarios where the domestic payment may not be executed immediately (e.g., busy periods at the ASPSP).

The TPP must ensure that the `Initiation` and `Risk` section matches the values specified in the consent.

The ASPSP must ensure that the payment instruction adheres to the limitations set by the corresponding VRP consent's `ControlParameters`.

When a payment would breach a limitation set by one or more `ControlParameters`, the ASPSP must return an error with code `U014` and pass in the control parameter field that caused the error in the `Field` field of the error message.

If the `CreditorAccount` was not specified in the the consent, the `CreditorAccount` must be specified in the instruction.

The TPP must ensure that the end-point is called with the same scope as the one used for the corresponding consent.

The ASPSP must reject a payment that has `Data.Instruction.SupplementaryData` that it cannot process.

#### # StatusCode

A `domestic-vrps` can only be created if its corresponding `domestic-vrp-consents` resource has the StatusCode of `AUTH`.

The `domestic-vrps` resource that is created successfully must have one of the following `PaymentStatusCode` values

StatusCode
RCVD
PDNG
ACTC
RJCT

### # GET /domestic-vrps/{DomesticVRPId}

Once the domestic vrp is created, a TPP can retrieve the `domestic-vrps` to check its status by using this endpoint.

The domestic-vrp resource must have one of the following ExternalPaymentTransactionStatus1Code code-set enumerations (for more information see `ExternalPaymentTransactionStatus1Code` here
(opens new window)) :

StatusCode
PDNG
ACTC
PATC
ACCP
ACFC
ACSP
ACWC
ACSC
ACWP
ACCC
BLCK
RJCT
RCVD

### # GET /domestic-vrps/{DomesticVRPId}/payment-details

A TPP can retrieve the details of the underlying payment transaction via this endpoint. This resource allows ASPSPs to return a richer list of Payment Statuses, and if available payment scheme related statuses.

The API must return one of the following StatusCodes:

StatusCode
RCVD
PDNG
ACTC
ACCP
ACFC
ACSP
ACWC
ACSC
ACWP
ACCC
BLCK
RJCT

## # State Model

### # Payment Order

The state model for the `domestic-vrps` resource follows the behavior and definitions for the ISO 20022 PaymentStatusCode code-set.

Note: Multi-authorisation is not currently supported in VRP.

Payment order state model key:

Colour (Style) | Description
--- | ---
Green (Bold) | Mandatory
Orange (Italic) | Optional, but recommended

## # Data Model

### # OBDomesticVRPInstruction

Name | Path | Definition | Type
--- | --- | --- | ---
InstructionIdentification (1..1) | `InstructionIdentification` | Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. | Max35Text
EndToEndIdentification (1..1) | `EndToEndIdentification` | Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field. | Max35Text
RemittanceInformation (0..1) | `RemittanceInformation` | Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. | OBRemittanceInformation1
LocalInstrument (0..1) | `LocalInstrument` | User community specific instrument. Usage: This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level. | OBExternalLocalInstrument1Code
InstructedAmount (1..1) | `InstructedAmount` | Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain. | OBActiveOrHistoricCurrencyAndAmount
Amount (1..1) | `InstructedAmount. Amount` | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. | OBActiveCurrencyAndAmount_SimpleType
Currency (1..1) | `InstructedAmount. Currency` | A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". | ActiveOrHistoricCurrencyCode
CreditorAgent (0..1) | `CreditorAgent` | Financial institution servicing an account for the creditor. | OBBranchAndFinancialInstitutionIdentification6
CreditorAccount (1..1) | `CreditorAccount` | Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. | OBCashAccountCreditor3
CreditorPostalAddress (0..1) | `CreditorPostalAddress` | Information that locates and identifies a specific address, as defined by postal services. | OBPostalAddress6
UltimateCreditor (0..1) | `UltimateCreditor` | Ultimate party to which an amount of money is due. | OBUltimateCreditor1
SupplementaryData (0..1) | `SupplementaryData` | Additional information that can not be captured in the structured fields and/or any other specific block |

### # OBDomesticVRPRequest

Name | Path | Definition | Type
--- | --- | --- | ---
Data (1..1) | `Data` |  |
PSUAuthenticationMethod (1..1) | `Data. PSUAuthenticationMethod` | The authentication method that was used to authenicate the PSU. | OBVRPAuthenticationMethods - Namespaced Enumeration
PSUInteractionType (0..1) | `Data. PSUInteractionType` | Indicates interaction type, currently if customer is present or not present. | OBVRPInteractionTypes
VRPType (1..1) | `Data. VRPType` | The type of payment being made under the VRP consent. This can be used to indicate whether this include sweeping payment or other ecommerce payments. | OBVRPConsentType - Namespaced Enumeration
ConsentId (1..1) | `Data. ConsentId` | Identifier for the Domestic VRP Consent that this payment is made under | Max128Text
Initiation (1..1) | `Data. Initiation` | The parameters of the VRP consent that should remain unchanged for each payment under this VRP. | OBDomesticVRPInitiation
Instruction (1..1) | `Data. Instruction` | Specific instructions for this particular payment within the VRP consent | OBDomesticVRPInstruction
Risk (1..1) | `Risk` | The risk block for this payment. This must match the risk block for the corresponding Domestic VRP consent. | OBRisk2

### # OBDomesticVRPResponse

Name | Path | Definition | Type
--- | --- | --- | ---
Data (1..1) | `Data` |  |
DomesticVRPId (1..1) | `Data. DomesticVRPId` | OB: Unique identification as assigned by the ASPSP to uniquely identify the domestic payment resource. | Max40Text
ConsentId (1..1) | `Data. ConsentId` | Identifier for the Domestic VRP Consent that this payment is made under | Max128Text
CreationDateTime (1..1) | `Data. CreationDateTime` | Date and time at which the message was created. | ISODateTime
StatusCode (1..1) | `Data. StatusCode` | Specifies the status of the payment information group. | RCVD PDNG ACTC ACCP ACFC ACSP ACWC ACSC ACWP ACCC BLCK RJCT
StatusUpdateDateTime (1..1) | `Data. StatusUpdateDateTime` | Date and time at which the resource StatusCode was updated. | ISODateTime
StatusReason (0..*) | `Data. StatusReason` | Array of StatusReasonCode. | Array
StatusReasonCode (0..1) | `Data. StatusReason. StatusReasonCode` | Specifies the status reason in a code form. For a full description see `ExternalStatusReason1Code` here (opens new window). | ExternalStatusReason1Code
StatusReasonDescription (0..1) | `Data.StatusReason. StatusReasonDescription` | Description supporting the StatusReasonCode | Max256Text
Path (0..1) | `Data. StatusReason. Path` | Path is optional but relevant when the status reason refers to an object/field and hence conditional to provide JSON path. | Max500Text
ExpectedExecutionDateTime (0..1) | `Data. ExpectedExecutionDateTime` | Expected execution date and time for the payment resource. | ISODateTime
ExpectedSettlementDateTime (0..1) | `Data. ExpectedSettlementDateTime` | Expected settlement date and time for the payment resource. | ISODateTime
Refund (0..1) | `Data. Refund` | Unambiguous identification of the refund account to which a refund will be made as a result of the transaction. This object is populated only when `Data. ReadRefundAccount` is set to `Yes` in the consent. | OBDomesticRefundAccount1
Charges (0..n) | `Data. Charges` | Set of elements used to provide details of a charge for the payment initiation. | OBCharge2
Initiation (1..1) | `Data. Initiation` | The parameters of the VRP consent that should remain unchanged for each payment under this VRP. | OBDomesticVRPInitiation
Instruction (1..1) | `Data. Instruction` | Specific instructions for this particular payment within the VRP consent | OBDomesticVRPInstruction
DebtorAccount (0..1) | `Data.DebtorAccount` | The approved DebtorAccount that the payment was made from. | OBCashAccountDebtorWithName

### # OBDomesticVRPDetails

Name | Path | Definition | Type
--- | --- | --- | ---
Data (1..1) | `Data` |  |
LocalInstrument (0..1) | `Data. LocalInstrument` | User community specific instrument. Usage: This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level. | OBExternalLocalInstrument1Code
PaymentTransactionId (1..1) | `Data. PaymentTransactionId` | Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable. | Max210Text
StatusCode (1..1) | `Data. StatusCode` | Status of a transfer, as assigned by the transaction administrator. | Values: RCVD PDNG ACTC ACCP ACFC ACSP ACWC ACSC ACWP ACCC BLCK RJCT (See `ExternalPaymentTransactionStatus1Code` in External codeset list (opens new window))
StatusUpdateDateTime (1..1) | `Data. StatusUpdateDateTime` | Date and time at which the resource StatusCode was updated. | ISODateTime
StatusDetail (0..*) | `Data. StatusDetail` | Array of StatusCodes | Array
StatusCode (1..1) | `Data. StatusDetail. StatusCode` | Status of a transfer, as assigned by the transaction administrator. | Max4Text
StatusReasonCode (0..1) | `Data. StatusDetail. StatusReason` | Reason code for the Status Code update | Specifies the status reason in a code form. For a full description see `ExternalStatusReason1Code` [here](https://github.com/OpenBankingUK/
StatusReasonDescription (0..1) | `Data. StatusDetail. StatusReasonDescription` | Reason provided for the status of a transfer. | Max256Text
StatusUpdateDateTime (1..1) | `Data. StatusDetail. StatusUpdateDateTime` | Date and time at which the resource StatusCode was updated. | ISODateTime

## # Usage Examples

See Usage Examples