The Payments Initiation API enables applications to make payments directly from a customer's account.
Customers remain in control, providing approval for each payment.
You must be registered with the relevant competent authority as a Payment Initiation Services Provider (PISP), have valid transport and signing certificates in place and be onboarded as a Third Party. This can be done via an email specified in contacts.
The API allows a Payment Initiation Service Provider (PISP) to:
The Payment Initiation is intended to initiate a single immediate domestic payment with the consent of the customer.
Each customer must consent to allow you to initiate a payment request, consent is an agreement between you as the application owner and the customer. Once consent is agreed between you and the customer, the client application initiates the payment request, with authentication and request confirmation happening on the bank's web or mobile platform. The design of the API ensures that a customer's credentials are never shared with you, so they can be reassured that their credentials remain confidential at all times.
The process of gaining confirmation of payment request from a customer is a multi-step process. You must complete each of the steps below in order to initiate a payment request.
Firstly, you authenticate with us and obtain an Public Token. This token is used later to register payment requests.
Example Post Request
https://ob-dev.alsalambank.com/apigateway/as/token.oauth2
Header Request
Content-Type:application/x-www-form-urlencoded
Body Request
grant_type:client_credentials
scope:payments
client_assertion_type:urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
client_assertion:eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1IiwidHlwIjoiSldUIn0.eyJpc3MiOiJUUFAxIiwiaWF0IjoxNTYwMTUyNDM4LCJleHAiOjE1NjAyNTQ0MDAsImF1ZCI6Imh0dHBzOi8vcGctbXNzcWwubW9zY293LmNtYS5ydTo5ODc2L2FzL3Rva2VuLm9hdXRoMiIsInN1YiI6InM2QmhkUmtxdDMifQ.Sseu8PEDRWFiU-VwBoF9mlWGzjAfWB_Thy_xY5-6lnQkHiHd7qDnYBHfFfdfRvV2HKNRuiMAlv60CkRabZ6ibGbej1xOK_kBd2UfJU6bkpYhigUygDhN8J1zwE3pGLtwA6lgICv0ihELb5S2EWz7A_mXouZoydgytHuUtG1PpujIhaKnlXTDJX010Nrs3HmdrRRDLBcvPdsQHc6-ghNYTT9fAq3bMr2PNwofpvZxoNK2DpAE5Qf1ZY4sPNZAFfp8xkIFXSIX6zRaqo3rbopxKuDbhWKEXP92GIk5IRUhGzZ1j3ZD9GnT_QiBQ_GNpy53bt0f4izSZqhNM7Fg0W99UA
Corresponding Response:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJUUFAxIiwic2NvcGUiOiJwYXltZW50cyIsImlzcyI6IkFQSV9HVyIsImV4cCI6MTU2MDI0MjIyMiwiaWF0IjoxNTYwMTU1ODIyfQ.eNpQEwvlHZ09h44N9Ds2j11PfWaldI925aBBQc1UnQVXg1NqDIipbPwqwt9AkU2m7M2HvPnXuxd_LBIKsUlPtz4e5P2fP4bBLa9rmzFCZqwyn8TyOFUd8Uzg4YsP9y2AE_k-MN0Ggd0FFVlLWj1Xcs5YbQxdlnhDKcwhO-4yw946qXQ4jAtA1zuoPwDkzHqojf8iSHQyPvmgvqee8XgpSLG4qEw0QGR6pKQ6VLA4WfLjVnQZVTqyHfAMA7wxS65ZhmspM6mq2xcd52BDyOw7QaecB8Tz6APt-86o7fwxQBg8YsP_Rk2sLoUdCxkePG6dwXn1pyd3WsaSGWi5oBMaNg",
"expires_in": 86400,
"token_type": "bearer",
"scope": "payments"
}
Then we need register new consent using retrieved public token. In this step we will be redirected to AuthPage for consents authorization and in case of successful authorization will be issue authorized key which will be change on resource token (This will be used in the next query as/token.oauth2)
Example Post Request
https://ob-dev.alsalambank.com/apigateway/api/account-access-consents
Header Request
Content-Type:application/json
Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJUUFAxIiwic2NvcGUiOiJwYXltZW50cyIsImlzcyI6IkFQSV9HVyIsImV4cCI6MTU2MDI0MjIyMiwiaWF0IjoxNTYwMTU1ODIyfQ.eNpQEwvlHZ09h44N9Ds2j11PfWaldI925aBBQc1UnQVXg1NqDIipbPwqwt9AkU2m7M2HvPnXuxd_LBIKsUlPtz4e5P2fP4bBLa9rmzFCZqwyn8TyOFUd8Uzg4YsP9y2AE_k-MN0Ggd0FFVlLWj1Xcs5YbQxdlnhDKcwhO-4yw946qXQ4jAtA1zuoPwDkzHqojf8iSHQyPvmgvqee8XgpSLG4qEw0QGR6pKQ6VLA4WfLjVnQZVTqyHfAMA7wxS65ZhmspM6mq2xcd52BDyOw7QaecB8Tz6APt-86o7fwxQBg8YsP_Rk2sLoUdCxkePG6dwXn1pyd3WsaSGWi5oBMaNg
Body Request
{
"Data": {
"Permissions": [
"ReadAccountsDetail",
"ReadProducts",
"ReadStandingOrdersDetail",
"ReadTransactionsCredits",
"ReadTransactionsDebits",
"ReadTransactionsDetail",
"ReadPAN",
"ReadParty",
"ReadPartyPSU",
"ReadScheduledPaymentsDetail",
"ReadStatementsDetail"
],
"ExpirationDateTime": "2019-06-29T00:00:00+00:00",
"TransactionFromDateTime": "2019-05-03T00:00:00+00:00",
"TransactionToDateTime": "2019-12-03T00:00:00+00:00"
},
"Risk": {}
}
Corresponding Response:
{
"Data": {
"ConsentId": "lX7D-Ej4Tr6Qn8GwbWU5FA",
"Status": "AwaitingAuthorisation",
"StatusUpdateDateTime": "2019-06-10T08:38:25.064+0000",
"CreationDateTime": "2019-06-10T08:38:25.064+0000",
"Permissions": [
"ReadAccountsDetail",
"ReadProducts",
"ReadStandingOrdersDetail",
"ReadTransactionsCredits",
"ReadTransactionsDebits",
"ReadTransactionsDetail",
"ReadPAN",
"ReadParty",
"ReadPartyPSU",
"ReadScheduledPaymentsDetail",
"ReadStatementsDetail"
],
"ExpirationDateTime": "2019-06-29T00:00:00.000+0000",
"TransactionFromDateTime": "2019-05-03T00:00:00.000+0000",
"TransactionToDateTime": "2019-12-03T00:00:00.000+0000"
},
"Links": {
"Self": "https://ob-dev.alsalambank.com/authpage/consentId/lX7D-Ej4Tr6Qn8GwbWU5FA"
}
}
And code response
ZXlKaGJHY2lPaUpTVXpVeE1pSjkuZXlKemRXSWlPaUpoZFhSb1gyTnZaR1VpTENKamIyNXpaVzUwU1dRaU9pSnNXRGRFTFVWcU5GUnlObEZ1T0VkM1lsZFZOVVpCSWl3aWFYTnpJam9pVkUxVFhDOVlJaXdpWlhod0lqb3hOVFl3TWpReU5EUXdMQ0pwWVhRaU9qRTFOakF4TlRZd05EQjkubHc4NEVPYjZFVDJ2R0RSTU1rSHdxRWQwczVDc3FKanRjcUpkSDdjNGZLR1FGdm0tbVpLR0dOekdmS3hXTDNIZ3BxY21iMjJJNEtkN2RSVk0tcFpKVWZCZVR5ZVFuNWd1V3NFdmt6N3QzdHByazJoQmtzVC1GOE00S2hKNUhFSGt5dlpyVkExQ19VaGxVVDJoT2ZCbnRtZkxHd3JGam5vQUNmNEt4Rk9IMWtLY3p1MXVUbzBKbzJuVWI4UzFNb0U2U1JYREJvBHk5aldEZ3NyelAxaFdFeldXdDhJU3pHcWVuWHVMbm80X05MNjdPdWRRbERYaTlOeWpJU1FTZndwTTlCT2Y2VkRpejdCTHVpNTJpbmtFYTZxeEVwOG9SMWdQcTRPaXJKS1ZuZmRjQUhyUDVJa0haRjE4Z3JKUXVtd1NxYWhMZ0E0VFNYOFoxcjhzZkpzR3h3
This example post request describe how to exchange authorized key to resource token
Example Post Request
https://ob-dev.alsalambank.com/apigateway/as/token.oauth2
Header Request
Content-Type:application/x-www-form-urlencoded
Body Request
grant_type:authorization_code
code:ZXlKaGJHY2lPaUpTVXpVeE1pSjkuZXlKemRXSWlPaUpoZFhSb1gyTnZaR1VpTENKamIyNXpaVzUwU1dRaU9pSnNXRGRFTFVWcU5GUnlObEZ1T0VkM1lsZFZOVVpCSWl3aWFYTnpJam9pVkUxVFhDOVlJaXdpWlhod0lqb3hOVFl3TWpReU5EUXdMQ0pwWVhRaU9qRTFOakF4TlRZd05EQjkubHc4NEVPYjZFVDJ2R0RSTU1rSHdxRWQwczVDc3FKanRjcUpkSDdjNGZLR1FGdm0tbVpLR0dOekdmS3hXTDNIZ3BxY21iMjJJNEtkN2RSVk0tcFpKVWZCZVR5ZVFuNWd1V3NFdmt6N3QzdHByazJoQmtzVC1GOE00S2hKNUhFSGt5dlpyVkExQ19VaGxVVDJoT2ZCbnRtZkxHd3JGam5vQUNmNEt4Rk9IMWtLY3p1MXVUbzBKbzJuVWI4UzFNb0U2U1JYREJvBHk5aldEZ3NyelAxaFdFeldXdDhJU3pHcWVuWHVMbm80X05MNjdPdWRRbERYaTlOeWpJU1FTZndwTTlCT2Y2VkRpejdCTHVpNTJpbmtFYTZxeEVwOG9SMWdQcTRPaXJKS1ZuZmRjQUhyUDVJa0haRjE4Z3JKUXVtd1NxYWhMZ0E0VFNYOFoxcjhzZkpzR3h3
client_assertion_type:urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
client_assertion:eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1IiwidHlwIjoiSldUIn0.eyJpc3MiOiJUUFAxIiwiaWF0IjoxNTYwMTUyNDM4LCJleHAiOjE1NjAyNTQ0MDAsImF1ZCI6Imh0dHBzOi8vcGctbXNzcWwubW9zY293LmNtYS5ydTo5ODc2L2FzL3Rva2VuLm9hdXRoMiIsInN1YiI6InM2QmhkUmtxdDMifQ.Sseu8PEDRWFiU-VwBoF9mlWGzjAfWB_Thy_xY5-6lnQkHiHd7qDnYBHfFfdfRvV2HKNRuiMAlv60CkRabZ6ibGbej1xOK_kBd2UfJU6bkpYhigUygDhN8J1zwE3pGLtwA6lgICv0ihELb5S2EWz7A_mXouZoydgytHuUtG1PpujIhaKnlXTDJX010Nrs3HmdrRRDLBcvPdsQHc6-ghNYTT9fAq3bMr2PNwofpvZxoNK2DpAE5Qf1ZY4sPNZAFfp8xkIFXSIX6zRaqo3rbopxKuDbhWKEXP92GIk5IRUhGzZ1j3ZD9GnT_QiBQ_GNpy53bt0f4izSZqhNM7Fg0W99UA
Responce
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJUUFAxIiwiY29uc2VudElkIjoibFg3RC1FajRUcjZRbjhHd2JXVTVGQSIsImlzcyI6IkFQSV9HVyIsImV4cCI6MTU2MDI0MjUyMSwiaWF0IjoxNTYwMTU2MTIxfQ.HHDDSZgo4OYuH1H2BTXfYg0dWal9LOGiUx0crlxaZDzxJ4GxnEJIeWctkllD_8XcN-DlGih2R3aMmJdIqi0Dk5wvOU3nv0DN50nKTbTdjzce4DLFL2nYV21lhv0xNHKx5nG6DWXfAdLt3p_MrgMR_PO3i-4tzOrpU_QASWnlczfdxbZYbauscWdXksoaMAnVxvwqXT4TjPtCdVfm3YKSSHfC9U-698c16r0uAXZ2gmzA0GnWGqbfyv8gwV6bRY8rBv4R7huEoK0OUZtUL6NF8xbLTCJ3hHN6Gjm9kpdj-5j8fjYYbd3TgfO5Dlc_v5POrWva5E6tFlI4fJCAJET96Q",
"expires_in": 86400,
"token_type": "bearer"
}
In last step we will use resource token to get resource URLs via get request
Example Get Request
https://ob-dev.alsalambank.com/apigateway/api/accounts
Header Request
Content-Type:application/json
Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJUUFAxIiwiY29uc2VudElkIjoibFg3RC1FajRUcjZRbjhHd2JXVTVGQSIsImlzcyI6IkFQSV9HVyIsImV4cCI6MTU2MDI0MjUyMSwiaWF0IjoxNTYwMTU2MTIxfQ.HHDDSZgo4OYuH1H2BTXfYg0dWal9LOGiUx0crlxaZDzxJ4GxnEJIeWctkllD_8XcN-DlGih2R3aMmJdIqi0Dk5wvOU3nv0DN50nKTbTdjzce4DLFL2nYV21lhv0xNHKx5nG6DWXfAdLt3p_MrgMR_PO3i-4tzOrpU_QASWnlczfdxbZYbauscWdXksoaMAnVxvwqXT4TjPtCdVfm3YKSSHfC9U-698c16r0uAXZ2gmzA0GnWGqbfyv8gwV6bRY8rBv4R7huEoK0OUZtUL6NF8xbLTCJ3hHN6Gjm9kpdj-5j8fjYYbd3TgfO5Dlc_v5POrWva5E6tFlI4fJCAJET96Q
Responce
{
"Data": {
"Account": [
{
"AccountId": "K1iEoUt4RmuoKZkVyGKXCA",
"Status": "Enabled",
"Currency": "BHD",
"AccountType": "Personal",
"AccountSubType": "CurrentAccount",
"Account": [
{
"SchemeName": "PAN",
"Identification": "599995xxxxxx8997"
}
],
"Servicer": {
"SchemeName": "BICFI",
"Identification": "ALSABHBM"
}
},
{
"AccountId": "TxcKRRkvTA69PNWu3641vQ",
"Status": "Enabled",
"Currency": "BHD",
"AccountType": "Personal",
"AccountSubType": "CurrentAccount",
"Account": [
{
"SchemeName": "PAN",
"Identification": "799995xxxxxx1999"
}
],
"Servicer": {
"SchemeName": "BICFI",
"Identification": "ALSABHBM"
}
},
{
"AccountId": "jmSNPTYCTcCQm7XR1_4x0g",
"Status": "Enabled",
"Currency": "BHD",
"AccountType": "Personal",
"AccountSubType": "CurrentAccount",
"Account": [
{
"SchemeName": "IBAN",
"Identification": "BH02ALSA01010200120103"
}
],
"Servicer": {
"SchemeName": "BICFI",
"Identification": "ALSABHBM"
}
},
{
"AccountId": "n5ORPZKIQ5KX_PmVWGsW0A",
"Status": "Enabled",
"Currency": "BHD",
"AccountType": "Personal",
"AccountSubType": "CurrentAccount",
"Account": [
{
"SchemeName": "IBAN",
"Identification": "BH02ALSA01010200120102"
}
],
"Servicer": {
"SchemeName": "BICFI",
"Identification": "ALSABHBM"
}
},
{
"AccountId": "0TMho2SATQOBJcAfYtfCDg",
"Status": "Enabled",
"Currency": "BHD",
"AccountType": "Personal",
"AccountSubType": "CurrentAccount",
"Account": [
{
"SchemeName": "IBAN",
"Identification": "BH02ALSA01010200120101"
}
],
"Servicer": {
"SchemeName": "BICFI",
"Identification": "ALSABHBM"
}
}
]
},
"Links": null
}
POST /domestic-payments
Once the domestic-payment-consent has been authorised by the PSU, the PISP can proceed to submitting the domestic-payment for processing:
Status: A domestic-payment can only be created if its corresponding domestic-payment-consent resource has the status of Authorised.
The domestic-payment resource that is created successfully must have one of the following PaymentStatusCode code-set enumerations:
Example Request Header:
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Content-Type: application/json
Accept: application/json
Example Request Body:
{
"Data": {
"Initiation": {
"InstructionIdentification": " 85997",
"EndToEndIdentification": " ",
"InstructedAmount": {
"Amount": "165.88",
"Currency": "BHD"
},
"CreditorAccount": {
"SchemeName": "IBAN",
"Identification": "08080021325698",
"Name": "ABC LLC",
"SecondaryIdentification": "0002"
},
"RemittanceInformation": {
"Reference": "9831-101",
"Unstructured": "Internal ops code 5120101"
}
}
},
"Risk": {
"PaymentContextCode": "EcommerceGoods",
"MerchantCategoryCode": "5967",
"MerchantCustomerIdentification": "053598653254",
"DeliveryAddress": {
"AddressLine": [
"Flat 7",
"Al Barsha "
],
"StreetName": "Al Barsha ",
"BuildingNumber": "27",
"PostCode": "GU31 2ZZ",
"TownName": " ",
"CountySubDivision": [
"Wessex"
],
"Country": "BH"
}
}
}
Example Response Header:
Content-Type: application/json
Example Response:
{
"Data": {
"ConsentId": "58923",
"Status": "AwaitingAuthorisation",
"CreationDateTime": "2017-06-05T15:15:13+00:00",
"StatusUpdateDateTime": "2017-06-05T15:15:13+00:00",
"Initiation": {
"InstructionIdentification": " 85997",
"EndToEndIdentification": " ",
"InstructedAmount": {
"Amount": "165.88",
"Currency": "BHD"
},
"CreditorAccount": {
"SchemeName": " IBAN",
"Identification": "08080021325698",
"Name": "ABC LLC",
"SecondaryIdentification": "0002"
},
"RemittanceInformation": {
"Reference": "9831-101",
"Unstructured": "Internal ops code 5120101"
}
}
},
"Risk": {
"PaymentContextCode": "EcommerceGoods",
"MerchantCategoryCode": "5967",
"MerchantCustomerIdentification": "053598653254",
"DeliveryAddress": {
"AddressLine": [
"Flat 7",
"Al Barsha Lodge"
],
"StreetName": "Al Barsha Avenue",
"BuildingNumber": "27",
"PostCode": "GU31 2ZZ",
"TownName": " ",
"CountySubDivision": [
"Wessex"
],
"Country": "BH"
}
},
"Links": {
"Self": "https://ob-dev.alsalambank.com/apigateway/domestic-payment-consents/58923"
},
"Meta": {}
}
A PISP can optionally retrieve a payment consent resource that they have created to check its status.
Status: Once the PSU authorises the payment-consent resource - the Status of the payment-consent resource will be updated with Authorised.
If the PSU rejects the consent or the domestic-payment-consent has failed some other ASPSP validation, the Status will be set to Rejected.
Once a domestic-payment has been successfully created using the domestic-payment-consent, the Status of the domestic-payment-consent will be set to Consumed.
The available status codes for the domestic-payment-consent resource are:
Example Post Request:
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Content-Type: application/json
Accept: application/json
Example Request Body:
{
"Data": {
"ConsentId": "58923",
"Initiation": {
"InstructionIdentification": " 85997",
"EndToEndIdentification": " ",
"InstructedAmount": {
"Amount": "165.88",
"Currency": "BHD"
},
"CreditorAccount": {
"SchemeName": "IBAN",
"Identification": "08080021325698",
"Name": "ABC LLC",
"SecondaryIdentification": "0002"
},
"RemittanceInformation": {
"Reference": "9831-101",
"Unstructured": "Internal ops code 5120101"
}
}
},
"Risk": {
"PaymentContextCode": "EcommerceGoods",
"MerchantCategoryCode": "5967",
"MerchantCustomerIdentification": "053598653254",
"DeliveryAddress": {
"AddressLine": [
"Flat 7",
"Al Barsha "
],
"StreetName": "Al Barsha ",
"BuildingNumber": "27",
"PostCode": "GU31 2ZZ",
"TownName": " ",
"CountySubDivision": [
"Wessex"
],
"Country": "BH"
}
}
}
Example Response Body:
{
"Data": {
"DomesticPaymentId": "58923-001",
"ConsentId": "58923",
"Status": "AcceptedSettlementInProcess",
"CreationDateTime": "2017-06-05T15:15:22+00:00",
"StatusUpdateDateTime": "2017-06-05T15:15:13+00:00",
"Initiation": {
"InstructionIdentification": " 85997",
"EndToEndIdentification": " ",
"InstructedAmount": {
"Amount": "165.88",
"Currency": "BHD"
},
"CreditorAccount": {
"SchemeName": "IBAN",
"Identification": "08080021325698",
"Name": "ABC LLC",
"SecondaryIdentification": "0002"
},
"RemittanceInformation": {
"Reference": "9831-101",
"Unstructured": "Internal ops code 5120101"
}
}
},
"Links": {
"Self": "https://ob-dev.alsalambank.com/apigateway/domestic-payments/58923-001"
},
"Meta": {}
}