Payments Module API Endpoint

The Payment Module API provides support for the automated scheduling of payments for new or existing transaction agreements.

The process consists of three steps:

Scheduling of new payments (creation of agreement on the fly if necessary)
Monitoring payments status
Handling of late payment rejections (for direct debit payments)

When scheduling new payments, an existing transaction agreement reference can be used to associate the payment with that agreement. For new agreements, the details of the agreement source and customer details must be provided.

After the scheduled payments are processed, payments will be generated and debited from the source. The status of each payment can be tracked by calling the API with the unique payment reference. Payments can take up to 48 business hours to be fully processed.

Even after a payment has been marked as completed there is a chance the source (usually the financial institution) will revert the payment and modify its status. In order to keep a check on this possibility, it is important that a check is made for late rejections for a period of time no less than 7 days. Again this can be performed by calling the API with the unique references for the payments.

An example of a simple workflow:

Customer accesses you platform to purchase a product or subscribe to a service from one of your merchants

Customer executes purchase and will pay in 12 payments of $100

Your platform calls Biz Core to create an agreement passing all the customer details and customer payment method details. Receives an agreement identifier.

Your platform calls Biz Core to schedule payments in this agreement. Receives scheduled transactions identifiers.

Biz Core updates your platform every time there is a change to the status of one of these scheduled transactions and your platform updates the customer records accordingly.

Generically, we support as part of our Payments module:

Creation of payment agreements between the customers and the merchants (ie: Customer agrees to pay $x per week/fortnight/month from his bank account/card to the subscriber and the payment processed by us)

Scheduling of once-off/recurring transactions in the future for those agreements

Execution of single transactions on-the-fly from bank account/card

Synchronization of transaction statuses for transactions with deferred outcome (ex: debits from bank accounts) via pull (api call) or push (web hooks) techniques

Authentication is based on HAWK id/key pair and we provide examples of implementation.

Our API is HTTPS based and uses typical HTTP requests with json payloads and responses.

Scheduling of new payments

API endpoint: api/v1/payments/transactions/create-direct-debit-scheduled-transactions

Verb: POST

Request:

public class CreateDirectDebitScheduledTransactionsRequest
{
    public Guid SubscriptionId { get; set; }
    public List<ApiScheduledTransactionsTransactionAgreement> TransactionsAgreements { get; set; } = new List<ApiScheduledTransactionsTransactionAgreement>();
}

public class ApiScheduledTransactionsTransactionAgreement
{
    /// <summary>
    /// Object containing the details of the new transaction agreement to be created
    /// </summary>
    public ApiDirectDebitTransactionAgreement TransactionAgreement { get; set; }
    /// <summary>
    /// Collection of transactions to scheduled for this agreement
    /// </summary>
    public List<NewApiScheduledTransaction> TransactionsToSchedule { get; set; } = new List<NewApiScheduledTransaction>();
}

public class ApiDirectDebitTransactionAgreement
{
    /// <summary>
    /// Details of the bank account that will be used as source of the debit
    /// </summary>
    public ApiDirectDebitTransactionSource TransactionSource { get; set; }
    /// <summary>
    /// The unique reference for an existing transaction agreement
    /// </summary>
    public string Reference { get; set; }
}

public class ApiDirectDebitTransactionSource
{
    public string Institution { get; set; }
    /// <summary>
    /// Account holder value as per the details on the bank account
    /// </summary>
    public string AccountHolder { get; set; }
    /// <summary>
    /// Unique BSB value for the institution (Australian Banks only)
    /// </summary>
    public string BSB { get; set; }
    /// <summary>
    /// Account number value as per the details on the bank account
    /// </summary>
    public string AccountNumber { get; set; }
    /// <summary>
    /// Name of the account within the holder's portfolio in the bank
    /// ex: Savings, Cheque...
    /// </summary>
    public string AccountName { get; set; }
    /// <summary>
    /// Name of the contact for this account
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    /// An email contact for the account holder
    /// </summary>
    public string EmailAddress { get; set; }
    /// <summary>
    /// A phone contact for the account holder
    /// </summary>
    public string PhoneNumber { get; set; }
    /// <summary>
    /// The phone type. Possible values:
    /// 
    /// 0 - Residential
    /// 1 - Mobile
    /// 2 - Business
    /// 
    /// </summary>
    public PhoneTypeEnum? PhoneTypeEnum { get; set; }
}

