Payments Building Block

Running locally

Dependencies

Payments Building Block relies on two external dependencies:

Logto

Used for authentication and logging. Clone the OGCIO Logto fork repository and follow the instructions in its README to run it locally.

Life-Events

Clone the Life-Events repository and follow its README for setup and local running instructions. This will spin up multiples services, those needed by Payments are:

• Localstack: Emulates AWS services required by the application.
• Postgres: Provides the database service.
• Profile Service: Handles user profile functionalities.

Once both Logto and Life-Events are set up and running you can initialize both payments and payments-api services by running:

make start

Providers integration

Stripe Setup

1. Create a Stripe account
2. Find your test keys in the dashboard and fill in these env variables:
3. Make sure your desired payment methods are enable in the dashboard

Set up webhooks locally

Because Stripe can't reach your locally hosted API, you can't register your webhook callback into your Stripe account. In order to test the webhook integration and allow the system to update Stripe transactions' statuses, you either expose your local API to a public domain (by using ngrok or any other tool like that) or use the Stripe CLI client.

Stripe CLI allows you to test different transaction scenarios from your terminal easily. It can also listen to events in your Stripe account and forward them to your locally hosted webhook callback.

• Install Stripe CLI: brew install stripe/stripe-cli/stripe
• Log in to the CLI using your credentials or your API key.

Run stripe login and continue the login process in your browser (two-step verification might be required).

Or

Use the --api-key flag and use your API key in the login command stripe login --api-key YOUR_API_KEY

• Run stripe listen to start listening to the incoming events. To forward the incoming calls to your locally hosted API, you have to set the --forward-to flag and your local endpoint (without specifying the protocol): stipre listen --forward-to localhost:8000/api/v1/YOUR_WEBHOOK

Testing Google Pay and PayPal locally

To use Google Pay or PayPal you need to register and verify an HTTPS domain, even for testing.

• Use ngrok or a similar tool get an HTTPS domain. If you're using ngrok you can follow this guide to create a static domain and a tunnel.
• Register your fixed domain on your Stripe dashboard as explained here
• Set the HOST_URL environment variable to your fixed domain, so you'll get redirected there after logging in
• Register a real, active card on Google Pay wallet. No amount will be charged when using the card in test environment.
• If you want to test the integration with life events change this redirect to point to your fixed domain

Testing Apple Pay locally

To use Apple Pay you need to register and verify an HTTPS domain, even for testing.

• Use ngrok or a similar tool get an HTTPS domain. If you're using ngrok you can follow this guide to create a static domain and a tunnel.
• Register your fixed domain on your Stripe dashboard as explained here
• Follow these steps to verify the domain with Apple Pay
• Set the HOST_URL environment variable to your fixed domain, so you'll get redirected there after logging in
• Register a real, active card on Apple Pay wallet. No amount will be charged when using the card in test environment.
• Use Safari browser when testing the integration
• If you want to test the integration with life events change this redirect to point to your fixed domain

TrueLayer

TrueLayer is a leading European open banking payments network that leverages open banking technology to connect banks, people, and businesses with big aspirations, both in Europe and the United Kingdom.

It simplifies payments through its products, allowing for the acceptance and sending of instant bank payments on any app or website. TrueLayer provides a suite of integration tools designed for rapid development, including embedded payment interfaces, plugins for online stores, mobile SDKs, and backend libraries for various programming languages.

Visit the documentation for more info.

---

In order to use the True Layer integration locally, you will need to fill these env variables:

TL_CLIENT_ID=your_client_id
TL_CLIENT_SECRET=your_client_secret
TL_CERTIFICATE_ID=your_certificate_id
TL_PRIVATE_KEY=your_private_key_with_line_breaks_joined_by_'\n'

1. Follow the instructions to setup a console account and create an app here
2. You should now have your client_id and client_secret values. Copy them in the TL_CLIENT_ID and TL_CLIENT_SECRET env variables
3. Then follow these steps to generate your public and private keys
4. Upload your public key to the True Layer Console and create a Merchant account by following this guide
5. In the Settings > App Settings > Allowed redirect URIs, add our redirect URI to the True layer console - http://localhost:3001/en/paymentRequest/complete
6. Follow these steps to format your private key so it can be used within an environment variable. Copy the formatted key in the TL_PRIVATE_KEY environment variable
7. You can get the value for the TL_CERTIFICATE_ID variable under Payments > Settings > Signing keys. Copy the KID fied of your signing key and paste it in your .env file.

Realex

In order to use Realex integration locally, you will need to fill these env variables in the .env file for payments app (used for seeding the Realex provider):

REALEX_MERCHANT_ID=your_realex_merchant_id
REALEX_SHARED_SECRET=your_realex_shared_secret

And these env variables in the .env file for payments-api app:

REALEX_PAYMENT_ACCOUNT=internet
REALEX_PAYMENT_URL="https://pay.sandbox.realexpayments.com/pay"
PAYMENTS_HOST_URL=http://localhost:3001

Test credentials can be found in the dashboard.

Testing the integration locally

For the whole flow to work the endpoint called by Realex upon payment completion needs to be publicly available. If you don't follow these steps the integration will work only partially when testing it locally. It will be possible to initiate a payment and simulate a transaction but the HPP will fail to redirect the user to our application.

• Use ngrok or a similar tool get an HTTPS domain. If you're using ngrok you can follow this guide to create a static domain and a tunnel.
• Register your fixed domain
• Set the PAYMENTS_BACKEND_URL environment variable in payments app to your fixed domain, so Realex will be able to reach the endpoint it has to call
• Remember to start the agent with your fixed domain before testing. If you're using ngrok you can run the following command

ngrok http 8001 --domain your-registered-domain

Completed payments

Transactions on Realex side are available at this dashboard for sandbox environment and at this dashboard for production environment.

Test cards

Transactions can be simulated against Realex sandbox environment using the test cards listed here.