# Domestic VRPS - v4.0

# 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.

# Status

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

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

Status
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)) :

Status
PDNG
ACTC
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 status codes:

Status
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

Payment Order Status

# Data Model

# OBDomesticVRPInstruction

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. For a full list of enumeration values refer to OB_Internal_CodeSet here (opens new window) OBInternalLocalInstrument1Code
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
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. OBPostalAddress7
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

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. If not provided the default is "OffSession" (customer is not present) when the individual VRP payment is made. 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. OBRisk1

# OBDomesticVRPResponse

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
Status (1..1) Data. Status Specifies the status of the payment information group. For a full list of values see ExternalPaymentTransactionStatus1Code here (opens new window)
StatusUpdateDateTime (1..1) Data. StatusUpdateDateTime Date and time at which the resource Status was updated. ISODateTime
StatusReason (0..*) Data. StatusReason Array of StatusReasonCode. OBStatusReason
StatusReasonCode (0..1) Data. StatusReason. StatusReasonCode Specifies the status reason in a code form. For a full description see OB_Internal_CodeSet here (opens new window). OBExternalStatusReason1Code
StatusReasonDescription (0..1) Data.StatusReason. StatusReasonDescription Description supporting the StatusReasonCode Max500Text
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..*) 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

OBDomesticVRPDetails

Name Path Definition Type
Data (1..1) Data
PaymentStatus (0..*)
PaymentTransactionId (1..1) Data. PaymentTransactionId Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable. Max210Text
Status (1..1) Data. Status Status of a transfer, as assigned by the transaction administrator. See ExternalPaymentTransactionStatus1Code in External codeset list (opens new window)
StatusUpdateDateTime (1..1) Data. StatusUpdateDateTime Date and time at which the resource Status was updated. ISODateTime
StatusDetail (0..*) Data. StatusDetail Payment status details as per underlying Payment Rail.
LocalInstrument (0..1) Data. PaymentStatus. StatusDetail. 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. For a full list of values see OBInternalLocalInstrument1Code in OB_Internal_CodeSet here (opens new window)
Status (1..1) Data. StatusDetail. Status Status of a transfer, as assigned by the transaction administrator. ExternalPaymentTransactionStatus1Code For a full list of values see External_CodeSet here (opens new window)
StatusReason (0..1) Data. StatusDetail. StatusReason Reason code for the Status Code update. Specifies the status reason using the Code Value of OBExternalStatusReason1Code. For a full list of values see OBExternalStatusReason1Code in OB_Internal_CodeSet here (opens new window)
StatusReasonDescription (0..1) Data. StatusDetail. StatusReasonDescription Reason provided for the status of a transfer using the Code Name of OBExternalStatusReason1Code For a full list of values see OBExternalStatusReason1Code in OB_Internal_CodeSet here (opens new window)

# Usage Examples

See Usage Examples