This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

International Payments

Owned by Former user (Deleted)
Last updated: Feb 26, 2019
12 min read

Follow the steps below to initiate an international payment order:

Sign up as a TPP user

  1. Navigate to the API Store while signed in as a TPP user.

  2. Click the Sign Up link at the top-left and navigate to the sign-up screen.  

  3. Provide the requested details as follows:

    1. Generic details

      FieldDescription
      Username/EmailThe username/email with which the TPP user signs in to the API Store.
      Retype PasswordThis prevents the TPP user from accidentally setting an incorrect password.
      PasswordThe password with which the TPP user signs in to the API Store.
      Last NameThe last name of the TPP user.
      First NameThe first name of the TPP user.

    2. Company details

      FieldDescription
      Legal Entity NameThe official name of the TPP.
      Country of RegistrationThe country in which the TPP is registered.
      Legal Identifier Number (LEI)This identifies the TPP.
      Company RegisterThe organization under which the TPP is registered.
      Company Registration NumberThe identifier issued at the TPP registration.
      Address Line 1The first line of the TPP address.
      Address Line 2The second line of the TPP address.
      CityThe city in which TPP is located.
      Postal CodeThe postal code of the TPP's geographical location.
      CountryThe country in which TPP is located.

    3. Competent Authority registration details

      FieldDescription
      Competent AuthorityThe regulatory body that authorizes and supervises the open banking services delivered by the TPP.
      Competent Authority CountryThe country of the competent authority that authorized the TPP to provide open banking services.
      Competent Authority Registration NumberThe registration number issued by the Competent Authority to the TPP.
      URL of the Competent Authority Register PageThe URL of the page that has the list of organizations authorized by the given competent authority.
      Open Banking Roles

      This captures the open banking roles the TPP is willing to take up:

      • Account Information Service Provider: An Account Information Service Provider (AISP) provides an aggregated view of all the accounts and past transactions that a customer has with different banks. To provide this view to the customer, the AISP should be authorized by the customer to view the corresponding transaction and balance information of all the payment accounts. The AISPs can also provide the facility to analyze the customer's spending patterns, expenses, and financial needs. Unlike a PISP, an AISP cannot transfer funds from a payment account.

      • Payment Initiation Service Provider: A Payment Initiation Service Provider (PISP) initiates credit transfers on behalf of a bank's customer.

      After selecting the PISP, indicate whether or not the TPP is authorized by a competent authority to provide the services of the selected roles.

      If the TPP is not yet registered to provide the services of the selected roles, indicate whether or not the TPP has applied for registration.

  4. Agree to the terms and conditions by selecting the check box.

  5. Click Sign Up. A request to approve the user sign up is sent to the Approver users.

Approve the TPP user

  1. Navigate to the Admin Portal  while signed in as an Approver user.

  2. Locate the approval request and click Assign To Me.    

  3. ClickStart to start the approval process.

  4. Select Approve and click Complete. The TPP user can now sign in to the API Store.

Sign-in as a TPP user

  1. Navigate to the API Store while signed in as a TPP user.

  2. Click Sign In and navigate to the sign in screen.

  3. Enter the username and password you entered at user sign up.

  4. Click Sign In. The API Store home screen is displayed along with the APIs. Remain in the API Store to create an application.

Create an application

  1. Sign in as a TPP user, and then click Applications on the API Store.

  2. Click Add Application.

  3. Enter application details:

    Field

    Description

    Name

    The application name.

    Per Token Quota

    This determines the maximum number of API requests accepted within a given duration.

    Description

    This describes the purpose of the application.

  4. Click Add. The application is created. Remain on the same page to generate application access tokens.

Subscribe to APIs

  1. Navigate back to the API Store while signed in as a TPP user.

  2. Click APIs.

  3. Select the PaymentInitiationAPI API version (e.g. v3.1).

  4. Select the application you created above.

  5. Set the throttling policy to Unlimited.

  6. Click Subscribe.

