Map payment methods

Provide your SMBs with the ability to choose how to make payments

Overview

Your SMB customers may have multiple bank accounts they can use to pay for a bill. In your application, you should enable them to select the account the payment should originate from.

Retrieve the list of existing bank accounts from the SMB's accounting platform and display the available mapping options to them in a UI, or allow them to create a new account when needed.

We have highlighted this alternative sequence of steps in our detailed process diagram below.

Detailed process diagram

If your platform supports multiple payment methods that can be mapped to a separate account, store the mapping of the relevant accountId - you will need this to create the bill payment later.

Foreign currency payments

Foreign currency payments

If you facilitate payments in a foreign currency, you should convert the payment to the currency of the account or create a new account in that currency.

Use the Get create account model endpoint to view the list of the company's currently enabled currencies. It can return:

• Single value: the account's base currency in platforms that only support the base currency
• Multiple values: several currencies enabled by the SMB user in their accounting platform
• No values: empty array for platforms where any and all currencies can be selected

Retrieve bank accounts

If your SMB customer is making payments from a pre-existing bank account, retrieve a list of their accounts and allow them to map payment methods against each one. Use the List accounts endpoint and filter by isBankAccount=true to return a list of valid bank accounts.

TypeScript

const accountsListResponse = await payablesClient.accounts.list({
    companyId: companyId,
    query: 'isBankAccount=true'
  });

Python

accounts_list_request = operations.ListAccountsRequest(
    company_id=company_id,
    query='isBankAccount=true'
)

accounts_list_response = payables_client.accounts.list(accounts_list_request)

C#

var accountsListResponse = await payablesClient.Accounts.ListAsync(new ListAccountsRequest() {
    CompanyId = companyId,
    Query = "isBankAccount=true"
});

Go

ctx := context.Background()
accountsListResponse, err := payablesClient.Accounts.List(ctx, operations.ListAccountsRequest{
    CompanyID: companyID,
    Query: "isBankAccount=true"
})

Create new account

If the SMB customer plans to make payments from a new payment method or account that you provide, a new account must be created in their accounting software. The account will contain their transactions, making the SMB's payment reconciliation workflows easier.

For Xero, QuickBooks Online, and Oracle NetSuite, use the Create bank account endpoint.

TypeScript

const accountCreateResponse = await payablesClient.accounts.create({
    account: {
        accountName: "BillPay Debit Account",
        accountType: AccountType.Debit,
        accountNumber: "80088008",
        currency: "USD",
        balance: 0,
        availableBalance: 0,
    },
    companyId: companyId,
    connectionId: connectionId
  });

Python

account_create_request = operations.CreateAccountsRequest(
    account=shared.Account(
        account_name="BillPay Debit Account",
        account_type=shared.AccountType.DEBIT,
        account_number="80088008",
        currency="USD",
        balance=0,
        available_balance=0,
    )
    company_id=company_id,
    connection_id=connection_id
)

account_create_response = payables_client.accounts.create(account_create_request)

C#

var accountCreateResponse = await payablesClient.Accounts.CreateAsync(new CreateAccountRequest() {
    Account=new Account(){
        AccountName = "BillPay Debit Account",
        AccountType = AccountType.Debit,
        AccountNumber = "80088008",
        Currency = "USD",
        Balance = 0,
        AvailableBalance = 0,
    }
    CompanyId = companyId,
    ConnectionId = connectionId
});

Go

ctx := context.Background()
accountsResponse, err := payablesClient.Accounts.Create(ctx, operations.CreateAccountRequest{
    Account: &shared.Account{
        AccountName: syncforpayables.String("BillPay Debit Account"),
        AccountType: AccountType.Debit,
        AccountNumber: "80088008",
        Currency: syncforpayables.String("USD"),
        Balance: 0,
        AvailableBalance: 0,
    },
    CompanyID: companyID,
    ConnectionID: connectionID,
})

Note that Xero does not support creating credit accounts.

For Sage Intacct, use the Create account endpoint to reflect that account in the customer's accounting software.

TypeScript

const accountCreateResponse = await payablesClient.accounts.create({
    accountPrototype: {
    name: "BillPay Debit Account"
        fullyQualifiedName: "BillPay Debit Account",
    fullyQualifiedCategory: "Asset.Current",
        nominalCode: "610",
        currency: "USD",
    status: AccountStatus.Active,
    type: AccountType.Asset,
        currentBalance: 0,
    },
  companyId: companyId,
    connectionId: connectionId
  });

Python

account_create_request = operations.CreateAccountRequest(
    account_prototype=shared.AccountPrototype(
        name='BillPay Debit Account',
        fully_qualified_name='BillPay Debit Account',
    fully_qualified_category='Asset.Current',
    nominal_code='610',
        currency='USD',
    status=shared.AccountStatus.ACTIVE,
    type=shared.AccountType.ASSET,
        current_balance=0,
    ),
  company_id=company_id,
    connection_id=connection_id
)

account_create_response = payables_client.accounts.create(account_create_request)

C#

var accountCreateResponse = await payablesClient.Accounts.CreateAsync(new CreateAccountRequest() {
  AccountPrototype = new AccountPrototype(){
    Name = "BillPay Debit Account",
        FullyQualifiedName = "BillPay Debit Account",
    FullyQualifiedCategory = "Asset.Current",
    NominalCode = "610",
        Currency = "USD",
    Status = AccountStatus.Active,
    Type = AccountType.Asset,
        CurrentBalance = 0,
    },
  CompanyId = companyId,
    ConnectionId = connectionId
});

Go

ctx := context.Background()
accountCreateResponse, err := payablesClient.Accounts.Create(ctx, operations.CreateAccountRequest{
    AccountPrototype: &shared.AccountPrototype{
    Name: syncforpayables.String("BillPay Debit Account"),
        FullyQualifiedName: syncforpayables.String("BillPay Debit Account"),
    FullyQualifiedCategory: syncforpayables.String("Asset.Current"),
    NominalCode: syncforpayables.String("610"),
        Currency: syncforpayables.String("USD"),
    Status: shared.AccountStatusActive.ToPointer(),
    Type: shared.AccountTypeAsset.ToPointer(),
        CurrentBalance: 0
    },
    CompanyID: companyID,
    ConnectionID: connectionID,
})

You can also use the Get create bank account model or Get create account model endpoints first to check integration-specific requirements for account creation, or read more about creating data with Codat.

Pre-pay account

Create a bank account with an accountType of Debit if you need to represent the following payment methods:

• Automated Clearing House (ACH) or Real-Time Payments (RTP) networks
• Cheque/check payments
• Electronic bank transfer
• BACS (Bankers' Automated Clearing System)

Credit account

Create a bank account with an accountType of Credit if you are providing a credit facility for the payment, such as:

• Commercial/business credit card
• BNPL (Buy Now, Pay Later)

---

Read next

• Reflect and reconcile bill payments in the SMB's accounting software