Testing Guide for Payment Initiation APIs

This guide explains how to test the Payment APIs of the 'Payment Initiation (Secure)' API product. A Client ID and Client Secret has been included in the attached Postman collection for convenience. However, you should sign up to the portal, create an application and subscribe to the 'Payment Initiation (Secure)' API product. This will give you your own Client ID and Client Secret for invoking the APIs. Please refer to the Getting Started page for instructions on how to do this.  

Postman collection to test Payment APIs

Below you can find the link to a test suite with the steps required to test the payment APIs. It includes HTTP requests with sample headers and test data.

Postman is a free REST test tool, you can download if from here . Save the content of the link below as a .json file and then import it in the tool as a test collection.

Link to postman collection

The rest of this page explains the steps implemented in the test suite. You can use this information as a guidance for the logic you need to implement in your application to be able to execute a payment.

Steps to test Payment APIs

1. Obtain an access token to invoke the Payments API

In this step you use the TPP credentials to obtain the access token required to submit a payment intent.

Call the POST /oauth2/token endpoint in the tppoauth2security API. The following parameters must be passed as headers in the HTTP request (changing the values as required).

Headers

Parameter Value Description
grant_type client_credentials The grant type being requested
client_id c1d81a9a-609a-47be-9363-8fa038b987da The client ID of your application registered in the developer portal
client_secret qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR5kO6dB7dJ4iU7qI0yB The client secret of your application registered in the developer portal
scope tpp_client_credential The scope being requested. This must match the scope in the POST /payments endpoint in the Payment Initiation APIs


2. Invoke the Payments API to obtain a payment ID

You now use the token obtained in the previous step to create a payment request. The payment will have to be approved by the end customer (step 3) before you can finally submit it (step 6)

Call the POST /open-banking/payments endpoint in the Payment Initiation APIs API. The following must be passed in the headers and body of the HTTP request (changing the values as required).

Headers

Parameter Value Description
authorization

Bearer AAEkMjliM2Q5OGUtMjYxYy00NDE3LWFiNjItNTM2Mjg3YWVmNTE5jJKryi7efsz5WxZ8roc

WOoHGVihnpGHAhaLr04WwGdfC_3sI2jL3AIIuWNrkqMB1vm15Fral817lh_5uYDBiTWQx7vn65jp

5waZyFReBcaPiepmLGp281APs5CKQPjwiMeB8GOJC0EhdFDgZA5cC5Q

The access token obtained in step 1

Body

Parameter Value Description
data > see message body in the postman collection The request data required to call the API

 Take note of the payment ID in the response data. You will need this as the reference to the payment intent that needs to be approved by the customer.

3. Obtain consent from the customer to execute the payment

You now start the three legged OAuth2.0 flow that will enable the ASPSP (the bank) to authenticate the customer and capture its consent to the payment.

Using a web browser, invoke the URL below to emulate the customer giving consent for the payment to be made (changing the values as required. Most importantly, the openbanking_intent_id value of the OIDC request token must be the same as the payment ID retrieved in step 2).

      https://api.eu.apiconnect.ibmcloud.com/cmarcoliukibmcom-open-banking-aggregator/rw-sandbox-production/psuoauth2security/v1.0.5/oauth2/authorize?response_type=code&client_id=c1d81a9a-609a-47be-9363-8fa038b987da&state=123456&scope=payment openid&redirect_uri=https://example.com/redirect&nonce=4987594875485-j&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5hbHBoYW5iYW5rLmNvbSIsImF1ZCI6InM2QmhkUmtxdDMiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL2V4YW1wbGUuY29tL3JlZGlyZWN0Iiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwibm9uY2UiOiI0OTg3NTk0ODc1NDg1LWoiLCJtYXhfYWdlIjo4NjQwMCwiY2xhaW1zIjp7InVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6IjE1MDQwMjE0NjU4MTUiLCJlc3NlbnRpYWwiOnRydWV9fSwiaWRfdG9rZW4iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiMTUwNDAyMTQ2NTgxNSIsImVzc2VudGlhbCI6dHJ1ZX0sImFjciI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI6WyJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJ1cm46b3BlbmJhbmtpbmc6cHNkMjpjYSJdfX19LCJqdGkiOiI2NThmYzg1MS03NzdjLTQ1MjEtOWY1Mi0zMGE0OWM3ZjQyMzgiLCJpYXQiOjE1MDI0Njc5ODIsImV4cCI6MTUwMjQ3MTY1OH0.7R4HcpmV5unXSmYEOfWhhU71iqLhnbA9Q88X72KOt0s

URL Parameters

Parameter Value Description
authorization

response_type

The OAuth flow type being used
client_id

c1d81a9a-609a-47be-9363-8fa038b987da

The client ID of your application registered in the developer portal
state

