Payly

Important information

Payly options can be accessed only after a merchant is created
The Callback URL has to be provided to access details on the payment status and charges

Process a payment

The following endpoint facilitates the processing of payment transactions through Payly. This endpoint allows secure transmission of payment details and receive confirmation or error responses from the system. A payment request in the mentioned sample format is sent to the endpoint. A successfully processed payment will provided the mentioned sample response.

Endpoint details

Endpoint URL	Method
`https://obsandboxservices.onesingleview.com/v1/api/observice/payment/single/sip/consent`	POST

Sample request

Process payment

{
  "banks": [
    {
      "code": "SAMA",
      "isSettlement": false,
      "amount": 3000.00,
      "currency": "SAR",
      "description": "Payment Towards Consultant Services"
    }
  ],
  "dateTimeStamp": "2024-12-31T10:40:00+02:00",
  "requestID": "df797efb-b588-4234-8ae1-5cb748559830",
  "merchantId": "APIS-300505",
}

Request parameters

JSON Tag	Requirement	Description	Data type
banks	Mandatory	Tag carrying information on bank and payment	Object
code	Mandatory	Unique bank identification code	String
isSettlement	Mandatory	Status of settlement to be mentioned as `false`	Boolean
amount	Mandatory	Payment amount	Numerical
currency	Mandatory	Currency of the payment	String
description	Mandatory	Details on payment	String
dateTimeStamp	Mandatory	Stamp denoting the date and time of the request	String
merchantId	Mandatory	Unique merchant identification	String
requestID	Mandatory	Unique request identification	String

Sample response

Process payment response

{
  "success": true,
  "payload": [
    {
      "code": "Bank_Code",
      "data": {
        "controlParameters": {
          "consentPeriod": {
            "validFromDateTime": "YYYY-MM-DDTHH:MM:SS",
            "validToDateTime": "YYYY-MM-DDTHH:MM:SS"
          },
          "currency": "Currency_Code",
          "acceptedAuthorizationType": "KSAOB.Single",
          "authorizationExpirationTimeWindow": 0000000,
          "consentSchedule": {
            "singlePayment": {
              "type": "KSAOB.SingleInstantPayment",
              "amount": 00000.00
            }
          }
        },
        "initiation": {
          "creditorAccount": {
            "identificationType": "KSAOB.IBAN",
            "identification": "IBAN",
            "accountHolderName": {
              "en": "Name_In_English",
              "ar": "Name_In_Arabic"
            }
          }
        },
        "beneficiaryInformation": {},
        "agentInformation": {
          "name": "",
          "identification": ""
        },
        "isEcommerce": false,
        "consentId": "Consent_Id",
        "flag": "Flag_Details",
        "status": "Payment_Status",
        "creationDateTime": "YYYY-MM-DDTHH:MM:SS.SSS+HH:MM",
        "statusUpdateDateTime": "YYYY-MM-DDTHH:MM:SS.SSS+HH:MM"
      },
      "links": {},
      "meta": {},
      "scope": "Scope_Details",
      "bankRedirectUrl": "Redirect_URL"
    }
  ]
}

Response paramaters

JSON Tag	Description
success	Process success status represented as `true` or `false`
payload	Tag carrying response information
code	Unique bank identification code
data	Tag carrying the response data of the accounts
controlParameters	Tag carrying information on content control
consentPeriod	Validity period of the consent
validFromDateTime	Starting date and time of the consent validity
validToDateTime	Ending date and time of the consent expiry
currency	Currency code of the payment
acceptedAuthorizationType	Authorization details to be mentioned as `KSAOB.Single`
authorizationExpirationTimeWindow	Time allotted for authorization of the payment
consentSchedule	Tag carrying information on the scheduled consent
singlePayment	Tag carrying the single payment information
type	Type of payment to be mentioned as `KSAOB.SingleInstantPayment`
amount	Amount of the payment
initiation	Tag carrying information on the initiation of the payment
creditorAccount	Tag carrying information on the creditor account
identificationType	Type of identification used for creditor account to be denoted as `KSAOB.IBAN`
identification	Unique IBAN or creditor account identification details
accountHolderName	Tag carrying information on the name of the account holder
en	Name of the account holder in English
ar	Name of the account holder in Arabic
beneficiaryInformation	Tag carrying beneficiary information
agentInformation	Tag carrying the agent's information
name	Name of the agent
identification	Unique identification details of the agent
isEcommerce	Payment status for eCommerce to be mentioned as `false`
consentId	Unique consent identification details
flag	Flag information of the consent & payment
status	Status of the consent authorization
creationDateTime	Date and time of the consent creation
statusUpdateDateTime	Date and time of the last updated consent status
links	Tag carrying information on links
meta	Meta information
scope	Scope of the consent
bankRedirectUrl	URL redirecting to bank platform for authorization

Authorization

