Authentication

1. Login to Adyen using your admin account

2. Go to the left panel and find Company Account and Merchant Account on the top left corner

2. Click on Developers -> API credentials -> Create crdential button

3. Click on Report user

4. Copy input password from the Basic Auth section and click Save at the bottom of the screen
   Make sure to store this password somewhere safe

5. Click on Developers and select the Report-User you just created, and click on Generate New API Key

6. Copy and store the API key then click on Save Generated API Key
   Make sure to copy the API key and pasting to your computer before clicking on the Save button

7. Remain on the same Report User page, Go to Roles and Associated Accounts section, ensure Merchant Report Download role is enabled. Click Save to save the Report User configuration

8. Click on Developer -> Webhooks -> + Webhooks button -> Add Standard notification

9. Make sure to toggle Enabled on the top right and click on Edit icon for Server configuration

10. Input the following values to the input fields and click Apply

• URL: <<<<<<<<<<<https://api.leapfin.com/webhook/adyen>>>>>>>>>>>
• Method: JSON
• SSL Version: TLSv1.2

11. Click on Edit Merchant accounts and select Include only specific Merchant Accounts that Leapfin needs access to. Click Apply.

12. Click on Edit Basic authentication and input a username into the field. This will be used for the Leapfin-Adyen connector. Click Apply and Save changes to save.

• User name: Webhook User Name

  • This will be the username used for Leapfin-Adyen connection, so remember to document it

  • Its recommended to choose a name unique to your leapfin account.

    • Recommendation: <company_name>_<prod/sandbox>_webhook

      • e.g. for ABC Company sandbox, the Username can be abc_sandbox_webhook

• Password: Report user password created basic auth creation in the previous step

13. Navigate to Reports on the left panel and enable the following reports:
    a) Dispute transaction details: Automatic generation
    

b) Payment accounting: Automatic generation

c) Settlement details: Automatic generation

14. Login to Leapfin -> Organization dropdown on the top right -> Integrations -> Connect (Adyen).
    Make sure your account has admin access

15. Input data according to the following and click Confirm at the bottom of the box.

• Company Account: From step 2
• Merchant Account: From step 2
• Report User: From step 4. example: report_008476@Company.LeapfinTechnology
• Report User Password: From step 4
• Webhook User: From step 12. example: <company_name>_<prod/sandbox>_webhook

Data Sources

Once authenticated, Leapfin will fetch and process following types of data from Adyen.

Payment Accounting Report

Each row in Ayden's payment accounting report is imported in Leapfin as an adyen-accounting-record. The schema of the report can be found in Adyen's documentation here. Leapfin relies on Adyen's webhook to receive notifications and download reports when available.

🚧

Configuration requirement

In order for Leapfin to fully process data from Ayden, two additional fields should be added to Ayden's payment accounting report.

• "Creation Date"
• "Modification Psp Reference"

Following Ayden's guide here to configure report columns.

Sample Data

{
    "Store": "",
    "MarkupSC": "",
    "TimeZone": "AEST",
    "UserName": "[email protected]",
    "PayableSC": "",
    "CapturedPC": "5.00",
    "MainAmount": "5.00",
    "ReceivedPC": "0.00",
    "RecordType": "SentForSettle",
    "BookingDate": "2019-09-03 00:02:10",
    "AuthorisedPC": "-5.00",
    "CommissionSC": "",
    "MainCurrency": "BRL",
    "PayableBatch": "",
    "PspReference": "1234567890123456789",
    "SchemeFeesSC": "",
    "InterchangeSC": "",
    "IssuerCountry": "BR",
    "PaymentMethod": "mc",
    "CompanyAccount": "companyY",
    "ShopperCountry": "",
    "MerchantAccount": "merchantX",
    "PaymentCurrency": "BRL",
    "ProcessingFeeFC": "",
    "UniqueTerminalID": "",
    "MerchantReference": "xXxXbdExD",
    "SettlementCurrency": "",
    "PaymentMethodVariant": "mccredit",
    "ProcessingFeeCurrency": "",
    "ModificationPspReference": "1234567890123456789",
    "ModificationMerchantReference": "xXxXbdExD"
}

