Payly

Instant & Secure Payments

📘

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

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 URLMethod
https://obsandboxservices.onesingleview.com/v1/api/observice/payment/single/sip/consentPOST

Sample request

{
  "banks": [
    {
      "code": "Enter_Bank_Code",
      "isSettlement": false,
      "amount": 00000.00,
      "currency": "Enter_Currency_Code",
      "description": "Enter_Description"
    }
  ],
  "dateTimeStamp": "YYYY-MM-DDTHH:MM:SS.SSSZ",
  "merchantId": "Enter_Merchant_Id",
  "requestID": 0000000000000
}

Request description

JSON TagDescriptionData type
banks
Mandatory
Tag carrying information on bank and paymentObject
code
Mandatory
Unique bank identification codeString
isSettlement
Mandatory
Status of settlement to be mentioned as falseBoolean
amount
Mandatory
Payment amountNumerical
currency
Mandatory
Currency of the payment String
description
Mandatory
Details on paymentString
dateTimeStamp
Mandatory
Stamp denoting the date and time of the requestString
merchantId
Mandatory
Unique merchant identificationString
requestID
Mandatory
Unique request identificationString

Sample 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 description

JSON TagDescription
successProcess success status represented as true or false
payloadTag carrying response information
codeUnique bank identification code
dataTag carrying the response data of the accounts
controlParametersTag carrying information on content control
consentPeriodValidity period of the consent
validFromDateTimeStarting date and time of the consent validity
validToDateTimeEnding date and time of the consent expiry
currencyCurrency code of the payment
acceptedAuthorizationTypeAuthorization details to be mentioned as KSAOB.Single
authorizationExpirationTimeWindowTime allotted for authorization of the payment
consentScheduleTag carrying information on the scheduled consent
singlePaymentTag carrying the single payment information
typeType of payment to be mentioned as KSAOB.SingleInstantPayment
amountAmount of the payment
initiationTag carrying information on the initiation of the payment
creditorAccountTag carrying information on the creditor account
identificationTypeType of identification used for creditor account to be denoted as KSAOB.IBAN
identificationUnique IBAN or creditor account identification details
accountHolderNameTag carrying information on the name of the account holder
enName of the account holder in English
arName of the account holder in Arabic
beneficiaryInformationTag carrying beneficiary information
agentInformationTag carrying the agent's information
nameName of the agent
identificationUnique identification details of the agent
isEcommercePayment status for eCommerce to be mentioned as false
consentIdUnique consent identification details
flagFlag information of the consent & payment
statusStatus of the consent authorization
creationDateTimeDate and time of the consent creation
statusUpdateDateTimeDate and time of the last updated consent status
linksTag carrying information on links
metaMeta information
scopeScope of the consent
bankRedirectUrlURL 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.

{
  "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 TagDescription
successProcess success status represented as true or false
scopeDetails on scope of the payment
consentIdUnique consent identification details
userIdUnique user identification details
sdkInformation on status of sdk status to be mentioned as false
bankCodeUnique bank identification code
paymentInitiationResTag carrying the information on the payment initiation response
paymentIdUnique payment identification details
paymentTransactionIdUnique payment transaction identification details
statusStatus of the payment initiation
statusUpdateDateTimeDate and time representing the last updated status
requestedExecutionDateTimeDate and time of the request exection
creationDateTimeDate and time of the creation of the payment request
expectedSettlementDateTimeDate and time representing the expected settlement time
chargesTag carrying information on the payment charges
typeType of the charges included for the payment
amountAmount representing the charges
amountAmount of the payment
currencyUnique currency code representing the payment currency
paymentDetailsTag carrying information on the payment details
controlParametersTag carrying information on content control
consentPeriodValidity period of the consent
validFromDateTimeStarting date and time of the consent validity
validToDateTimeEnding date and time of the consent expiry
currencyCurrency code of the payment
acceptedAuthorizationTypeAuthorization details to be mentioned as KSAOB.Single
authorizationExpirationTimeWindowTime allotted for authorization of the payment
consentScheduleTag carrying information on the scheduled consent
singlePaymentTag carrying the single payment information
typeType of payment to be mentioned as KSAOB.SingleInstantPayment
amountAmount of the payment
initiationTag carrying information on the initiation of the payment
debtorAccountTag carrying information on the debtor account
identificationTypeType of identification used for debtor account to be denoted as KSAOB.IBAN
identificationUnique IBAN or debtor account identification details
accountHolderNameTag carrying information on the name of the account holder
enName of the account holder in English
arName of the account holder in Arabic
debtorAgentInformation on the debtor agent bank
creditorAccountTag carrying beneficiary information
identificationTypeType of identification used for creditor account to be denoted as KSAOB.IBAN
identificationUnique IBAN or creditor account identification details
accountHolderNameTag carrying information on the name of the account holder
enName of the account holder in English
arName of the account holder in Arabic
purposePurpose of the payment