Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Integration and go-live checklist

Checklist for building and taking your Issuing integration live.

On this page you'll 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:

Verify your test credentials

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

Replace the {id} below with your balance platform name (you get this from your Adyen contact), and provide your API credentials (the web service user and password you received from your Adyen contact).

Try it out!
curl https://balanceplatform-api-test.adyen.com/bcl/v1/balancePlatforms/{id} \
  -u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
  -H "content-type: application/json"

If the call was successful, you receive an HTTP 200 result code along with the id and status of your balance platform.

Response
{
    "id": "YOUR_BALANCE_PLATFORM_ID",
    "status": "Active"
}

Create account holders and balance accounts

Onboard users as account holders and create balance accounts.

  1. Create account holders.
    Create one or more account holders depending on the account structure that you defined.
  2. Create balance accounts.
    Create balance accounts and link the accounts to the account holder(s).

Manage accounts

Learn how to update an existing account holder and how to get a list of all account holders and balance accounts.

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'll use the card details to make a test payment.

Manage card status

Depending on your use case, you'll need to be able to 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 ard is a permanent action and cannot be reversed.

Add and manage funds

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

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 balance platform 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 1500 milliseconds of the payment attempt, you'll have to:

  1. Expose an endpoint to handle relayed authorisation webhooks.
    Configure an endpoint to receive relayed authorisation. To differentiate relayed authorisation webhooks from other webhooks, make this a separate endpoint from your notification webhooks.
  2. Configure the endpoint in Adyen.
    Reach out to your Adyen contact to configure the endpoint within the Adyen platform.
  3. Respond to relayed authorisation webhooks.
    Respond to the webhook within 1500 milliseconds of the payment attempt, specifying if you would like to allow or decline the payment. Reach out to your Adyen contact to set up a default fallback logic. The fallback logic will be applied in case Adyen does not receive a 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'll 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 API.

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

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

Make a test payment
curl https://checkout-test.adyen.com/v64/payments \
-H 'x-api-key: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YourCompanyECOM",
  "reference": "My first Adyen test payment",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "paymentMethod": {
    "type": "scheme",
    "number": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "2030",
    "cvc": "737"
  }
}'

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

Process notification webhooks

The balance platform sends notification webhooks to communicate asynchronous events such as payments, captures, refunds, and fund transfers.

  1. Expose an endpoint to handle notification webhooks.
    You need to configure an endpoint in your system to be able to receive our webhooks. If you are using relayed authorisation, make sure you use a separate endpoint for notification webhooks, and a separate endpoint for relayed authorisation webhooks.
  2. Configure the endpoint in Adyen.
    Reach out to your Adyen contact to configure the endpoint within the Adyen platform.
  3. Receive and accept notification webhooks.
    Accept and process different notification types.

Reports

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

  1. Set up SFTP server access.
    Provide your SSH key and your IP addresses to your Adyen contact. We configure this on our end so you can securely log in and download reports from Adyen's SFTP server.
  2. Download reports.
    Make sure that you can programmatically download reports from the SFTP server.

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 acount 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:

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

    1. Switch to live Balance Platform 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 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.
    • Notification webhooks: Confirm that you can receive and accept notifications webhooks in the live environment.
    • Reports: Confirm that you can download reports for transactions in the live environment.