logo

Openbanking

MyBank

Get Started

Payment Initiation Service (PIS) Request To Pay flow

When the Developer wants to test the PIS APIs, they would need to create an app in their Dashboard of API product type KSA PIS.

Below steps are required to complete a single request to pay ( RTP).

  1. The customer consents the PISP that he/she would like to use the bank account.
  2. Developer (PISP) contacts the bank & sends RTP Initiation Request.
    • Bank checks if Developer App Id (client_id) has necessary authorizations
    • The bank uses the information & creates RTP Consent Response & creates one or more authorization sub-resources which is directly mapped to authorise the payment
  3. The bank responds to the Developer with Consent Response which also instructs the Developer on how to proceed with the Authentication & Authorization.
  4. The Developer redirects the customer to the bank website for authentication & consent confirmation.
  5. After the necessary checks, the bank sends the Access Token to the Developer, Developer can submit and initiate a RTP payment.

Illustrative Flow for Request to Pay

  • Step 1: Third party onboarding
  • Step 2: Third party App Creation
  • Step 3: Third Party token generation
  • Step 4: Initiate a request-to-pay-consent
  • Step 5: ConsentID generated with "AwaitingAuthorization" status
  • Step 6: Customer authentication
  • Step 7: Customer authorization
  • Step 8: Consent updated to "Authorized" status
  • Step 9: Customer token granted
  • Step 10: Request To Pay Instruction API with customer token
  • Step 11: Request to Pay details response

PISP Dev Portal Testing

Following steps are needed to complete PISP flow:

1. Select App

On clicking the

Test
button against the App as shown below, the Developer is redirected to the Swagger UI.

2. Developer Token Generation

The first step is to configure the Private Key using the

Click Here
Button. This can be also be reconfigured, if required.

