Skip to main content

​
Custom API

starling, starling-sandbox

​
Scopes

  • Account Information 🔒
  • Payment Initiation 🔒

​
Live and Sandbox Environment (AIS)

  1. Register a new account on the platform
  2. Create an application
    1. Name your application
    2. Give your application a description, homepage url and redirect url
    3. Set the ‘Redirect’ to https://auth.yapily.com/
    4. Submit
  3. Take a note of your Client ID and Client Secret
  4. Add the Client ID as Key and Client Secret as Secret to your application in the Yapily Console
Note: to upgrade your application to Live please refer to the Going Live section of the Get Started

​
Live Personal Accounts (AIS Only)

  1. Register for a new Starling developer account on their website
  2. Create a Starling application
    1. Name your application
    2. Give your application a description, homepage url and redirect url
    3. Go to Personal Access Token tab and click on ‘Connect Accounts’
    4. Follow the instructions on the screen in order to connect your account
    5. Go back to the Personal Access tab and click on ‘Create Token’ add a token name and select the following scopes: account:read, balance:read, address:read, customer:read, transaction:read
    6. Copy the token and make a POST request to the Yapily API endpoint http://api.yapily.com/users/{user-uuid}/consents to add the token to create a consent resource for your application user
  3. Use the Yapily consent token to sign requests for users’ financial data

​
Live and Sandbox Environment (PISP)

  1. Register for a new Starling developer account on their website
  2. Create a Starling application
    1. Name your application
    2. Give your application a description, homepage url and redirect url
    3. Set the ‘Redirect’ to https://auth.yapily.com/
    4. Add Logo to your application.(It is required if permission upgrade for an application is to be requested.)
    5. Submit
  3. Take a note of your Client ID and Client Secret.
  4. Upload your KEYS:
    1. Create two pairs of public/private keys (Please refer [Generate Key Pair Section below]). One pair is used to sign the API request and other pair is used as a rotation key which is used to sign new key uploads.
    2. Store the keys securely.
    3. Upload the public key part of the signing key pair to your application in the Starling Developer Portal and generate Key Uid.
    4. Take a note of generated Key Uid.
    5. Click next to upload the public key part of the rotation key pair.
    6. The private key part of the signing key pair is to be uploaded in your application in the Yapily Console.
    7. The private key part of the rotation key pair is to be used to sign the new public key (the key used to sign the API). This is required only when an old signing key is to be replaced with new one.
  5. Add the Client ID as Key, Client Secret as Secret, Key Uid as Signing Key id and private key part of signing key pair as Private key to your application in the Yapily Console. The private key should either be:
    1. A complete private key, across new lines and with headers and footers, such as -----BEGIN RSA PRIVATE KEY-----` or
    2. A single line for the whole body of the signature without headers and footers.
Note:
  • To upgrade your application to Live please refer to the Going Live section of the Get Started
  • PISPs need to apply for a scope upgrade to have Payment Initiation Service permissions. They can apply upgrade via the Starling Developer Portal - Partners.
    1. Read the Permission Upgrade Guide
    2. Click the Upgrade permissions button.
    3. Select an application for which upgrade is required from the list. It will take you to the Application Preview page.
    4. Click next to go to the Permissions page.
    5. Select following permissions (or scopes) on the page: account:read, balance:read, confirmation-of-funds:read,address:read, payee:read, transaction:read, pay-local:read, mandate:read, standing-order:read, account-identifier:read, account-holder-name:read, account-holder-type:read, customer:read, customer:read, payee:create, pay-local:create, pay-local-once:create, pay-foreign:create, standing-order:create`.
    6. Next, select the regulated status of your company.
    7. Download the Partner Application Form. Complete the form and upload it on the link provided on the same page.
    8. Click Next and provide your company details and submit the request.

​
Generate Key Pair

The key requirements for Starling are as follows:
  • Keys must be either RSA or ECDSA keys.
  • RSA keys should have a length of either 2048 or 4096.
  • ECDSA keys should have a length of 256.
  • RSA keys should not be SSH keys. All valid RSA key bodies will start with MII.
The above requirement can be met as follows: OpenSSL - Generate ECDSA or RSA pair using either of the following code snippets

​
RSA:

  1. Create a 2048 bit key pair:
openssl genrsa -out private_signing.key.pem 2048 openssl genrsa -out private_rotation.key.pem 2048
  1. Extract public key
openssl rsa -in private_signing.key.pem -out public_signing.key -pubout openssl rsa -in private_rotation.key.pem -out public_rotation.key -pubout