public enum PhoneTypeEnum
{
    [PhoneTypeMetadata(Name = "Residential")]
    Residential,
    [PhoneTypeMetadata(Name = "Mobile")]
    Mobile,
    [PhoneTypeMetadata(Name = "Business")]
    Business,
}

public class PhoneTypeMetadata : Attribute
{
    public string Name { get; set; }
}

public class NewApiScheduledTransaction
{
    /// <summary>
    /// The date the transaction will be executed
    /// </summary>
    public DateTimeOffset ScheduledDate { get; set; } 
    /// <summary>
    /// Transaction amount
    /// </summary>
    public decimal Amount { get; set; }
    /// <summary>
    /// Unique reference for this single transaction.
    /// This value can be used to check the current status of the scheduled transactions
    /// </summary>
    public string Reference { get; set; } 
}

Response:

public class Response<T>
{
    public int StatusCode { get; set; }
    public T Result { get; set; }
}

public class CreateDirectDebitScheduledTransactionsResponse : Response<CreateDirectDebitScheduledTransactionsResponseDTO>
{
}

public class CreateDirectDebitScheduledTransactionsResponseDTO
{
    public ApiDirectDebitScheduledTransactions ScheduledTransactions { get; set; }
}

public class ApiDirectDebitScheduledTransactions
{
    public bool Success { get; set; }
    public List<string> Errors { get; set; }
    public List<ApiScheduledTransaction> ScheduledTransactions { get; set; }
}

public class ApiScheduledTransaction
{
    public bool Success { get; set; }
    public List<string> Errors { get; set; }
    public string TransactionReference { get; set; }
    public string TransactionAgreementReference { get; set; }
    public string TransactionSourceType { get; set; }
    public string TransactionSourceReference { get; set; }
    public DateTimeOffset? TransactionDate { get; set; }
    public decimal? Amount { get; set; }
}

Payment status updates

API endpoint: api/v1/payments/transaction-statuses/get-transactions-statuses

Verb: POST

Request:

public class GetTransactionsCurrentStatusRequest
{
    public Guid SubscriptionId { get; set; }
    public List<string> ScheduledTransactionReferences { get; set; } = new List<string>();
}

Response:

public class Response<T>
{
    public int StatusCode { get; set; }
    public T Result { get; set; }
}

public class GetTransactionsCurrentStatusResponse : Response<GetTransactionsCurrentStatusResponseDTO>
{
}

public class GetTransactionsCurrentStatusResponseDTO
{
    public ScheduledTransactionsStatuses TransactionsCurrentStatuses { get; set; }
}

public class ScheduledTransactionsStatuses
{
    public ICollection<ScheduledTransactionStatus> Statuses { get; set; }
}

public class ScheduledTransactionStatus
{
    public string TransactionAgreementReference { get; set; }
    public string TransactionReference { get; set; }
    public DateTimeOffset TransactionDate { get; set; }
    public DateTimeOffset? ClearedDate { get; set; }
    public TransactionStatusEnum TransactionStatus { get; set; }
    public DateTimeOffset TransactionStatusDate { get; set; }
    public string TransactionAgreementStatus { get; set; }
}

public enum TransactionStatusEnum
{
    [TransactionStatusMetadata(Name = "Pending")]
    Pending = 1,
    [TransactionStatusMetadata(Name = "Processing")]
    Processing,
    [TransactionStatusMetadata(Name = "Accepted")]
    Accepted,
    [TransactionStatusMetadata(Name = "Declined")]
    Declined,
    [TransactionStatusMetadata(Name = "Disputed")]
    Disputed,
    [TransactionStatusMetadata(Name = "Cancelled")]
    Cancelled,
    [TransactionStatusMetadata(Name = "Complete")]
    Complete,
    [TransactionStatusMetadata(Name = "Refunded Via Claim")]
    RefundedViaClaim,
    [TransactionStatusMetadata(Name = "Late Rejection")]
    LateRejection,
}

public class TransactionStatusMetadata : Attribute
{
    public string Name { get; set; }
}

Late rejections

API endpoint: api/v1/payments/transaction-statuses/get-late-rejections

Verb: POST

Request:

public class GetLateRejectionsRequest
{
    public Guid SubscriptionId { get; set; }
    public DateTimeOffset DateFromInclusive { get; set; }
    public DateTimeOffset? DateTo { get; set; }
}

Response:

public class Response<T>
{
    public int StatusCode { get; set; }
    public T Result { get; set; }
}

public class GetLateRejectionsResponse : Response<GetLateRejectionsResponseDTO>
{
}