Please chose the respective private key to sign the request ( which matches Certificate or JWKS url provided during the [App creation]) & paste it in the application signing private key field above the Authorize button.
Private-Key for Client Certificate
-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDaGj3mL+E3Mflz
oQ8iXkPFoW76OMA81+E6JxYr+wfWuHFTG5HeAH/6fujz3LNRz4t6ib8I3p11aDhC
ABfKPgoGspG+uoQQfbUTseYcSg9XcgQ4asNTYvSlribDTLH2bi7LZLfTIpIsOA7o
JMIXwQu+zSs/dOWAtr8abiV+aweEFCzoR53lz/Hkz4gukv7/JbyuRiN1tbsRwnTz
sDdpN47G61j6eYHiAAtirGSuA0MXbHolztOPyB6hJFelbg52TY5z1zYWQL1KCoXU
ubq5LpZwXhngmzT+LN+giYTHEDB3AIMibwjcIt8M6BIHtH37inyXZYHhTnXwH4YG
UtnDLtOPAgMBAAECggEAdHKUYAVqWtzs0gbJHNF1n9w8c46/XPzqPPFHjj3eho89
umC69ewQaH9AA4vvlhuY3dkTzTmGmnwFpX+FNC8BjWfkFxBgmKl1d8mBEdOc81Rl
2nVuSmRIOPmNqrKVRfy4MVJaL3mCz+cyVlHh62rfyYSjtaLFMn7f882haSjd/28F
HpfwJvrVcb2zEtbWdOBMH09fBSLqF7SuIGrawldyfdqbwZeqGuFxgDR8+675V65/
cEgIj8m5YcwnfFPptLNB8bcOcAFdQh1IQcJRnHw0DOrD8DvKs22VjnFpC+i7VoWS
GORahAUI7oZRayJhswq+DKHDXAr/bYMxU7oT0brFwQKBgQD/hdmgOyS7pFZPUcTy
GCl/zGYFLyFYHGLqCcHcvIIZBRqTuO6k6uD2f+zpQlcYeGYToBvgLJF66ja3ipee
XO0eTipwRcZuKh2SX6hYmj8f1HGNMi/WeHkfJoQhNVMw0hudxhh8gWwmsRr+LPyj
iXSoufzt3vVN52yFnMbhJ/0V4QKBgQDagoDYtLxm3RM086WIA3YtJ8repK4/XjzM
pDrm5vVpbVmBVqz+ypG6/punSX3gfS58IOaW4hw6FlWdhqkQEeg8bewKs/QXkc4a
c8EMj0ioeaYtJ3XF9sV8gl55bXshHR0yVoh2puDatDNUJyEzM8jtPA8jWVPbJQe7
N3FUNp83bwKBgErv4kcPkVJGe9l/TZcCZwlH1JOoosrIaGniuqwVzMGxsX2pOrO6
/obMNZqjDg/rH2SaDBLOf0vg7HMffh+/ePruSZvrmqosR8fpreFuOx0GnNaf5U+s
vTjZft6OWPt0Ywz+T6gT/LfMMPJiFyWO5lulT/wi6yYRvM3ikKDvrVWBAoGAROxl
N/XKd6fEJy+zRvPQku26UAAh9lsDUol7CtpPDrIvSVzNtJCw5wrojhvgWK8juoOm
OHGZ9biVyNpw+WCsoGML0VRx6f1TxYQ9oHiRspKsmBGaVJdCM8PriOG/tPI6A2bI
JKT+x/2PMzwkfMIY3rvTCpNin/1OMv+J/8Y68oECgYAS8AHgjWdTK321VUuxcJqT
NtPED5+5xwy2ZGSmbNVPfCGSsOceVGY4KdwO+qk6eXfcR/AS+tYnBJ0Cv5+JMGFa
cvZUH5a4ww4VocInEt01QzGdJd2JsqXn+mBsMepsajTvibCFKAapYTsw0QWaS6E6
eXYx8a1jK15SFaJ33Y4tZg==
-----END PRIVATE KEY-----
Private-Key for JWKS url
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA0J5vAPXfZS755gaBYn2PEakdHLtAmZc0cKA5wTL89V4uz9sd
kiub+S91cJUTqfxqFFwFe+acTKW7+HKOusJREq3oWNyv394+2OXSDz15Lso6GEAT
orSRTWzfqUjogjOOBxrvxrcMyxS2RM/NjaNPw2PDWO6u0/BHPWbzyKdKbzzGsuqp
d4bZ85+xzDXhXRe0n23GCnGxpPM0SvsW9CAme23+ET/F6VdfPKkX0GSU/vxdwEwG
Urk5sbBmtoLcj+pfpJKaA7ZbtLsngrIVIPRNUdcP3eCPiYHrDltsi1wnWlnRj2OB
cqfM6bVOQfIiVLv+UC2PgY9gmzzw+Q86GPBQOwIDAQABAoIBAQCsJhDzefEeTeVp
K3UZEQM+T472Zo6oL13WkmEWTDzxPQbj/qwoMlRDDCadAGd5nhDrPARKecIAfcLf
AalF85NzFo7kxTdcRMkXso3khZW6RqYp3LZXTSmZ+n2V89PpnSFWO6QhFmw4KJ8/
qTq15k2rrmdEu7EIsv4WbR4+Nc32e3L9PRcHM14ez3rXPEt9z9BAUwnjqmm4uXmc
GmYwSs2EHC1jfTLWzpxdYCEQNG959jKE4/JIKNuZRZJ6XuzC4bFkpAhiQlLVAn6D
97gPJWDJuxjSZtovbA2dlhb+uRUS2Ygj0vi0Z/NxgFh3vTzg5e9OWHxhW4l+DGoK
shiU5BABAoGBAOw3B2wahVxulE8V+p3yOCiEsoSoQIXuOx90IwUWTdNxBUdPi6ce
p3GOZIjDMf/Hjz85Tv1PCJxuj84QIGRXbaiWLdpXFC+dB53z1r9SqBhXvGwjae4m
Epik/9EoxU8wWZ5qAKBXGxAM1x4IFjJ2zK6UiwRB+uHRdhqoF11VxhHbAoGBAOIX
rwjuYHFQuEDmcaGqXYLwdAMEohxmRLgIIa2JXf+oDZeNsjJjrKgYUeV4Ckp4FL9r
6zPTZBl3FEVWK3LpCyk920uchqeW18zIxKHQ4ozqN9zsc/7lrXFEh+SaQewaVEtl
LqKpySQNGJy4/71u4x3M3d9//zyfQkEmuUkwPvkhAoGBAJRLl+VOYRs+cO2Vptky
D/+gD1MpLhjnD0cX6kRvVDzCX8X9Mnegzw6DjqotoV4rMstGd0igLY/H+ZAsn6lf
GgEVB4Rj1tBtjTKkutUyV0WxDyH0ubRBQruCGvh82CJ3AExr0CjZhqv047h+6zCT
VLzllMD/iznp/nONw91c1BSxAoGAXSY21i4oC+ee0hZfcKTZPA5HLcsl4x97Znrr
LS0wThl16B/X8AzC4MqMS0dmrgHFQox67fJFBnzaHCsBYamEEKzMgd1uWPO720JI
SQbfoAELnPjKXZVRHR6IAnZPfK/oVNvOF/Rty22d20wZCXn7FpcGPoPkq5xN1rvW
kMHQ4CECgYEA5d84bsBKb6u0YspU9hpc9o8F5PcJxqlwsfyOof80tUwA3NTk985c
vaiXM5kQwM21q7bCyMoNfTi681MzlK1gt9GYRAHV4NJhw410mGDdnmGYFtsJwJIZ
bnwttYJsI0RIrk7Irom8HD2AnTvV5aI05Dxhv/+nCfn+bhy1Qqwce98=
-----END RSA PRIVATE KEY---