12345

The state as specified by the TPP
scope

payment openidpayme

The scope being requested. Must match the scope of the POST open-banking/payment-submissions endpoint
redirect_uri

https://example.com/redirect

The redirect URL of the application registered in the developer portal
nonce

4987594875485-j

The nonce as specified by the TPP
request

<see value in url above>

This is a oidc request object containing a claim identifying the payment that needs to be authorized.
To modify it to support your test scenario use the debugger at https://jwt.io:
- copy the encoded value of this example
- modify the decoded json object specifying the id of the payment you want to authorize in the openbanking_intent_id field
- use the new encoded string as oidc request object when you call the /authorize endpoint

Follow the UI flow and at the end, take note of the authorisation code appended to the URL (e.g. https://example.com/redirect?code=xxxxxxxxxxxxx).

4. Get the access token required to execute the payment

Following the OAuth2.0 protocol, you know exchange the access code for the access token required for step 6. If you want you can see, following the instruction of step 5, how is token is linked to the payment approved by the customer.

Call the POST /oauth2/token endpoint in the psuoauth2security API. The following must be passed in the headers and body of the HTTP request (changing the values as required).

Body

Parameter Value Description
client_id c1d81a9a-609a-47be-9363-8fa038b987da Client id of your application
client_secret qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR5kO6dB7dJ4iU7qI0yB  Client secret of your application
grant_type authorization_code The grant type being requested
redirect_uri https://example.com/redirect The redirect URL which must match that of the application registered in the developer portal. 
code

AAINOPze9ca_secTAjtK7xfjYM3cuUR12Tqedf0mmCXx0K1viL8UQke3vb7Q65NegBoPN8GADS7-

kVvJjLlUuwjb60mH09duTXxB2V49GD9jeJjOa8Idpz6JNCFukBBzA9W90JdKiEjMXQf6cM8QFqudNJ4jGQecmI_

JFWRwIcvXDeesKJlX4I_uSEzRbrZ2lmRk5R9o5-2sUCen_

vRgv8nxUh6u57OXp9gXZPzhzzDWe4bALn5kp6AoKcG9E7FBGWWZQDIF7D9cqz9LGXZIcT8

The authorisation code retrieved in step 3 

 Take note of the access token in the response data.

5. Introspect the access token (optional)

Note that this step is not required for the execution of the transaction, however looking at the content of the access token wil help you understand how the system is working, behind the scenes.

Call the  POST /oauth2/introspect endpoint in the  psuoauth2security API to obtain the data contained inside of the access token.  The following must be passed in the headers and body of the HTTP request  (changing the values as required).

Header

     Parameter     Value     Description
     x-ibm-client-id     c1d81a9a-609a-47be-9363-8fa038b987da     Cliend id of your application
     x-ibm-client-secret     qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR5kO6dB7dJ4iU7qI0yB     Client secret of your application

Body

Parameter Value Description
token

AAEkMjliM2Q5OGUtMjYxYy00NDE3LWFiNjItNTM2Mjg3YWVmNTE5eegFiXh16pNoEDwNfpByhJic3nZRikKL_

GwGgkmhYxMFPXRIu3cOmrcjCumaKttumnfZl6n0IO7pS0puWFuPVN5uDufH9zCzPfb_EKOC1Dj3G3ex0c4EG-UqiEffwb_B1Wf_S1XULelK-9EcNNVKh2jKCRkC-g3wIjllh3a9651sCChfpjsbjIbe0yofQnA21CjouEM8YtfkrSKHMYOZbu81yacMfljfQKrKZM-47HI

The token obtained in step 4
token_type_hint access_token Must be 'access_token'

6. Submit the payment for execution

You can now use the access token to execute the payment.

Call the POST /open-banking/payment-submissions endpoint in the  Payment Initiation APIs API to execute the payment. The following must be passed in the headers and body of the HTTP request  (changing the values as required).

Headers

Parameter Value Description
authorization

Bearer AAEkMjliM2Q5OGUtMjYxYy00NDE3LWFiNjItNTM2Mjg3YWVmNTE5eegFiXh16pNoEDwNfpByhJic3nZRikKL_

GwGgkmhYxMFPXRIu3cOmrcjCumaKttumnfZl6n0IO7pS0puWFuPVN5uDufH9zCzPfb_EKOC1Dj3G3ex0c4EG-UqiEffwb_B1Wf_S1XULelK-9EcNNVKh2jKCRkC-g3wIjllh3a9651sCChfpjsbjIbe0yofQnA21CjouEM8YtfkrSKHMYOZbu81yacMfljfQKrKZM-47HI

The token obtained in step 4

Body

Parameter Value Description
data         
> see message body in the postman collection                                                                          The data associated with the payment request, including the payment ID obtained in step 2