public class GetLateRejectionsResponseDTO
{
    public ScheduledTransactionsStatuses LateRejections { get; set; }
}

public class ScheduledTransactionStatus
{
    public string TransactionAgreementReference { get; set; }
    public string TransactionReference { get; set; }
    public DateTimeOffset TransactionDate { get; set; }
    public DateTimeOffset? ClearedDate { get; set; }
    public TransactionStatusEnum TransactionStatus { get; set; }
    public DateTimeOffset TransactionStatusDate { get; set; }
    public string TransactionAgreementStatus { get; set; }
}

public enum TransactionStatusEnum
{
    [TransactionStatusMetadata(Name = "Pending")]
    Pending = 1,
    [TransactionStatusMetadata(Name = "Processing")]
    Processing,
    [TransactionStatusMetadata(Name = "Accepted")]
    Accepted,
    [TransactionStatusMetadata(Name = "Declined")]
    Declined,
    [TransactionStatusMetadata(Name = "Disputed")]
    Disputed,
    [TransactionStatusMetadata(Name = "Cancelled")]
    Cancelled,
    [TransactionStatusMetadata(Name = "Complete")]
    Complete,
    [TransactionStatusMetadata(Name = "Refunded Via Claim")]
    RefundedViaClaim,
    [TransactionStatusMetadata(Name = "Late Rejection")]
    LateRejection,
}

public class TransactionStatusMetadata : Attribute
{
    public string Name { get; set; }
}

Authorisation:

Using HAWK authentication with the Key ID and API Key provided to you. See postman collection authentication.

Workflow:

Create a transaction agreement:

The first step is to create a transaction agreement between your customer and yourself with Biz Core as the provider that will execute the debits.

In order to do this you need to execute a call to api/v2/payments/transactions/create-new-agreement-without-source

The payload for this method includes:

SubscriptionId: your Subscription Id (provided to you)

ExternalReference: (optional) you can provide a reference/id from your own system for this agreement. This will be stored in Biz Core and visible on the agreement.

Customer: object containing the customer details (name, date of birth, email contact, phone contact)

SourceUpdatedCallbackUrl: (optional) if set, this url will be called when the user has provided the payment method details

SourceUpdatedRedirectUrl: (optional) if set, the payment selection page will be redirected to this url, once the user has provided the payment method details

{
    "subscriptionId": "{{SubscriptionId}}",
    "externalReference": "MY-REF-XXXX",
    "customer": {
        "externalReference": "MY-CUST-XXXX",
        "entityType": 0,
        "person": {
            "givenName": "string",
            "familyName": "string",
            "dateOfBirth": "1960-01-01T00:00:00",
            "emailContacts": [
                {
                    "emailAddress": "unit.test@fsoft.net.au"
                }
            ],
            "phoneContacts": [
                {
                    "phoneType": 1,
                    "phoneNumber": "0400000000"
                }
            ]
        }
    },
    "sourceUpdatedCallbackUrl": null,
    "sourceUpdatedRedirectUrl": null
}

{
    "result": {
        "agreement": {
            "transactionAgreementId": "4f306af7-dbe0-4c52-8f93-13cf211e086e",
            "transactionAgreementReference": "BCP025859A",
            "customerId": "30756c89-1f77-4afc-a550-9e8e0f137eb2",
            "customerReference": "BCC048617A",
            "sourceCreationUrl": "https%3A%2F%2Fbizcore-fe.bizcorebeta.com.au%2F(agreement%3Anew-source%3Bagreement%3D4f306af7-dbe0-4c52-8f93-13cf211e086e%3BapiKeyId%3D00926de8-1b17-4ceb-bab0-715cc18d3aae%3BapiKey%3D8ecf3b07-619e-4293-9eff-6fdfd245221f%3BcallbackUrl%3D%3BredirectUrl%3D)"
        }
    },
    "statusCode": 200
}

The response includes:

TransactionAgreementId: unique identifier for this agreement in Biz Core. This should be stored in your system and can be used to schedule and execute transactions for example.

TransactionAgreementReference: unique reference for this agreement in Biz Core. This should be stored in your system.

CustomerId: unique identifier for this customer in Biz Core. This should be stored in your system and can be used to create additional agreements for this customer.

SourceCreationUrl: this url can be sent to the customer, directly redirected to or embedded in your own page via an iframe for the customer to select and provide payment details.

Customer provides payment details using sourceCreationUrl