The next step is AISP's App-Id to get authenticated by clicking the

ThirdParty Authorise
button & fill in the App secret to get access token specific to the Developer.

3. Request To Pay Initiation Request Call

The bearer token from above step should be populated in the PISP Request To Pay Initiation Request Endpoint -

POST /requests-to-pay/consents

Use the below payload to send the request to pay initiation requests. Make sure the IBAN of Creditor Account matches the PSU who is going to authorise.

Note:
  1. The Base Consent Id should be unique
  2. Check the expiration date
{
    "iss": "KSAOBKSA-ETC-QLNU",
    "exp": 1700801103.733,
    "iat": 1700800503.733,
    "nbf": 1700800503.733,
    "aud": "18fd6b2d-b4c2-497a-a6ce-478e5195f2a7",
  "message": {
    "Data": {
      "BaseConsentId": "4fghutr-hnjik-2678-4758-12345678-123 ----UNIQUE BASE CONSENTID GIVEN IN REQUEST-----",
      "ControlParameters": {
        "ConsentPeriod": {
          "ValidFromDateTime": "2024-07-01T04:25:29.035Z",
          "ValidToDateTime": "2024-12-01T04:25:29.035Z"
        },
        "ConsentSchedule": {
          "Type": "KSAOB.SingleRequestToPay",
          "Purpose": "Investments",
          "ExpiryDate": "2023-12-07",
          "Remarks": "2023-12-07",
          "Instruction": [
            {
              "Amount": {
                "Amount": "100.00",
                "Currency": "SAR"
              },
              "DebtorAccount": {
                "SchemeName": "KSAOB.IBAN",
                "Identification": "SA0000000012345678178909",
                "Name": {
                  "en": "Ibrahim Sheik",
                  "ar": "ابراهيم الشيخ"
                },
                "DebtorAgent": "SASAMA"
              }
            }
          ]
        },
        "AcceptedAuthorizationType": "KSAOB.Single",
        "AuthorizationExpirationTimeWindow": "001:00:00"
      },
      "Initiation": {
        "CreditorAccount": {
          "SchemeName": "KSAOB.IBAN",
          "Identification": "SA0000000012345678167519",
          "Name": {
            "en": "Nazeem Fatima",
            "ar": "ناظم فاطمة"
          },
          "TradingName": {
            "en": "Banfico",
            "ar": "بانفيكو"
          },
          "CreditorAgent": "SASAMA"
        }
      },
      "RemittanceInformation": {
        "Reference": "Investments"
      },
      "Purpose": "Investments",
      "ExpiryDate": "2023-12-07",
      "Remarks": "2023-12-07"
    },
    "Subscription": {
      "Webhook": {
        "Url": "https://api.pisp.com/webhook/callbackUrl",
        "IsActive": false
      }
    }
  }
}
  • On a successful request the Developer will receive the below response.
  • Please verify that an unique 'ConsentID' will be generated and the status of the 'ConsentID' will be set as
    AwaitingAuthorization
    .
{
  "aud": "KSAOBKSA-EBV-SOLJ",
  "nbf": 1710846880,
  "iss": "https://auth1.lab.openbanking.sa",
  "exp": 1710847780,
  "message": {
    "Data": {
      "ConsentId": "rtp-44cb796e-81cb-4bdd-85c7-ab6eac5eea4e",
      "BaseConsentId": "4fghutr-hnjik-5678-47584861465",
      "Status": "AwaitingAuthorization",
      "StatusUpdateDateTime": "2024-03-19T11:14:40.784121Z",
      "CreationDateTime": "2024-03-19T11:14:40.784145Z",
      "ControlParameters": {
        "ConsentPeriod": {
          "ValidFromDateTime": "2024-04-07T12:32:51.298Z",
          "ValidToDateTime": "2024-05-07T12:32:51.298Z"
        },
        "ConsentSchedule": {
          "Type": "KSAOB.SingleRequestToPay",
          "Purpose": "Investments",
          "ExpiryDate": "2023-12-07",
          "Remarks": "2023-12-07",
          "Instruction": [
            {
              "Amount": {
                "Amount": "100.00",
                "Currency": "SAR"
              },
              "DebtorAccount": {
                "SchemeName": "KSAOB.IBAN",
                "Identification": "SA0000000018345679178909",
                "Name": {
                  "en": "Ibrahim Sheik",
                  "ar": "ابراهيم الشيخ"
                },
                "DebtorAgent": "SASAMA"
              }
            }
          ]
        },
        "AcceptedAuthorizationType": "KSAOB.Single",
        "AuthorizationExpirationTimeWindow": "001:00:00"
      },
      "Initiation": {
        "CreditorAccount": {
          "SchemeName": "KSAOB.IBAN",
          "Identification": "SA0000000012345678178909",
          "Name": {
            "en": "Nazeem Fatima",
            "ar": "ناظم فاطمة"
          },
          "TradingName": {
            "en": "Banfico",
            "ar": "بانفيكو"
          },
          "CreditorAgent": "SASAMA"
        }
      },
      "Purpose": "Investments",
      "ExpiryDate": "2023-12-07",
      "Remarks": "2023-12-07"
    },
    "Links": {
      "Self": "/open-banking/payment/2023.08-draft2/payments/request-to-pay-consents/rtp-44cb796e-81cb-4bdd-85c7-ab6eac5eea4e",
      "Related": [
        "/open-banking/payment/2023.08-draft2/payments/request-to-pay-consents/rtp-44cb796e-81cb-4bdd-85c7-ab6eac5eea4e"
      ]
    },
    "Meta": {}
  },
  "iat": 1710846880
}

