Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
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"
}

Onboard legal entities

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

  1. Identify the required KYC information.
    Check the required KYC information based on the country 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 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 card 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 webhooks. To differentiate relayed authorisation webhooks from webhooks for other platform events, make sure 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/v67/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 notifications from webhooks

The balance platform sends notifications to communicate asynchronous events in your platform such as payments, captures, refunds, and fund transfers. You receive these notifications through webhooks.

  1. Configure a webhook endpoint.
    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.
    Reach out to your Adyen contact to configure the endpoint within the Adyen platform.
  3. Receive and accept notifications.
    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 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:

  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.