From the example above: https://bizcore-fe.bizcorebeta.com.au/(agreement:new-source;agreement=4f306af7-dbe0-4c52-8f93-13cf211e086e;apiKeyId=00926de8-1b17-4ceb-bab0-715cc18d3aae;apiKey=8ecf3b07-619e-4293-9eff-6fdfd245221f;callbackUrl=;redirectUrl=)

After submission you now have your first authorised agreement in Biz Core:

By opening up the record you can see your customer details and agreement summary:

You can also confirm the payment details:

Schedule transactions

You can schedule as many transactions as you need in a single api call and they can have any combination of values

In order to do this you need to execute a call to /api/v2/payments/transactions/schedule-transactions

In the example below I schedule a single payment for $100 (a deposit) and then weekly payments of $20 starting on the 4th of July and finishing on the 26th of December

Example payload:

{
    "subscriptionId": "{{SubscriptionId}}",
    "transactionAgreements": [
        {
            "transactionAgreementId": "4f306af7-dbe0-4c52-8f93-13cf211e086e",
            "scheduledTransactions": [
                {
                    "scheduledTransactionType": 0,
                    "scheduledDate": "2022-06-27T00:00:00+10:00",
                    "amount": 100,
                    "reference": "MY-UNIQUE-REF-DEPOSIT-XXXXX"
                },
                {
                    "scheduledTransactionType": 1,
                    "startDate": "2022-07-04T00:00:00+10:00",
                    "endDate": "2022-12-26T00:00:00+10:00",
                    "frequency": 1,
                    "amount": 20
                }
            ]
        }
    ]
}

Example response:

{
    "result": {
        "scheduledTransactions": {
            "subscriptionId": "b0ec457c-7970-499c-8aa1-a6a045d01da8",
            "transactionAgreements": [
                {
                    "transactionAgreementId": "4f306af7-dbe0-4c52-8f93-13cf211e086e",
                    "reference": null,
                    "status": null,
                    "customer": null,
                    "thirdParties": null,
                    "scheduledTransactions": [
                        {
                            "scheduledTransactionType": 0,
                            "scheduledDate": "2022-06-27T00:00:00+10:00",
                            "startDate": null,
                            "endDate": null,
                            "frequency": null,
                            "amount": 100.0,
                            "reference": "MY-UNIQUE-REF-DEPOSIT-XXXXX",
                            "scheduledTransactionId": "8b919100-0b70-4a08-9704-bdae02950529"
                        },
                        {
                            "scheduledTransactionType": 1,
                            "scheduledDate": null,
                            "startDate": "2022-07-04T00:00:00+10:00",
                            "endDate": "2022-12-26T00:00:00+10:00",
                            "frequency": 1,
                            "amount": 20.0,
                            "reference": null,
                            "scheduledTransactionId": "d6cfa397-d79d-4ef2-a98b-d1fad7626a97"
                        }
                    ],
                    "clearExistingScheduledTransactions": false
                }
            ]
        }
    },
    "statusCode": 200
}

You can now see the scheduled transactions on the agreement:

All of the transactions except the first are linked to a recurring scheduled transaction:

At this point your agreement is set up and we will execute those transactions on the scheduled date.

Check progress

You can check the progress of any scheduled transactions by using /api/v1/payments/transaction-statuses/get-transactions-statuses and passing the list of scheduled transaction references you used when creating them.

Note that this will only return results once the scheduled transactions are processed (after the scheduled date).

Alternatively you can setup a web hook to call your own api whenever a transaction changes status:

(Alternative) Execute transactions ad-hoc

Most of our partners and subscribers prefer to handle the scheduling on their side to prevent the constant need to synchronize payment plan changes between the applications and risk them becoming out of sync.

In this case you can skip the scheduling and status checking steps above and simply use /api/v2/payments/transactions/execute-transaction. This is our recommended method.

Example request:

{
    "transactionAgreementId": "4f306af7-dbe0-4c52-8f93-13cf211e086e",
    "amount": 50,
    "externalReference": "MY-UNIQUE-REF-AD-HOC-XXXXX"
}

Example response:

{
    "result": {
        "transaction": {
            "transactionId": "06641949-997e-44f9-9908-802812b791c6",
            "transactionAgreementId": "4f306af7-dbe0-4c52-8f93-13cf211e086e",
            "transactionSourceTypeId": 0,
            "transactionSourceType": "Bank Account",
            "transactionStatusId": 1,
            "transactionStatus": "Pending",
            "amount": 50.00,
            "transactionReference": "MY-UNIQUE-REF-AD-HOC-XXXXX",
            "transactionDate": "2022-06-24T00:00:00+10:00",
            "processDate": null,
            "clearedDate": null,
            "feesAmount": 1.0,
            "totalAmount": 50.00,
            "declineCode": null,
            "declineMessage": null,
            "code": null,
            "type": null
        }
    },
    "statusCode": 200
}