The response provides the paymentId, transaction-status, scaOAuth & scaStatus endpoints. The Developer uses the OAuth well-known endpoint of the bank to redirect the customer for authentication.

4. PSU Authentication

Select the

Customer Authorise
to authenticate the PSU.

Two types of PSU Authentication flows are supported:

  1. Redirect Authorize
  2. Decoupled Authorize

To navigate through PSU authentication flow and generate PSU Token please refer PSU Authentication flow

The Developer can use the TPP access_token to get details of the consent status.

  1. Verify that the consent status is
    Finished
    and Flag is set as
    Consumed
  2. Copy the
    RequestToPayID
    from Data.Links.Related[] to fetch the status of RequestToPayID in the future
{
  "aud": "aud",
  "nbf": 1710847244,
  "iss": "iss",
  "exp": 1710848144,
  "message": {
    "Data": {
      "ConsentId": "rtp-3847bccd-54e3-4c96-b5b5-68a8c4d691eb",
      "BaseConsentId": "4fghutr-hnjik-5678-47583445890",
      "Status": "Finished",
      "Flags": [
        {
          "Flag": "Consumed",
          "FlagSetDateTime": "2024-03-19T11:20:21.823566Z"
        }
      ],
      "StatusUpdateDateTime": "2024-03-19T11:20:21.823558Z",
      "CreationDateTime": "2024-03-19T11:19:54.994731Z",
      "ControlParameters": {
        "ConsentPeriod": {
          "ValidFromDateTime": "2024-04-07T12:32:51.298Z",
          "ValidToDateTime": "2024-05-07T12:32:51.298Z"
        },
        "ConsentSchedule": {
          "Type": "KSAOB.SingleRequestToPay",
          "Purpose": "Investments",
          "ExpiryDate": "2023-12-07",
          "Remarks": "2023-12-07",
          "Instruction": [
            {
              "Amount": {
                "Amount": "100.00",
                "Currency": "SAR"
              },
              "DebtorAccount": {
                "SchemeName": "KSAOB.IBAN",
                "Identification": "SA0000000018345679178909",
                "Name": {
                  "en": "Ibrahim Sheik",
                  "ar": "ابراهيم الشيخ"
                },
                "DebtorAgent": "SASAMA"
              }
            }
          ]
        },
        "AcceptedAuthorizationType": "KSAOB.Single",
        "AuthorizationExpirationTimeWindow": "001:00:00"
      },
      "Initiation": {
        "CreditorAccount": {
          "SchemeName": "KSAOB.IBAN",
          "Identification": "SA0000000018345679178909",
          "Name": {
            "en": "Nazeem Fatima",
            "ar": "ناظم فاطمة"
          },
          "TradingName": {
            "en": "Banfico",
            "ar": "بانفيكو"
          },
          "CreditorAgent": "SASAMA"
        }
      },
      "Purpose": "Investments",
      "ExpiryDate": "2023-12-07",
      "Remarks": "2023-12-07"
    },
    "Links": {
      "Self": "/open-banking/payment/2023.08-draft2/payments/request-to-pay-consents/rtp-3847bccd-54e3-4c96-b5b5-68a8c4d691eb",
      "Related": [
        "/open-banking/payment/2023.08-draft2/payments/requests-to-pay/6ce48bff-0f3d-4f01-ba68-2b178ca8da19"
      ]
    },
    "Meta": {}
  },
  "iat": 1710847244
}

