Create Consent

User consent is the foremost requirement to authorize Singleview and enable the PIS module to:

Register an intent to initiate a payment
Access payment details to track the payment status or get the transaction details

Here are the details to understand consent creation for PIS module through Singleview:

Endpoint details

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/pisp/createconsent`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to create a payment consent

Request to create consent - sample

{
    "SVPaymentConsentRequest": {
        "DateTimeStamp": "2022-07-25T17:51:03",
        "RequestID": "{{RequestID}}",
        "userName": "{{userName}}",
        "SVPaymentConsentInfoMessage": [
            {
                "SVPaymentConsentInfoRequest": {
                    "BankCode": "SAMA",
                    "Data": {
                        "Initiation": {
                            "InstructionIdentification": "1254521522",
                            "EndToEndIdentification": "12545245515151522",
                            "InstructedAmount": {
                                "Amount": 667.61,
                                "Currency": "GBP"
                            },
                            "CreditorAccount": {
                                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                                "Identification": "12345678901234",
                                "Name": "Daniel Group"
                            },
                            "RemittanceInformation": {
                                "Reference": "test 8898",
                                "Unstructured": "9113 repellat quis rem"
                            }
                        }
                    },
                    "Risk": {}
                }
            }
        ]
    }
}

Description:

JSON Tag	Description	Data type
SVPaymentConsentRequest Mandatory	Create payment consent request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVPaymentConsentInfoMessage Mandatory	Create payment consent information message tag	Object
SVPaymentConsentInfoRequest Mandatory	Create payment consent information request tag	Object
BankCode Mandatory	Unique bank code for identification	String
Data Mandatory	Data tag representing the set of data included in the request	Object
Initiation Mandatory	Initiation payload sent by the initiating party to the ASPSP to request movement of funds	Object
InstructionIdentification Mandatory	Point-to-point reference of individual instructions	String
EndToEndIdentification Mandatory	Unique identification used for reconciliation or to link tasks relating to the transaction	String
InstructedAmount Mandatory	Ordered amount to be moved between the debtor and creditor	Object
Amount Mandatory	Specified amount to be processed	String
Currency Mandatory	The currency of the amount used in transaction	String
CreditorAccount Mandatory	Account information of the creditor tag	Object
SchemeName Mandatory	Name of the account's identification scheme	String
Identification Mandatory	Unique identification of the servicing institution	String
Name Mandatory	Name(s) of the account holder or owner	String
RemittanceInformation Mandatory	Description of the payment	Object
Reference Mandatory	Assigned by the creditor to refer to the payment transaction	String
Unstructured Mandatory	Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.	String
Risk Mandatory	Risk description & disclaimer	String

Successfully created consent response - sample

{
    "success": true,
    "message": "",
    "SVPaymentConsentResponse": {
        "SVPaymentConsentInfoMessage": [
            {
                "SVPaymentConsentInfoResponse": {
                    "Data": {
                        "Initiation": {
                            "InstructionIdentification": "1254521522",
                            "EndToEndIdentification": "12545245515151522",
                            "InstructedAmount": {
                                "Amount": 667.61,
                                "Currency": "GBP"
                            },
                            "CreditorAccount": {
                                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                                "Identification": "12345678901234",
                                "Name": "Daniel Group"
                            },
                            "RemittanceInformation": {
                                "Reference": "test 8898",
                                "Unstructured": "9113 repellat quis rem"
                            }
                        },
                        "ConsentId": "pay-di-679b5a8e-7993-42d4-8c5c-c22f505555ce",
                        "Status": "AwaitingAuthorisation",
                        "CreationDateTime": "2022-07-25T11:27:36.639Z",
                        "StatusUpdateDateTime": "2022-07-25T11:27:36.639Z",
                        "consentId": "pay-di-679b5a8e-7993-42d4-8c5c-c22f505555ce"
                    },
                    "Risk": {},
                    "Links": {
                        "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/pisp/domestic-payment-consents/pay-di-679b5a8e-7993-42d4-8c5c-c22f505555ce"
                    },
                    "Meta": {},
                    "BankCode": "SAMA",
                    "scope": "openid payments",
                    "state": "67eddad6-9058-4c6d-9bd5-92ffa57130d3",
                    "bankRedirectURL": "https://auth1.lab.openbanking.sa/auth?client_id=9f97a211-6f57-4239-bbe4-2b4654ba6af6&response_type=code&scope=openid%20payments&request=eyJhbGciOiJub25lIn0.eyJhdWQiOiJodHRwczovL2F1dGgxLmxhYi5vcGVuYmFua2luZy5zYSIsImV4cCI6MTY1ODc0OTA1NywiaXNzIjoiOWY5N2EyMTEtNmY1Ny00MjM5LWJiZTQtMmI0NjU0YmE2YWY2Iiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3VhdC5vbmVzaW5nbGV2aWV3LmNvbS9vcGVuYmFua2luZy9hdXRob3Jpc2UvVTBGTlFRPT0iLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6IjlmOTdhMjExLTZmNTctNDIzOS1iYmU0LTJiNDY1NGJhNmFmNiIsIm5vbmNlIjoiMDQ0MjhkODMtYjcwNS00NzIyLWE5MTItYWZjOGQ3NDRiYmU2Iiwic3RhdGUiOiI2N2VkZGFkNi05MDU4LTRjNmQtOWJkNS05MmZmYTU3MTMwZDMiLCJuYmYiOjE2NTg3NDc1NTcsImxvZ2luX2hpbnQiOiJyYXN0YW1hbiIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJwYXktZGktNjc5YjVhOGUtNzk5My00MmQ0LThjNWMtYzIyZjUwNTU1NWNlIiwiZXNzZW50aWFsIjp0cnVlfX19fQ.",
                    "Token": "deb456b2-1b48-42cf-9810-85e57f7c0d89"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVPaymentConsentResponse	Create payment consent response tag
SVPaymentConsentInfoMessage	Create payment consent information message tag
SVPaymentConsentInfoResponse	Payment consent information response tag
Data	Data tag representing the set of data included in the request
Initiation	Initiation payload sent by the initiating party to the ASPSP to request movement of funds
InstructionIdentification	Point-to-point reference of individual instructions
EndToEndIdentification	Unique identification used for reconciliation or to link tasks relating to the transaction
InstructedAmount	Ordered amount to be moved between the debtor and creditor
Amount	Specified amount to be processed
Currency	The currency of the amount used in transaction
CreditorAccount	Account information of the creditor tag
SchemeName	Name of the account's identification scheme
Identification	Unique identification of the servicing institution
Name	Name(s) of the account holder or owner
RemittanceInformation	Description of the payment
Reference	Assigned by the creditor to refer to the payment transaction
Unstructured	Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.
ConsentId	Unique consent identification
Status	Status of the payment
CreationDateTime	Date of creation of payment
StatusUpdateDateTime	Last updated status date and time for payment
Risk	Risk description & disclaimer
Links	Redirect links
Self	Own link/url details
Meta	Meta tag
BankCode	Unique bank code for identification
scope	Scope details
state	Unique state identification
bankRedirectURL	Bank redirect url for reflecting the results
Token	Secondary identification

Initiate Payment

Endpoint details

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/pisp/paymentInitiation`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to initiate a payment

