5. Usage Examples (Draft Version 1.0)

The usage examples for the individual APIs are documented in their respective pages.

This section provides usage examples for some repeating patterns that are used by multiple resources

5.1 Pagination Flows

The example below illustrates how an ASPSP may return a paginated response.

5.2 Request

GET /accounts/7859342/transactions?pg=2 HTTP/1.1
Authorization: Bearer 4AopnAZFKjr5zBsicSQpLL
x-fapi-auth-date:  Tue, 13 Jun 2023 19:43:31 GMT+03:00
x-fapi-customer-ip-address: 204.35.213.15
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Accept: application/json

5.3 Paginated Resource Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Content-Type: application/json

Example:

{
  "Data": {
    …
  },
"Links": {
 "Self": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions/",
 "Last": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=12",    
 "First": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions/",    
 "Next": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=4"
  },  
"Meta": {
              "TotalPages": 12,
	"FirstAvailableDateTime": "2023-06-13T00:00:00+03:00",
	"LastAvailableDateTime": "2023-06-13T00:00:00+03:00"
  }
}

5.4 Request Next Page of Results

GET /accounts/7859342/transactions?pg=2 HTTP/1.1
Authorization: Bearer 4AopnAZFKjr5zBsicSQpLL
x-fapi-auth-date:  Tue, 13 Jun 2023 19:43:31 GMT+03:00
x-fapi-customer-ip-address: 204.35.213.15
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Accept: application/json

5.5 Paginated Resource Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Content-Type: application/json

Example:

{
  "Data": {
    ...
  },
  "Links": {
    "Self": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=2",
    "Last": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=12",    
    "First": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions/",    
    "Next": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=3",
    "Prev": "https://api.abcbank.com/open-banking/v3.1/aisp/accounts/7859342/transactions?pg=1"
  },
  "Meta": {
    "TotalPages": 12,
	"FirstAvailableDateTime": "2023-05-13T00:00:00+03:00",
	"LastAvailableDateTime": "2023-06-13T00:00:00+03:00"
  }
}

5.6 Error Flows

JSON Error Response

5.7 Request

POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 4AopnAZFKjr5zBsicSQpLL
x-idempotency-key: ABCDQPR.31245.GFP.21
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-auth-date: Tue, 13 Jun 2023 19:43:31 GMT+03:00
x-fapi-customer-ip-address: 204.35.213.15
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Content-Type: application/json
Accept: application/json

Example:

{
  "Data": {
    "Initiation": {
      "EndToEndIdentification": "12345678",
      "InstructedAmount": {
        "Amount": "200”,
        “Currency”: “KWD"
      },
      "CreditorAccount": {
        "SchemeName": "KW.OBF.IBAN",
        "Identification": "2345678923",
        "Name": "Mohammad Abdullah"
      },
      "RemittanceInformation": {
        "Reference": "SHOP-101",
        "Unstructured": "Internal ops code 3412"
      }
    }
  },
      "StreetName": "Route 1666",
      "BuildingNumber": "30",
      "PostCode": "46300",
      "TownName": "Jabriya",
      "Country": "Kuwait"
    }
  }
}

5.8 Response

HTTP/1.1 400 Bad Request
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 75fdc714-f2dg-7676-c759-710d6715689g
Content-Type: application/json

Example:

{
  "Code": "400 BadRequest",
  "Id": "5b5f0fb3-860b-17e8-adc0-fa6ae01bbebc",
  "Message": "Invalid request parameters.",
  "Errors": [
    {
      "ErrorCode": "KW.OBF.Field.Missing",
      "Message": "Instructed identification is missing",
      "Path": "Data.Initiation.InstructionIdentification",
      "Url": "<url to the api reference for Payment Inititaion API>"
    },
    {
      "ErrorCode": "KW.OBF.Unsupported.Scheme",
      "Message": "Scheme name supplied is not supported",
      "Path": "Data.Initiation.CreditorAccount.SchemeName",
      "Url": "<url to the online documentation referring supported scheme names>"
    }
  ]
}