6. RequestToPayID status API call

The Developer can use the TPP access_token along with the obtained RequestToPayID from above to get current status of the RequestToPayID.

  1. Verify that the status of Refund is
    KSAOB.Pending
  2. Please take the note of the RequestToPayID for future reference
{
  "aud": "aud",
  "nbf": 1710847367,
  "iss": "iss",
  "exp": 1710848267,
  "message": {
    "Data": {
      "RequestsToPayId": "6ce48bff-0f3d-4f01-ba68-2b178ca8da19",
      "ConsentId": "rtp-3847bccd-54e3-4c96-b5b5-68a8c4d691eb",
      "Purpose": "Investments",
      "Instruction": [
        {
          "Type": "KSAOB.SingleRequestToPay",
          "Amount": {
            "Amount": "100.00",
            "Currency": "SAR"
          },
          "Status": "KSAOB.Pending",
          "StatusUpdateDateTime": "2024-03-19T11:20:21.817706Z",
          "CreationDateTime": "2024-03-19T11:20:21.817695Z"
        }
      ]
    },
    "Links": {
      "Self": "/open-banking/payment/2023.08-draft2/requests-to-pay/6ce48bff-0f3d-4f01-ba68-2b178ca8da19"
    },
    "Meta": {
      "TotalPages": 1
    }
  },
  "iat": 1710847367
}

7.Approving the Request to Pay in Core Bank

  1. Login to Core Bank with PSU credentials for the PSU which was used to authenticate.
  2. The request to pay which was initiated will be reflected in the Statement Section with the Status of
    Pending
  3. Select the transaction and Click on
    Pay

4. The Request to pay status will be Booked

5. Validate the balance debited from the account
Note: If the Creditor account belongs to the CoreBank, validate that the transaction is reflected there and balance is credited to the account.

8. Request To Pay status API call

After approving the payments, the Developer can use the TPP access_token along with the obtained RequestToPayID from above to get current status of the RequestToPayID.

  1. Verify that the status of Request to Pay is
    KSAOB.Paid
{
  "aud": "aud",
  "nbf": 1710847434,
  "iss": "iss",
  "exp": 1710848334,
  "message": {
    "Data": {
      "RequestsToPayId": "6ce48bff-0f3d-4f01-ba68-2b178ca8da19",
      "ConsentId": "rtp-3847bccd-54e3-4c96-b5b5-68a8c4d691eb",
      "Purpose": "Investments",
      "Instruction": [
        {
          "Type": "KSAOB.SingleRequestToPay",
          "Amount": {
            "Amount": "100.00",
            "Currency": "SAR"
          },
          "Status": "KSAOB.Paid",
          "StatusUpdateDateTime": "2024-03-19T11:20:21.817706Z",
          "CreationDateTime": "2024-03-19T11:20:21.817695Z"
        }
      ]
    },
    "Links": {
      "Self": "/open-banking/payment/2023.08-draft2/requests-to-pay/6ce48bff-0f3d-4f01-ba68-2b178ca8da19"
    },
    "Meta": {
      "TotalPages": 1
    }
  },
  "iat": 1710847434
}
logo

Openbanking

MyBank

Navigation
Developers
Legals