API Flows

Before we start, let's define how a flow is defined within Ayoconnect's solutions:

• Flow - a single flow is defined as a combination of APIs. Details of Direct Debit flows are explained below.

Why are flows important in Ayoconnect's Direct Debit solution?

Flows are an important part in the Direct Debit APIs as there are some limitations in the values of the X-External-ID header, whereby all API calls that are part of the same flow must have the same X-External-ID header.

Failing to do so will result in a broken flow, and it may not be possible to resolve any issues raised for that flow.

Flows

There is 4 MAIN FLOWS that you can perform using Ayoconnect's Direct Debit Solution:

Binding Flow

APIs part of this flow:

• Generate B2B Access Token API
• Get OAuth Code API
• Account Binding API

Partners can follow the below steps to perform a Card Binding:

• Generate a B2B token by calling the Generate B2B Access Token API.
• With the newly generated B2B token, generate a unique authCode by calling the Get OAuth Code API.
• Replace the auth_code in the below URL with the value of the authCode field from the previous step: https://sandbox.api.of.ayoconnect.id/dd-card-binding?authCode={auth_code}
• Open the URL and the bank selection screen will open. Follow the steps mentioned in the UI and complete the Card Binding process. After a successful Card Binding, a callback with the account status will be sent to the registered callback URL. In case of any issue during the Card Binding, a callback will be sent and the client is redirected back to the client app for the failure screen.
  • NOTE: the same value used in the authCode field in the URL, will be returned in the X-EXTERNAL-ID field in the callback (partners can use this field to link the callback requests with the accounts bound in the previous step).
• If the callback isn't received, or you want to reconfirm that the account has been properly bound, you can call the Account Binding API with the same authCode used in the previous steps to get the accountToken and other details of the card, which can be directly used for payments.

Payment Flow

APIs part of this flow:

• Generate B2B Access Token API
• Generate B2B2C Customer Authorization Token API
• Direct Debit Payment API
• Verify OTP API (only in case of payments that require OTP)

NOTE: Before you start with this flow, you will need to generate a new value for the X-EXTERNAL-ID header. Don't reuse the same value in different flows.

Partners can follow the below steps to perform a Payment:

• Generate a B2B token by calling the Generate B2B Access Token API.
• Generate a B2B2C token by calling the Generate B2B2C Customer Authorization Token API.
• Use the B2B and B2B2C tokens to generate the request to the Direct Debit Payment API.
• In case of a payment with OTP, a new call to the Verify OTP API will be required.
  • NOTE: Partners shouldn't fail the transaction if the OTP verification is not completed before 3 attempts (the transaction should be marked as failed only after the 3 OTP verification attempts).
  • NOTE: After 3 failed attempts, the account will be blocked and the partners should block the customer for that specific bank (to prevent further requests).
• After a payment, a callback should be received by the partners with the status.
• If the callback isn't received, or you want to reconfirm that the payment has been properly confirmed, you can call the Get the Status of a transaction API with the same X-EXTERNAL-ID used in the previous steps.

Unbinding Flow

APIs part of this flow:

• Generate B2B Access Token API
• Generate B2B2C Customer Authorization Token API
• Account Unbinding API
• Verify OTP API

NOTE: Before you start with this flow, you will need to generate a new value for the X-EXTERNAL-ID header. Don't reuse the same value in different flows.

Partners can follow the below steps to perform the Card Unbinding:

• Generate a B2B token by calling the Generate B2B Access Token API.
• Generate a B2B2C token by calling the Generate B2B2C Customer Authorization Token API.
• Use the B2B and B2B2C tokens to generate the request to the Account Unbinding API.
• In case of a Card Unbinding with OTP, a new call to the Verify OTP API will be required.