The bankRedirectUrl will redirect you to the bank's login platform that needs to be provided with your login credentials to authorize the payment
The user (approver) has to select the debit account and confirm the consent after login
After this step you'll be redirected to the SingleView platform which is configured with the bank to fetch information through Webhook regarding the initiation and status of the payment

For model bank, the authorization response is provided by the API itself without any involvement of actual bank

Payment Status & Charges (Webhook)

Updates on payment information and status are provided through webhooks to the assigned callback URLs. Below is the sample response of the webhook.

Payment Status & Charges Webhook

{
  "success":true,
  "scope":"Scope_of_Payments",
  "consentId":"Consent_Id",
  "userId":"null",
  "sdk":false,
  "bankCode":"Bank_Code",
  "paymentInitiationRes":{
    "paymentId":"Payment_Id",
    "paymentTransactionId":"Transaction_Id",
    "status":"Status_of_the_Payment",
    "statusUpdateDateTime":"YYYY-MM-DDTHH:MM:SS.SSS+HH:MM",
    "requestedExecutionDateTime":"YYYY-MM-DDTHH:MM:SS.SSS+HH:MM",
    "creationDateTime":"YYYY-MM-DDTHH:MM:SS.SSS+HH:MM",
    "expectedSettlementDateTime":"YYYY-MM-DDTHH:MM:SS.SSS+HH:MM",
    "charges":[
      {
        "type":"VAT",
        "amount":"000.00"
      }
    ],
    "amount":00,
    "currency":"Currency_Code",
    "paymentDetails":{
      "controlParameters":{
        "consentPeriod":{
          "validFromDateTime":"YYYY-MM-DDTHH:MM:SS",
          "validToDateTime":"YYYY-MM-DDTHH:MM:SS"},
        "currency":"Currency_Code",
        "acceptedAuthorizationType":"KSAOB.Single",
        "authorizationExpirationTimeWindow":0000000,
        "consentSchedule":{
          "singlePayment":{
            "type":"KSAOB.SingleInstantPayment",
            "amount":00
          }
        }
      },
      "initiation":{
        "debtorAccount":{
          "identificationType":"KSAOB.IBAN",
          "identification":"0000000000000",
          "accountHolderName":{
            "en":"Name_In_English",
            "ar":"Name_In_Arabic"
          },
          "debtorAgent":"Debitor_Agent"
        },
        "creditorAccount":{
          "identificationType":"KSAOB.IBAN",
          "identification":"0000000000000",
          "accountHolderName":{
            "en":"Name_In_English",
            "ar":"Name_In_Arabic"
          }
        }
      },
      "purpose":"Purpose_of_the_Payment"
    }
  }
}

Response details

JSON Tag	Description
success	Process success status represented as `true` or `false`
scope	Details on scope of the payment
consentId	Unique consent identification details
userId	Unique user identification details
sdk	Information on status of sdk status to be mentioned as `false`
bankCode	Unique bank identification code
paymentInitiationRes	Tag carrying the information on the payment initiation response
paymentId	Unique payment identification details
paymentTransactionId	Unique payment transaction identification details
status	Status of the payment initiation
statusUpdateDateTime	Date and time representing the last updated status
requestedExecutionDateTime	Date and time of the request exection
creationDateTime	Date and time of the creation of the payment request
expectedSettlementDateTime	Date and time representing the expected settlement time
charges	Tag carrying information on the payment charges
type	Type of the charges included for the payment
amount	Amount representing the charges
amount	Amount of the payment
currency	Unique currency code representing the payment currency
paymentDetails	Tag carrying information on the payment details
controlParameters	Tag carrying information on content control
consentPeriod	Validity period of the consent
validFromDateTime	Starting date and time of the consent validity
validToDateTime	Ending date and time of the consent expiry
currency	Currency code of the payment
acceptedAuthorizationType	Authorization details to be mentioned as `KSAOB.Single`
authorizationExpirationTimeWindow	Time allotted for authorization of the payment
consentSchedule	Tag carrying information on the scheduled consent
singlePayment	Tag carrying the single payment information
type	Type of payment to be mentioned as `KSAOB.SingleInstantPayment`
amount	Amount of the payment
initiation	Tag carrying information on the initiation of the payment
debtorAccount	Tag carrying information on the debtor account
identificationType	Type of identification used for debtor account to be denoted as `KSAOB.IBAN`
identification	Unique IBAN or debtor account identification details
accountHolderName	Tag carrying information on the name of the account holder
en	Name of the account holder in English
ar	Name of the account holder in Arabic
debtorAgent	Information on the debtor agent bank
creditorAccount	Tag carrying beneficiary information
identificationType	Type of identification used for creditor account to be denoted as `KSAOB.IBAN`
identification	Unique IBAN or creditor account identification details
accountHolderName	Tag carrying information on the name of the account holder
en	Name of the account holder in English
ar	Name of the account holder in Arabic
purpose	Purpose of the payment

Categories

GENERAL INFORMATION

GETTING STARTED

CONSENT MANAGEMENT

Raw Data APIs

DATA USE CASE APIS

Plug-and-Play Integrations