And you can see your transaction on the agreement:

Additional API's :

To send the email to the customer for signing documents for bank authorization through API? Also how to know if a customer has signed the authorization link? You can call API endpoint is api/v1/payments/transaction-agreements/send-transaction-agreement-for-signature. POST with 2 params (source is optional): transactionAgreementId and transactionSourceId

Example Request URL:

https://bizcore-api.bizcorebeta.com.au/api/v1/payments/transaction-agreements/send-transaction-agreement-for-signature?transactionAgreementId=a7647b63-97d4-4b0b-bdf7-4cb5895ca43a

Response body: {"statusCode": 200 }

To stop/delete a transaction which is scheduled/processed:
Scheduled transactions can be deleted but not the processed transactions. Below are the three API options to delete the scheduled transactions:
/api/v1/payments/transactions/delete-scheduled-transaction
/api/v1/payments/transactions/delete-recurring-scheduled-transaction
/api/v1/payments/transactions/delete-all-scheduled-transactions

Example Request URL:

https://bizcore-api.bizcorebeta.com.au/api/v1/payments/transactions/delete-all-scheduled-transactions?transactionAgreement

You have now created the agreement. Let's update the source with the bank details:

update-agreement-source-direct-debit

https://portal.bizcore.com.au/api/v2/payments/transactions/update-agreement-source-direct-debit

Request:

{
    "TransactionAgreementId": "81903f9c-9337-4d8a-8c04-8ac8d54449d5",
    "TransactionSourceType": 0,
    "NewTransactionSource": {
        "TransactionAgreementId": "81903f9c-9337-4d8a-8c04-8ac8d54449d5",
        "Institution": "Test Bank",
        "AccountHolder": "Unit Test",
        "AccountNumber": "0000000",
        "AccountName": "Cheque",
        "BSB": "000000",
        "Name": "Test"
    }
}

In order to update the transaction source at a later date you could actually use the same URL you received in step 1. We have still created an API endpoint to retrieve that URL for your convenience:

https://bizcore-api.bizcorebeta.com.au/api/v2/payments/transactions/update-agreement-source

Request:

{
    "TransactionAgreementId": "55aba0ac-5dac-4f50-90ff-fbded77712b9",
    "SourceUpdatedCallbackUrl": null,
    "SourceUpdatedRedirectUrl": "https://www.google.com.au"
}

Response:

{
    "result": {
        "sourceCreationUrl": "https%3A%2F%2Fbizcore-fe.bizcorebeta.com.au%2F(agreement%3Anew-source%3Bagreement%3D55aba0ac-5dac-4f50-90ff-fbded77712b9%3BapiKeyId%3D1d9f8028-d844-4d13-8510-af5527b7913d%3BapiKey%3Ddac4e697-113f-4ca4-9286-eb699f81cfe0%3BcallbackUrl%3D%3BredirectUrl%3Dhttps%3A%2F%2Fwww.google.com.au)"
    },
    "statusCode": 200
}

You can also use the mechanisms described in step 4 to get updates on progress. That's it! These are the basic steps for integration.

We have full flexibility regarding the payment scheduling within an agreement. We support:

Any number of individual scheduled transactions (unique date and amount)

Any number of recurring scheduled transactions (based on start date, end date (optional), frequency and amount)

Any combination of those

In your case, after creating the agreement, you can call our api to schedule:

Single scheduled transaction for the deposit

Single scheduled transaction for the catch-up payment

Multiple single scheduled transactions or a recurring transaction for the ongoing payments

How will your platform handle the payment schedule?

Option 1: Internally, by keeping the payment schedule logic and calling Biz Core "just-in-time" to execute the scheduled transactions

Option 2: Let Biz Core handle it, by scheduling all payments when creating the agreement

We find that most integrators end up with option 1 as although it looks harder to implement, it becomes easier to manage during the life of the agreement. Ex:

Customer wants to change the payment frequency or the day of week the payment is taken

Customer misses a payment or a payment is declined

Customer makes an additional payment

On all those scenarios, you'd have to call Biz Core to delete existing and create new scheduled payments as part of handling those events. In short you have to keep your platform and Biz Core in sync if you decide to go with option 2.