Request to initiate a payment - sample

{
    "SVPaymentInitiationRequest": {
        "DateTimeStamp": "2022-07-25T17:51:03",
        "RequestID": "{{RequestID}}",
        "userName": "{{userName}}",
        "SVPaymentInitiationInfoMessage": [
            {
                "SVPaymentInitiationInfoRequest": {
                    "BankCode": "SAMA",
                    "Data": {
                        "ConsentId": "{{ConsentId}}",
                        "Initiation": "{{Initiation}}"
                    },
                    "Risk": {}
                }
            }
        ]
    }
}

Description:

JSON Tag	Description	Data type
SVPaymentInitiationRequest Mandatory	Request to initiate payment tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVPaymentInitiationInfoMessage Mandatory	Payment initiation information message tag	Object
SVPaymentInitiationInfoRequest Mandatory	Payment initiation request information tag	Object
BankCode Mandatory	Unique bank code for identification	String
Data Mandatory	Data tag representing the data included in the request	Object
ConsentId Mandatory	Unique consent identification	String
Initiation Mandatory	Initiation payload sent by the initiating party to the ASPSP to request movement of funds	String
Risk Mandatory	Risk description & disclaimer	String

Successfully initiated payment response - sample

{
    "success": true,
    "message": "",
    "SVPaymentInitiationResponse": {
        "SVPaymentInitiationInfoMessage": [
            {
                "SVPaymentInitiationInfoResponse": {
                    "Data": {
                        "ConsentId": "pay-di-679b5a8e-7993-42d4-8c5c-c22f505555ce",
                        "Status": "PENDING",
                        "CreationDateTime": "2022-07-25T11:33:53.363Z",
                        "StatusUpdateDateTime": "2022-07-25T11:33:53.363Z",
                        "Initiation": {
                            "InstructionIdentification": "1254521522",
                            "EndToEndIdentification": "12545245515151522",
                            "InstructedAmount": {
                                "Amount": 667.61,
                                "Currency": "GBP"
                            },
                            "CreditorAccount": {
                                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                                "Identification": "12345678901234",
                                "Name": "Daniel Group"
                            },
                            "RemittanceInformation": {
                                "Reference": "test 8898",
                                "Unstructured": "9113 repellat quis rem"
                            }
                        },
                        "DomesticPaymentId": "9dfa2094-4af0-4994-a2eb-ae6b8556c827"
                    },
                    "Links": {
                        "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/pisp/domestic-payments/9dfa2094-4af0-4994-a2eb-ae6b8556c827"
                    },
                    "Meta": {},
                    "BankCode": "SAMA"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVPaymentInitiationResponse	Initiate payment response tag
SVPaymentInitiationInfoMessage	Initiate payment information message tag
SVPaymentInitiationInfoResponse	Initiate payment information response tag
Data	Data tag representing the set of data included in the request
ConsentId	Unique consent identification
Status	Status of the payment
CreationDateTime	Date of creation of payment
StatusUpdateDateTime	Last updated status date and time for payment
Initiation	Initiation payload sent by the initiating party to the ASPSP to request movement of funds
InstructionIdentification	Point-to-point reference of individual instructions
EndToEndIdentification	Unique identification used for reconciliation or to link tasks relating to the transaction
InstructedAmount	Ordered amount to be moved between the debtor and creditor
Amount	Specified amount to be processed
Currency	The currency of the amount used in transaction
CreditorAccount	Account information of the creditor tag
SchemeName	Name of the account's identification scheme
Identification	Unique identification of the servicing institution
Name	Name(s) of the account holder or owner
RemittanceInformation	Description of the payment
Reference	Assigned by the creditor to refer to the payment transaction
Unstructured	Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.
DomesticPaymentId	Unique identification for payment resource
Links	Redirect links
Self	Own link/url details
Meta	Meta tag
BankCode	Unique bank code for identification

Get Payment Details

Endpoint details

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/pisp/paymentDetails`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Fetching the details of a payment through Payment ID

Request to get payment details - sample

{
    "SVPaymentDetailsRequest": {
        "DateTimeStamp": "2022-07-25T17:51:03",
        "RequestID": "{{RequestID}}",
        "userName": "{{userName}}",
        "SVPaymentDetailsInfoMessage": [
            {
                "SVPaymentDetailsInfoRequest": {
                    "BankCode": "SAMA",
                    "PaymentId": "{{DomesticPaymentId}}"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description	Data type
SVPaymentDetailsRequest Mandatory	Get payment details request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVPaymentDetailsInfoMessage Mandatory	Get payment details information message tag	Object
SVPaymentDetailsInfoRequest Mandatory	Get payment details information request tag	Object
BankCode Mandatory	Unique bank code for identification	String
PaymentId Mandatory	Unique identification for payment resource	String

Successfully fetched payment details response - sample

{
    "success": true,
    "message": "",
    "SVPaymentDetailsResponse": {
        "SVPaymentDetailsInfoMessage": [
            {
                "SVPaymentDetailsInfoResponse": {
                    "BankCode": "SAMA",
                    "payment": {
                        "Data": {
                            "ConsentId": "pay-di-679b5a8e-7993-42d4-8c5c-c22f505555ce",
                            "CreationDateTime": "2022-07-25T11:33:53.363Z",
                            "StatusUpdateDateTime": "2022-07-25T11:34:09.094Z",
                            "Status": "Pending",
                            "Initiation": {
                                "InstructionIdentification": "1254521522",
                                "EndToEndIdentification": "12545245515151522",
                                "InstructedAmount": {
                                    "Amount": 667.61,
                                    "Currency": "GBP"
                                },
                                "CreditorAccount": {
                                    "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                                    "Identification": "12345678901234",
                                    "Name": "Daniel Group"
                                },
                                "RemittanceInformation": {
                                    "Reference": "test 8898",
                                    "Unstructured": "9113 repellat quis rem"
                                }
                            },
                            "DomesticPaymentId": "9dfa2094-4af0-4994-a2eb-ae6b8556c827",
                            "Refund": "null"
                        },
                        "Links": {
                            "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/pisp/domestic-payments/9dfa2094-4af0-4994-a2eb-ae6b8556c827"
                        },
                        "Meta": {}
                    },
                    "details": {
                        "Data": {
                            "PaymentTransactionId": "9dfa2094-4af0-4994-a2eb-ae6b8556c827",
                            "Status": "Pending",
                            "StatusUpdateDateTime": "2022-07-25T11:34:09.086Z",
                            "StatusDetails": [
                                {
                                    "LocalInstrument": "UK.OBIE.FPS",
                                    "Status": "Pending",
                                    "StatusReason": "Not Submitted",
                                    "StatusReasonDescription": "None"
                                }
                            ]
                        },
                        "Links": {
                            "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/pisp/domestic-payments/9dfa2094-4af0-4994-a2eb-ae6b8556c827/payment-details"
                        },
                        "Meta": {}
                    }
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVPaymentDetailsResponse	Get payment details response tag
SVPaymentDetailsInfoMessage	Get payment details information message tag
SVPaymentDetailsInfoResponse	Get payment details information response tag
BankCode	Unique bank code for identification
payment	Payment details tag
Data	Data tag representing the set of data included in the request
ConsentId	Unique consent identification
CreationDateTime	Date of creation of payment
StatusUpdateDateTime	Last updated status date and time for payment
Status	Status of the payment
Initiation	Initiation payload sent by the initiating party to the ASPSP to request movement of funds
InstructionIdentification	Point-to-point reference of individual instructions
EndToEndIdentification	Unique identification used for reconciliation or to link tasks relating to the transaction
InstructedAmount	Ordered amount to be moved between the debtor and creditor
Amount	Specified amount to be processed
Currency	The currency of the amount used in transaction
CreditorAccount	Account information of the creditor tag
SchemeName	Name of the account's identification scheme
Identification	Unique identification of the servicing institution
Name	Name(s) of the account holder or owner
RemittanceInformation	Description of the payment
Reference	Assigned by the creditor to refer to the payment transaction
Unstructured	Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.
DomesticPaymentId	Unique identification for domestic payment resource
Refund	Refund account details: Available only when PSU has an active consent with the TPP.
Links	Redirect links
Self	Own link/url details
Meta	Meta tag
details	Transaction details of the payment
Data	Data set of payment information
PaymentTransactionId	Unique transaction identification for payment resource
Status	Status of the payment
StatusUpdateDateTime	Last updated status date and time for payment
StatusDetails	Details of the status
LocalInstrument	Local handling payment status
Status	Status of the payment request
StatusReason	Reason of the status
StatusReasonDescription	Description of the status reason