Create the certificates

  1. While signed in as a TPP user, create a keystore file by issuing the command below. Make sure that you update the following placeholders:  

    1. alias: A preferred alias for the keystore file  

    2. preferred-filename: A preferred name for the keystore file

      keytool -genkey -alias <<alias>> -keyalg RSA -keystore <<filename>>.jks

  2. Extract the certificate from the generated keystore file. Make sure you update the following placeholders:

    1. alias: This is an alias for the keystore.

    2. fileName: This is the certificate name.

    3. keyStoreName: This is the keystore name.

    keytool -export -alias <<alias>> -file <<fileName>> -keystore <<keyStoreName>>.jks

    In a production scenario, the created certificate needs to emailed to the ASPSP. 

  3. Provide the password you used for the keystore. The public key certificate is extracted to the same location where you ran the command.

  4. Convert the keystore from the jks format to PKCS12. Make sure you update the following placeholders:

    1. keyStoreName: This is the name of the keystore.

    2. PKCS12FileName: This is the name of the keystore in the PKCS12 format.

      keytool -importkeystore -srckeystore <<keystoreStoreName>>.jks -destkeystore <<PKCS12FileName>>.p12 -deststoretype PKCS12

  5. Create the application certificate (.pem) file using the keystore in the PKCS12 format, e.g. tpp.p12. Make sure you update the following placeholders:

  1. PKCS12FileName: This is the name of the keystore in the PKCS12 format.

  2. PEMFileName: This is the name of the application certificate that is created in the .pem format.

    openssl pkcs12 -in <<PKCS12FileName>>.p12 -nokeys -out <<PEMFileName>>.pem

Request access keys

  1. While signed in as a TPP user, click either of the following on the application details page:

    1. Production Keys to generate access tokens in the production environment.

    2. Sandbox Keys to generate access tokens in the sandbox environment.

  2. Provide the requested details as described below:

    Field

    Description

    Grant Types

    These determine the credentials that are used to generate the access token. There are six grant types available in WSO2 Open Banking:

    • Refresh Token: This renews expired access tokens.

    • SAML2: This exchanges an SAML access token with an OAuth access token.

    • Password: This obtains an access token by providing the resource owner's username and password.

    • Client Credential: This relates to the client credentials grant type and is applicable when consuming the API as an application.

    • IWA-NTLM: This is useful to obtain an access token for an API in a WSO2 Open Banking instance running on Windows.

    • Code: This relates to the authorization code grant type and is applicable when consuming the API as a user.

    Callback URL

    The URL used by the AISP/PISP to receive the authorization code sent from the Account Servicing Payment Service Provider (ASPSP), e.g. the bank. The authorization code can be used later to generate an OAuth2 access token.

    Application Certificate

    The content between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----  strings of the Application Certificate (.PEM) that you created above.

  3. Click Request Access if you are generating production keys. A request to approve the token generation is sent to the Approver user.

  4. Click Generate Keys if you generated sandbox keys. The consumer key and consumer secret are generated.  

Approve production key generation

  1. Navigate to the Admin Portal  while signed in as an Approver user.

  2. Click Tasks > Application Registration.

  3. Locate the approval request and click Assign To Me.

  4. Click Start to start the approval process.

  5. Select Approve and click Complete.

  6. Navigate back to the API Store and click Applications.

  7. Click View of the application that you created to navigate to the application details page.

  8. Click on the Production Keys tab and observe the generated keys: the consumer key and the consumer secret.

Upload the certificate

  1. Navigate to the Management Console while signed in as an Admin user.

  2. Click Main > Manage > Keystores > List.

  3. Click Import Cert relevant to your .jks keystore. By default, the filename of the keystore is  wso2carbon.jks. This may differ based on how you named your keystore.

  4. Click Choose File and select the certificate you generated above.

  5. Click Import. In the information message that appears, click OK.

  6. Click Finish and remain in the Management Console.

Generate an application access token

When invoking APIs in the PISP flow, application access tokens must be generated using the client credential grant type.

  1. While signed in as a TPP user, extract the fingerprint of the certificate created above.

  2. Generate the client assertion by signing the following JSON payload using the supported algorithms.

    {
  "alg": "<<This will be the algorithm used for signing>>",
  "kid": "<<This will be the certificate fingerprint>>",
  "typ": "JWT"
}

{
  "iss": "<<This is the issue of the token, e.g., client ID of your application>>",
  "sub": "<<This is the subject identifier of the issuer, e.g., client ID of your application>>",
  "exp": <<This is epoch time of the token expiration date/time>>,
  "iat": <<This is epoch time of the token issuance date/time>>,
  "jti": "<<This is an incremental unique value>>",
  "aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>"
}
<signature>

  3. Issue the following cURL command in a command prompt. Make sure you update the placeholders with the relevant values.

    curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" -k -d "grant_type=client_credentials&scope=payments&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<pass the signed key generated in the above>>&redirect_uri=<<The callback URL of your application>>" https://<<AM_HOST>>:8243/token/

    The access token is generated.