​
ECDSA:

  1. Create a key pair:
openssl ecparam -genkey -name prime256v1 -noout -out private_signing.key.pem openssl ecparam -genkey -name prime256v1 -noout -out private_rotation.key.pem
  1. Extract public key
openssl ecparam -in private_signing.key.pem -out public_signing.key -pubout openssl ecparam -in private_rotation.key.pem -out public_rotation.key -pubout Java - Generate ECDSA or RSA pair using either of the following code snippets

​
RSA:

KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA"); keyPairGenerator.initialize(2048, new SecureRandom()); KeyPair signingKey = keyPairGenerator.generateKeyPair(); String publicSigningKey = new String(Base64.getEncoder().encode(signingKey.getPublic().getEncoded())); String privateSigningKey = new String(Base64.getEncoder().encode(signingKey.getPrivate().getEncoded())); KeyPair rotationKey = keyPairGenerator.generateKeyPair(); String publicRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPublic().getEncoded())); String privateRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPrivate().getEncoded()));

​
ECDSA:

KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC"); keyPairGenerator.initialize(256); KeyPair signingKey = keyPairGenerator.generateKeyPair(); String publicKey = new String(Base64.getEncoder().encode(signingKey.getPublic().getEncoded())); String privateKey = new String(Base64.getEncoder().encode(signingKey.getPrivate().getEncoded())); KeyPair rotationKey = keyPairGenerator.generateKeyPair(); String publicRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPublic().getEncoded())); String privateRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPrivate().getEncoded()));

​
OpenBanking API

starling_ob, starling_ob-sandbox

​
Scopes

  • Account Information 🔒

​
Onboarding ASPSP’s to Yapily Application

​
OB Certificates

Precondition: To connect to Starling OB institutions with OB certs a dynamic registration request (DCR) is needed. Pre-requisites for DCR:
  • Valid OBWAC / OBSEAL certificates
  • SSA (downloaded from OBIE directory) - Optional

​
Steps Required for DCR registration

  1. Download your SSA from the OBIE directory (optional - see step 3) Open the OBIE Directory for your organisation, navigate to the SSA you want to use for the registration and generate the SSA. The downloaded SSA has to be passed as is to the registration endpoint; do not alter the contents or format.
  2. Upload the signing (OBSEAL) and transport (OBWAC) certificates into V2 services Request 
    curl --location --request POST '[https://api.yapily.com/certificates/keys/](https://api.yapily.com/certificates/keys/)' \

--header 'Authorization: Basic YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
--header 'Content-Type: application/json' \
--data-raw '[{
   "pem": "$YOUR_PUBLIC_KEY_AS_PEM",
   "key": "$YOUR_PRIVATE_KEY",
   "kid" : "$CERT_KID",
   "name" : "$CERTIFICATE_NAME"
}]'
    Response 
    {
"id": "d16f87d3-4222-4173-b8b9-44aeccacae7d",
....
}
    Save the id and remember for which kind of key it corresponds: e.g. SIGNING_KEY_UUID = d16f87d3-4222-4173-b8b9-44aeccacae7d Once you have done it for the signing key, do the same request for your transport key.
  3. Call the registration endpoint The final step is to call the registration endpoint with the certificate UUIDs and the downloaded SSA: Request Do not alter the downloaded SSA. Pass directly to the register endpoint in its JWS format. 
    curl --location --request POST 'https://api.yapily.com/institutions/starling_ob/register' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
     --data-raw '{
            "signingKeyID": "$SIGNING_KEY_UUID",
            "transportKeyID": "$TRANSPORT_KEY_UUID",
            "ssa": "$DOWNLOADED_SSA"
     }'
    If you are not manually supplying the SSA, then you will need to add two additional request body parameters; softwareStatementId and organisationId - these must match the JWKS URL that corresponds to your OB certificates : 
    curl --location --request POST 'https://api.yapily.com/institutions/starling_ob/register' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
     --data-raw '{
            "signingKeyID": "$SIGNING_KEY_UUID",
            "transportKeyID": "$TRANSPORT_KEY_UUID",
            "softwareStatementId" : "N7i....",
            "organisationId" : "0014H...."
     }'
    Response 
    {
   "id": "a0460a91-4b4c-422a-bbe6-bebe0b92e308"
}
Note above ID, this will be the clientId which can be further used to Get, Modify, Delete registrations with Yapily

​
Support

If you require technical support with certificate management, please contact Support.