Settlement Details Report

Each row in Ayden's settlement details report is imported in Leapfin as an adyen-settlement-record. The schema of the report can be found in Adyen's documentation here. Leapfin relies on Adyen's webhook to receive notifications and download reports when available.

Sample Data

{
    "Type": "MerchantPayout",
    "MarkupNC": "",
    "TimeZone": "EDT",
    "Reserved4": "",
    "Reserved5": "",
    "Reserved6": "",
    "Reserved7": "",
    "Reserved8": "",
    "Reserved9": "",
    "NetDebitNC": "4.16",
    "Reserved10": "",
    "BatchNumber": "1",
    "NetCreditNC": "",
    "NetCurrency": "USD",
    "CommissionNC": "",
    "CreationDate": "2018-03-20 21:31:39",
    "ExchangeRate": "",
    "GrossDebitGC": "",
    "PspReference": "",
    "SchemeFeesNC": "",
    "GrossCreditGC": "",
    "GrossCurrency": "",
    "InterchangeNC": "",
    "PaymentMethod": "",
    "CompanyAccount": "companyY",
    "MerchantAccount": "merchantX",
    "MerchantReference": "",
    "PaymentMethodVariant": "",
    "ModificationReference": "messages from merchantX",
    "ModificationMerchantReference": ""
}

Dispute Transaction Report

Each row in Ayden's dispute transaction report is imported in Leapfin as an adyen-dispute-record. The schema of the report can be found in Adyen's documentation here. Leapfin relies on Adyen's webhook to receive notifications and download reports when available.

Sample Data

{
    "Bic": "",
    "Iban": "",
    "IssuerId": "123456",
    "UserName": "system",
    "Reserved4": "",
    "Reserved5": "",
    "ShopperIP": "127.0.0.1",
    "DisputeARN": "12345678901234567890",
    "RecordDate": "2018-09-11 12:28:17",
    "RecordType": "NotificationOfChargeback",
    "ShopperPAN": "3248",
    "AVSResponse": "18",
    "DisputeDate": "2018-09-11 12:28:17",
    "PaymentDate": "2018-08-30 06:26:15",
    "RiskScoring": "1",
    "ShopperName": "David Jim",
    "CBReasonCode": "10.4",
    "CBSchemeCode": "visa",
    "CVC2Response": "1",
    "PspReference": "1234567890123456",
    "ShopperEmail": "",
    "DisputeAmount": "393.51",
    "DisputeReason": "Other Fraud-Card Absent Environment",
    "IssuerCountry": "CZ",
    "NoFReasonCode": "",
    "NoFSchemeCode": "",
    "PaymentAmount": "373.00",
    "PaymentMethod": "visa",
    "RFIReasonCode": "",
    "RFISchemeCode": "",
    "CompanyAccount": "companyY",
    "DisputeEndDate": "2018-09-29 12:28:17",
    "ShopperCountry": "",
    "DisputeCurrency": "USD",
    "MerchantAccount": "merchantX",
    "PaymentCurrency": "USD",
    "ShopperReference": "",
    "MerchantReference": "1234-123-1234567",
    "RecordDateTimeZone": "EDT",
    "ShopperInteraction": "Ecommerce",
    "3DDirectoryResponse": "",
    "DisputeAutoDefended": "",
    "DisputeDateTimeZone": "EDT",
    "DisputePSPReference": "9876543210654321",
    "PaymentDateTimeZone": "EDT",
    "DisputeEndDateTimeZone": "EDT",
    "3DAuthenticationResponse": ""
}

Mapping Logics

adyen-accounting-record

Adyen creates a pspReference( link) for each transaction. As the transaction going through difference stages, e.g. Authorised, Settled, Refunded, etc, a series of adyen-accounting-record is generated. Adyen uses RecordType(link) to indicate the stage of the transaction, and BookingDate to indicate the timestamp of the stage.