Invoke the Payment Initiation API

  1. Navigate back to the API Store while signed in as a TPP user.

  2. Click APIs.

  3. Select the PaymentAPI v3.1 API.

  4. Click the POST /international-payment-consents resource.

    1. Use the following as the body:

      {
  "Data": {
    "Initiation": {
      "InstructionIdentification": "<<This is the identification assigned by the instructing party to uniquely identify the instruction, e.g., ANSM023>>",
      "EndToEndIdentification": "<<This is the identification assigned by the instructing party to uniquely identify the transaction, e.g., FRESCO.21302.GFX.37>>",
      "InstructionPriority": "<<This is the indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction, e.g. , Normal>>",
      "CurrencyOfTransfer":"<<This is the currency of the to be transferred amount, which is different from the currency of the debtor's account, e.g. , USD>>",
      "InstructedAmount": {
          "Amount": "<<This is the transaction amount to be moved between the debtor and creditor, e.g., 20.00>>",
          "Currency": "<<This is the currency of the transaction in ISO 4217, e.g., GPB>>"
      },
      "CreditorAccount": {
        "SchemeName": "<<This is the unambiguous identification of the creditor account, e.g.SortCodeAccountNumber>>",
        "Identification": "<<This is the identification  assigned by an institution to identify an account, e.g., 08080021325698>>",
        "Name": "<<This is the name of the account, as assigned by the account servicing institution, e.g., Bob Clements>>"
      },
      "RemittanceInformation": {
        "Reference": "<<This is the information that enables matching an entry with the items that the transfer is intended to settle, e.g, .FRESCO-037>>",
        "Unstructured": "<<This is the information supplied to enable the matching/reconciliation of an entry, e.g., Internal ops code 5120103>>"
      },
      "ExchangeRateInformation": {
        "UnitCurrency": "<<Currency in which the rate of exchange is expressed in a currency exchange, e.g. , GBP>>",
        "RateType": "<<Specifies the type used to complete the currency exchange, e.g. , Actual>>"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PartyToParty"
  }
}
    2. To support idempotency, enter a unique request identifier in the x-idempotency-key field.
    3. Enter a unique ID that identifies the ASPSP in the x-fapi-financial-id field.
    4. In the Authorization field, enter the user access token you generated in the Generate User Access Token section. Use the Bearer:<< access token>> format.

    5. Click Try it out!. The API response bears the Payment ID.

Invoke the /authorize API

  1. Generate the request object by signing the following JSON payload using the supported algorithms, while signed in as a TPP user.

    {
  "alg": "<<This will be the algorithm used for signing>>",
  "kid": "<<This will be the certificate fingerprint>>",
  "typ": "JWT"
}

Body
{
	"aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>"	
	"iss": "<<This is the issue of the token, e.g., client ID of your application>>",
	"response_type": "<<This can be code or code id_token>>” 
	"client_id": "<<This is the client ID of your application>>",
	"redirect_uri": "<<This is the callback URL we set during application access token generation. Ref: Generate Application Access Token section>",
	"scope": "payments openid",
	"state": "<<Base64encoded("pisp":PaymentAPI)>>",
	"nonce": "<<This is a value used to prevent replay attacks>>",
	"max_age": 86400,
	"claims": {
    	"userinfo": {
        	"openbanking_intent_id": {
            	"value": "<<This is the PaymentId/ConsentId retrieved in Invoke the PaymentInitiationAPI API section>>",
            	"essential": true
        	}
    	},
    	"id_token": {
        	"openbanking_intent_id": {
            	"value": "<<This is the PaymentId/ConsentId retrieved in Invoke the PaymentInitiationAPI API section>>",
            	"essential": true
        	},
        	"acr": {
            	"essential": true,
            	"values": [
                	"urn:openbanking:psd2:sca",
                	"urn:openbanking:psd2:ca"
            	]
        	}
    	}
	}
} 

<signature>

    For a response type, use the values based on their purpose:

    • code: Retrieves the authorize code

    • code id_token: Retrieves the authorize token and ID token

  2. Issue the following in a browser to prompt and invoke the /authorize API. Make sure you update the placeholders with the relevant values.

    https://<<AM_HOST>>:8243/authorize/?response_type=<<This can be code or code id_token>>&client_id=<<the client-id of your application>>&scope=payments openid&redirect_uri=<<The Callback URL of your application>>&state=<<Base64encoded("pisp":PaymentId/ConsentId)>>&request=<<The request object generated in the step above>>
  3. Once you pass this call, you are directed to a login page. Log in with the credentials of a user having a subscriber role.
  4. If a secondary factor is required (e.g., SMSOTP), provide the relevant values.

Upon successful authentication, the user is redirected to the consent management page. Upon providing consent, an authorization code is generated.

Generate a user access token

This step involves generating an access token using the authorization code generated in the section above.

  1. Issue the following cURL command in a command prompt to generate the access token, while signed in as a TPP user.

    curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<<Authorization code we generated in the Invoke the /authorize API section>>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate Application Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>:8243/token
  2. Remain in the API Store.

Invoke the Payment Submission API

  1. In the API Store, click APIs.
  2. Select the PaymentAPI v3.1 API.
  3. Click the POST /international-payments resource.

    1. Use the following as the body:

      {
  "Data": {
    "ConsentId": "<<This is the ConsentId created in the Invoke the Payment Initiation API section>>",
    "Initiation": {
      "InstructionIdentification": "<<This is the identification assigned by the instructing party to uniquely identify the instruction, e.g., ANSM023>>",
      "EndToEndIdentification": "<<This is the identification assigned by the instructing party to uniquely identify the transaction, e.g., FRESCO.21302.GFX.37>>",
      "InstructionPriority": "<<This is the indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction, e.g. , Normal>>",
      "CurrencyOfTransfer":"<<This is the currency of the to be transferred amount, which is different from the currency of the debtor's account, e.g. , USD>>",
      "InstructedAmount": {
          "Amount": "<<This is the transaction amount to be moved between the debtor and creditor, e.g., 20.00>>",
          "Currency": "<<This is the currency of the transaction in ISO 4217, e.g., GPB>>"
      },
      "CreditorAccount": {
        "SchemeName": "<<This is the unambiguous identification of the creditor account, e.g.SortCodeAccountNumber>>",
        "Identification": "<<This is the identification  assigned by an institution to identify an account, e.g., 08080021325698>>",
        "Name": "<<This is the name of the account, as assigned by the account servicing institution, e.g., Bob Clements>>"
      },
      "RemittanceInformation": {
        "Reference": "<<This is the information that enables matching an entry with the items that the transfer is intended to settle, e.g, .FRESCO-037>>",
        "Unstructured": "<<This is the information supplied to enable the matching/reconciliation of an entry, e.g., Internal ops code 5120103>>"
      },
      "ExchangeRateInformation": {
        "UnitCurrency": "<<Currency in which the rate of exchange is expressed in a currency exchange, e.g. , GBP>>",
        "RateType": "<<Specifies the type used to complete the currency exchange, e.g. , Actual>>"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PartyToParty"
  }
}
    2. To support idempotency, enter a unique request identifier in the x-idempotency-key field.
    3. Enter a unique ID that identifies the ASPSP in the x-fapi-financial-id field.
    4. In the Authorization field, enter the user access token you generated in the Generate User Access Token section. Use the Bearer:<< access token>> format.

    5. Click Try it out!. The API response bears the Payment Submission ID (e.g., "InternationalPaymentId": "7290-003") along with the payment submission details.

  4. Click the GET /payment-submissions/{PaymentSubmissionId} resource.
    1. Enter the respective Payment Submission ID generated in the step above in the InternationalPaymentId field.
    2. Enter a unique ID that identifies the ASPSP in the x-fapi-financial-id field.
    3. In the Authorization field, enter the user access token you generated in the Generate User Access Token section. Use the Bearer:<< access token>> format.
    4. Click Try it out!. The API response bears the payment submission details.

Renew an access token

Issue the following cURL command while signed in as a TPP user to call the refresh_token endpoint and regenerate a new access token.

curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=refresh_token&refresh_token=<<This is the refresh token token generated in the Generate User Access Token section>>&scope=payments openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate User Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>>:8243/token/