Payment Initiation

Overview

The Payment Initiation Service (PIS) allows TPPs to initiate payments. To initiate a payment, the TPP needs authorization (consent approval) from the Payment Service User (PSU), ensuring proper authorization for initiating the payment transaction.

Request Scenario

In the following scenario, we show the process for payment initiation. Within this flow, the TPP makes payment initiation request, and receives authorization link from the ASPSP. The PSU is redirected to the interface of ASPSP for payment approval through the received authorization link. After successful payment approval, the ASPSP executes the payment and TPP can show payment status to the PSU.
Payment Initiation Service Diagram
Step 1: PSU Initiates Payment from TPP Interface
  • The process begins with the Payment Service User (PSU) initiating a payment request through the Third-Party Provider's (TPP) interface.
Step 2: TPP Makes Payment Initiation Request
  • The TPP, upon receiving the payment request, proceeds to make a payment initiation request to the PSU's ASPSP, outlining the specifics of the payment.
To initiate a payment, the TPP must make a “Payment initiation request to /payment endpoint:
POST
/xs2a/v1.3/payments/{payment-product}
Request example
curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/payments/instant-credit-transfers'\\
--header 'Obp-Sandbox-Environment: true'\\
--header 'X-Request-ID: 8073efa3-a9e0-4f57-9b5c-558f3aecb272'\\
--header 'TPP-Redirect-URI: https://tpp_success_page'\\
--header 'Content-Type: application/json'\\
--header 'Authorization: Bearer eyJhbGciOiJSUz....'\\
--header 'PSU-IP-Address: 1.1.1.1'\\
--header 'TPP-Nok-Redirect-URI: https://tpp_failure_page'\\
--data '{
  "debtorAccount": {
     "iban": "MK07300000004635084"
    },
   "creditorAccount": {
     "iban": "MK07300097116152977"
    },
   "creditorAddress":{"country":"MK"},
   "creditorName": "Milosh Zanotskin",
   "instructedAmount": {
     "currency": "MKD",
     "amount": "500.00"
    },
   "remittanceInformationUnstructured": "test payment"
}'
Note: The value of header TPP-Redirect-URI indicates the address to which the ASPSP will redirect the PSU after consent approval.
Step 3: ASPSP Responds with Error Message (If Unsuccessful)
  • In the event of an unsuccessful payment initiation request, the ASPSP responds to the TPP with an appropriate error message, indicating the reason for the failure.
Step 4: ASPSP Returns an Authorization Link
  • Upon successful payment initiation request, the ASPSP generates and returns an authorization link to the TPP.
Response example
{
"transactionStatus": "RCVD",
"paymentId": "684b3fac-b476-469d-b19c-6778bdd0cf9f",
"_links": {
   "self": {
      "href": "/sandbox/xs2a/v1.3/payments/instant-credit-transfers/684b3fac-b476-469d-b19c-6778bdd0cf9f"
    },
   "status": {
      "href": "/sandbox/xs2a/v1.3/payments/instant-credit-transfers/684b3fac-b476-469d-b19c-6778bdd0cf9f/status"
    },
   "scaRedirect": {
      "href": "https://bank_sca_page/sca-client/mock/5af7f5a5-f094-4425-98e0-4e0cf61d9eed/consent"
    }
 },
"authorisationId": "5af7f5a5-f094-4425-98e0-4e0cf61d9eed",
"tppMessages": [
   {
   "category": "MSG",
   "code": "INFO",
   "text": "Go to authorization url!"
   }
 ]
}
Step 5: TPP Redirects PSU to Authorization Link
  • The TPP redirects the PSU to the authorization link provided by the ASPSP, where PSU can proceed with giving their consent (payment approval).
Step 6: PSU Gives Consent to Payment Initiation
  • At the authorization link, the PSU provides consent for the payment initiation, confirming their approval for the transaction.
Step 7: ASPSP Initiates Payment
  • With the PSU's consent secured, the ASPSP proceeds to initiate the payment according to the provided instructions.
Step 8: PSU Returns to Failed Payment Interface
  • If the PSU did not approve the consent at the authorization link to make the payment, they are redirected back to a failed payment interface of the TPP. This redirect link is added as a value by TPP in TPP-Nok-Redirect-URI header and is used optionally.
Step 9: PSU Returns to Successful Payment Interface
  • In contrast, if the PSU approves the payment, they are directed back to a successful payment interface of the TPP, indicating a successful authorization. This redirect link is added as a value by TPP in TPP-Redirect-URI header and is mandatory.
Step 10: TPP Requests Payment Status
  • The TPP requests the payment status from the ASPSP to gain updated information about the payment status.
GET
/xs2a/v1.3/payments/{payment-product}/{payment-id}/status
Request example:
curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/payments/instant-credit-transfers/null'\\
--header 'Obp-Sandbox-Environment: true'\\
--header 'X-Request-ID: 87566ad8-41c5-4515-a8a4-afd1a8811d21'\\
--header 'Content-Type: application/json'\\
--header 'Authorization: Bearer eyJhbGciOiJS......'\\
--header 'PSU-IP-Address: 1.1.1.1'
Step 11: ASPSP Returns Payment Status
  • In response to the TPP's request, the ASPSP returns the current payment status.
Step 12: TPP Displays Payment Status to PSU
  • Lastly, the TPP displays the payment status to the PSU, offering an overview of the payment transaction's outcome.