When mapping data, Leapfin creates a single Payment or Refund record for each transaction (i.e. PspReference). The series of adyen-accounting-record across different RecordType are consolidated based on timestamps (i.e. BookingDate). Updated information from new records will replace that from previous records. The latest transaction stage is display on Leapfin platform.

🚧

Booking Date Limitation

In very rare cases, the stage of transaction changes multiple times within 1 second. Two or more adyen-accounting-record are created by Adyen with different RecordType (and other field values) but the exact same BookingDate.

As a results, Leapfin cannot determine the latest stage of the transaction. The records will be processed by Leapfin in the order of time received, which may not match with the latest status shown in Adyen.

Create a Payment

If adyen-accounting-record.RecordType is one of the following, a LeapfinPayment record will be created.

• Authorised, AuthorisedPending, Cancelled, CaptureFailed, Error, Expired, Received, Refused, Retried, SentForSettle, Settled, SettledBulk, SettledExternally, SettledExternallyWithInfo, SettledInInstallments, SettledInistallmentSuspendInstallment, SuspendInstallment, AdvancedInstallment, AdvancedInstallmentCancelled, OpenInstallment, CloseInstallment

Create a Refund

If adyen-accounting-record.RecordType is one of the following, a LeapfinRefund record will be created.

• RefundAuthorised, Refunded, RefundedBulk, RefundedExternally, RefundedExternallyWithInfo, RefundFailed, RefundedInInstallments, RefundedInstallment, RefundedReversed, SentForRefund

adyen-settlement-record

Adyen creates an adyen-settlement-record when there is a change to the balance of merchant's fund. The records are categorized into difference types (see full list of types).

Some Type values are associated with individual transactions. For example, when a transaction is "Settled" or "Refund", it will impact the balance of merchant's fund. Such adyen-settlement-record contains a non-empty PspReference value, which can be tied to adyen-accounting-record.

Other Type values are associated with batch actions. For example, when a batch of transactions are paid out to merchant, a single "MerchantPayout" record is created. Such adyen-settlement-record have empty PspReference value and cannot be tied to adyen-accounting-record directly. Instead, BatchNumber must be used to as the intermediary to identify the list of transactions (i.e. PspReference values) included in the batch action.

When mapping data, Leapfin extracts only payout and fee information from adyen-settlement-record. This is because individual transaction information is already covered by the mapping of adyen-accounting-record. Compared to adyen-settlement-record, adyen-accounting-record contains more detailed information for each transaction.

Based on the Type value, Leapfin creates either Settlement record or Fee record.

Create a Settlement

If adyen-settlement-record.Type is "MerchantPayout", a LeapfinSettlement record will be created.

Create a Fee

If adyen-settlement-record.Type is one of the following, a LeapfinFee record will be created.

• "Fee", "MiscCosts", "PaymentCost", “InvoiceDeduction”

In addition, for adyen-settlement-record with any Type value, a LeapfinFee record is created for each of the following fields as long as the value is non-zero.

• CommissionNC, MarkupNC, SchemeFeesNC, InterchangeNC

adyen-dispute-record

Similar to adyen-accounting-record, a series of adyen-dispute-record is created as a transaction going through difference stage of the dispute (or chargeback) process. Adyen uses DisputePspREference to uniquely identify a dispute transaction and RecordType to indicate the stage of the dispute.

When mapping data, Leapfin creates a single dispute record for each dispute transaction (i.e. DisputePspREference). The series of adyen-dispute-record across different RecordType are consolidated based on timestamps (i.e. RecordDate). Information from the latest record is display on Leapfin platform.

🚧

Handle SecondChargeback

Though Adyen handles second chargeback - another chargeback initiated after the merchant won the original chargeback - as a specific stage (i.e. RecordType) of the original chargeback, Leapfin considers them as separate dispute records. A different dispute record will be created by Leapfin when "SecondChargeback" occurs.

Create a Dispute

If adyen-dispute-record.RecordType is not "RequestForInformation" or "InformationSupplied", a LeapfinDispute will be created.

NOTE: Leapfin does not create a dispute record until it is formally initiated.