Integration and go-live checklist

On this page you learn the steps for developing an Adyen Issuing integration and for taking your integration live.

Before you start building your integration, make sure that you have already:

• Designed your implementation.
• Received your Issuing test account and API credential from your Adyen contact.

Verify your test credentials

To verify that your test API credentials are working, make your first requests.

You need the API keys of the following credentials to make these requests:

• ws_[123456]@BalancePlatform.[YourBalancePlatform]: use this API key to make requests to the Configuration API and the Transfers API.
• ws_[123456]@Scope.Company_[YourCompanyAccount]: use this API key to make requests to the Legal Entity Management API using basic authentication.

Try out the requests below.

Onboard legal entities

Before you can start issuing cards, your account holders need to go through verification checks. Adyen performs the checks against the legal entity of the account holder.

1. Identify the required information.
   Check the required information based on the location where the account holder is operating in.
2. Create legal entities.
   Create a legal entity resource for the account holder's organization and for the individuals associated to the organization.
3. Add transfer instruments.
   For use cases that involve moving funds between balance accounts and bank accounts, add a transfer instrument to represent the account holder's bank account.
4. Upload additional documents.
   Adyen may also require you to upload additional documents if needed.

Create account holders and balance accounts

Create an account holder and one or more balance accounts.

1. Create account holders.
   Create an account holder and link it to their legal entity.
2. Create balance accounts.
   Create balance accounts and link the accounts to the account holder(s).

Manage your platform

Learn how to update manage account holders and balance accounts to view details or update statuses.

• Manage account holders.
  View and update account holders in your platform.
• Manage balance accounts.
  View and update balance accounts in your platform.

Create cards

Create virtual or physical cards depending on your use case.

When you successfully create virtual cards in the test environment, you receive the card number, expiry date, and CVC. You use these card details to make a test payment.

Manage card status

Depending on your use case, you can change a card's status.

• Suspend a single-use card after it has been used.
  If a single-use card has been used, suspend the card to temporarily prevent payments.

• Close a card.
  If a card should no longer be used, close the card. Closing a card is a permanent action and cannot be reversed.

Add and manage funds

To make test payments with an Adyen-issued card, you need to make sure the balance accounts have funds.

• Add funds to your liable balance account.
  Reach out to your Adyen contact to help you add funds to your liable balance account in the test environment.

When you have the funds on your liable balance account, you can then:

• Manage funds.
  Transfer funds to other balance accounts. The flow of funds between the liable balance account and other balance accounts depends your business logic and on how you designed your account structure.

Approve or decline payments

With relayed authorisation, you approve or decline a payment by responding to a webhook. With transaction rules, payments are approved or declined based on conditions. You can use relayed authorisation, transaction rules, or both.

When combined, transaction rules are applied first, serving as a filtering mechanism for payment attempts before sending you the relayed authorisation webhook.

Use relayed authorisation

If you decide to use relayed authorisation to approve or decline payments within 2000 milliseconds of the payment attempt, you have to:

1. Expose an endpoint to handle relayed authorisation webhooks.
   Configure an endpoint to receive relayed authorisation webhooks. To differentiate relayed authorisation webhooks from webhooks for other platform events, make sure this a separate endpoint from your webhooks.
2. Configure the relayed authorisation webhook in Adyen.
3. Respond to relayed authorisation webhooks.
   Respond to the webhook within 2000 milliseconds of the payment attempt, specifying if you want to allow or decline the payment.
   You can define default fallback logic for Adyen to apply to the payment attempt in cases when Adyen does not receive a response, or receives an invalid response, from you.

Use transaction rules

Before you start creating transaction rules, make sure that you have already clearly defined your business logic and requirements when approving or declining payments. You turn these requirements into rule conditions.

1. Create payment instrument groups.
   Grouping together payment instruments is useful if you want to apply a transaction rule to multiple cards. Create a payment instrument group, assign cards to the group, and assign a transaction rule to the group.
2. Create transaction rules.
   Define rule conditions. A payment is automatically approved or declined depending on the conditions in the transaction rule. A transaction rule must be linked to one payment instrument, payment instrument group, or the whole balance platform.

Make test payments

Ask your Adyen contact for your online payments API credential. This API credential is different from the one that you use with the Balance Platform or Legal Entity Management APIs.

You use your online payments API credentials to simulate payments in the test environment using the /payments endpoint.

For example, to make a EUR 10 payment, replace the number, expiryMonth, expiryYear, and cvc with the card details you received when you created the card.

The response depends on whether you approved or declined the payment.

Process webhooks

Adyen sends webhooks to communicate asynchronous events in your platform such as payments, captures, refunds, and fund transfers.

1. Configure a webhook endpoint on your server.
   Set up a webhook endpoint in your system to receive webhooks from Adyen. If you are also accepting relayed authorisation webhooks, make sure to use separate endpoints.
2. Configure the endpoint in Adyen.
   • Configure regular webhooks
   • Configure relayed authorisation webhooks
3. Receive and accept webhooks.
   Accept and process different webhook types.

Download reports

You can use reports to reconcile payments and balances in your system.

1. Set up your reports credentials.
   Your Adyen contact will provide you with a reports credential, which you need if you want to programmatically download reports.
2. Download reports.
   Listen to the balancePlatform.report.created webhook to know when a report was generated and is ready to be downloaded. To download a report, you must authenticate your GET requests with your report credentials.

Going live

To start issuing cards in the live environment, you need to apply for a live account. When you have your live account, follow the steps below to take your integration live.

1. Replicate your test account setup.

   The setup from your test Adyen Issuing account is not replicated to your live Adyen Issuing account. If you created the following resources in your test environment, make sure that you replicate your setup in your live account:

   • Account holders
   • Balance accounts
   • Transaction rules
   • Payment instrument groups
     
     

2. Update your code base.
   Update your code base and Issuing account settings.

   1. Switch to live Balance Platform and Legal Entity Management API credentials.
      Get your live API credentials from your Adyen contact. Copy these keys to your live platform.

   2. Switch from test to live endpoints.
      Change the test endpoint https://balanceplatform-api-test.adyen.com/ to live
      https://balanceplatform-api-live.adyen.com/.
      
      

3. Run end-to-end tests.

   • Live Balance Platform and Legal Entity Management API credentials: Make your first live API request to make sure that your live API credentials are working.
   • Account holders and balance accounts: Confirm you can create and retrieve account holders and balance accounts.
   • Cards: Confirm that you can create cards.
   • Transaction rules: Confirm that you can create and manage transaction rules.
   • Relayed authorisation: Confirm that you can receive relayed authorisation webhooks, and that you can successfully respond to approve or decline payments.
   • Payments:
     • Test the happy flow by making payments with cards you created in the live environment.
     • Test non-happy payment flows where payments are declined through relayed authorisation or transaction rules.
   • Webhooks: Confirm that you can receive and accept webhooks in the live environment.
   • Verification errors: Test your error handling scenarios when onboarding users.
   • Reports: Confirm that you can download reports for transactions in the live environment.