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