Get Sandbox Access

Paybase Developer Centre

OverviewAPI GuidesGetting StartedRecipesGig Economy PlatformsSharing Economy PlatformsMarketplacesBlockchain BusinessesEscrowSandboxRolesRulesDue DiligenceCustomersAccountsBank AccountsCardsTransactionsIntroductionInboundGetting money into the systemTransaction ReferenceAccount ReferenceInternalOutboundEscrowSplit PaymentsRefundsStrong Customer Authentication3D Secure AuthenticationIntroductionCreate a cardCreate a transactionDocument UploadStatementsWebhooksErrorsPQLAPI ReferenceAccountCreate an accountRetrieve an accountTransition account statusList all accountsAnnotate an accountDelete annotation from an accountTag an accountDelete tag from an accountBank AccountCreate a bank accountRetrieve a bank accountUpdate a bank accountTransition bank account statusList all bank accountsAnnotate a bank accountDelete annotation from a bank accountTag a bank accountDelete tag from a bank accountCardCreate a cardRetrieve a cardUpdate a cardTransition card statusList all cardsAnnotate a cardDelete annotation from a cardTag a cardDelete tag from a cardCardholderCreate a cardholderRetrieve a cardholderUpdate a cardholderTransition cardholder statusList all cardholdersAnnotate a cardholderDelete annotation from a cardholderTag a cardholderDelete tag from a cardholderCreate an authentication tokenCheckCreate a checkCustomerIndividual CustomerCreate a customerRetrieve a customerUpdate a customerSole TraderCreate a customerRetrieve a customerUpdate a customerOrganisationCreate a CustomerRetrieve a CustomerUpdate a CustomerIncorporated BusinessCreate a customerRetrieve a customerUpdate a customerBusiness PersonAdd a business personRetrieve a business personUpdate a business personDelete a business personRetrieve a customerTransition state of a customerList all customersAnnotate a customerDelete annotation from a customerTag a customerRemove tag from a customerCreate an authentication tokenTouch a customerDocumentCreate a documentRetrieve a documentList Document TypesReferenceRetrieve a referenceStatementRetrieve a statementStatusRetrieve API statusTransactionCreate inbound transactionCreate internal transactionCreate outbound transactionRetrieve a transactionTransition transaction statusList all transactionsAnnotate a transactionDelete annotation from a transactionTag a transactionDelete tag from a transaction
API version: ba085a6

Accounts

An Account on the Paybase platform is an entity that holds balances for Customers as e-money under the regulatory licence of Paybase and is key to creating and managing Transactions on your platform. An account has to be linked to a Customer through an ownerID. Accounts are used for several purposes:

  • Receive funds via an Inbound Card payment, Bank Transfer or from another Account
  • Make an Internal Transfer to another Account
  • Withdraw funds to an external Bank Account

Depending on your payment flows, you will be required to create an Account for some or all the participants on your platform. You will be able to specify the currencyISO in which you want to create an Account. Note that Paybase currently only supports GBP and will start supporting EUR in the near future.

Account States

An Account can have the following states:

  • ENABLED - The state into which an Account goes when it is first created. An Enabled Account is ready to transact. Note that while an Account might be enabled, the Customer to which it is linked must have passed the necessary verification in order to start transacting.
  • DISABLED - The Account is temporarily Disabled.
  • CLOSED - The Account is permanently Closed and cannot be Enabled again.

Creating an Account

Use the accounts endpoint to create a new Account and associate it with a Customer by providing their ID in the ownerID attribute.

1
2
3
4
5
6
7
8
9
10
11
12
import { v1 } from '@paybase/client';

const client = v1('<- API Key ->', { sandbox: true });

const { accessToken } = await client.createCustomerAuthenticationToken({
  id: "customer/82c6fb26-8027-454a-8451-ae37c0f9d72c"
});

const result = await client.createAccount({
  ownerId: "customer/82c6fb26-8027-454a-8451-ae37c0f9d72c",
  currencyISO: "GBP"
}, { apiKey: accessToken });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import json
import requests

requests.post(
  "https://api-json.sandbox.paybase.io/v1/accounts",
  data = json.dumps({
    "ownerId": "customer/82c6fb26-8027-454a-8451-ae37c0f9d72c",
    "currencyISO": "GBP"
  }),
  headers = {
    "Content-Type": "application/json",
    "X-Token": "<X-Token goes here>"
  }
).json()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$client = new \GuzzleHttp\Client();
$client->request(
  "post",
  "https://api-json.sandbox.paybase.io/v1/accounts",
  [
    "body" => "{
      \"ownerId\": \"customer/82c6fb26-8027-454a-8451-ae37c0f9d72c\",
      \"currencyISO\": \"GBP\"
    }",
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
5
6
7
8
curl -X POST \
"https://api-json.sandbox.paybase.io/v1/accounts"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \
  -d '{
    "ownerId": "customer/82c6fb26-8027-454a-8451-ae37c0f9d72c",
    "currencyISO": "GBP"
  }'

The response to the API call is the full Account object.

Account Reference

An account reference can be used to deposit funds in an Account from an external bank account. Use the reference endpoint and provide the destination Account ID in the toID parameter to get a reference object containing the bank details to which a transfer will need to be made. The object also contains a reference that will be required with the transfer to help us identify the funds and allocate it to the right account. You will be able to pass on the bank details and the reference to your customers to instruct them to make bank deposits into their account.

1
2
3
4
5
6
7
import { v1 } from '@paybase/client';

const client = v1('<- API Key ->', { sandbox: true });

const result = await client.getReference({
  toId: "account/28958679-e8a8-47a8-967c-f979ae8509a2"
});

1
2
3
4
5
6
7
8
9
10
import json
import requests

requests.get(
  "https://api-json.sandbox.paybase.io/v1/reference/account/28958679-e8a8-47a8-967c-f979ae8509a2Params: toId",
  headers = {
    "Content-Type": "application/json",
    "X-Token": "<X-Token goes here>"
  }
).json()

1
2
3
4
5
6
7
8
9
10
11
$client = new \GuzzleHttp\Client();
$client->request(
  "get",
  "https://api-json.sandbox.paybase.io/v1/reference/account/28958679-e8a8-47a8-967c-f979ae8509a2Params: toId",
  [
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
curl -X GET \
"https://api-json.sandbox.paybase.io/v1/reference/account/28958679-e8a8-47a8-967c-f979ae8509a2Params: toId"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \

Account Balances

The platform operates under an 'optimistic debits, pessimistic credits' methodology. In practice, this means that any transaction which would lower an account's balance on completion will do so in any of the transitory states before. Any transaction which would increase an account's balance will only do so once the transaction has been fully confirmed and reached the EFFECTED state. This ensures that all accounts will have the necessary balance to create and any payments they start to create, and balance will only be given to an account once fully confirmed.

An Account has six different balances, some of which are used to calculate the Available Balance.

  • completeBalance - a sum of the Adjustments made to the Account as part of Transactions which are in a completed state (EFFECTED or ADJUSTED)
  • incompleteCredits - a sum of the positive Adjustments made to the Account as part of Transactions which are in an incomplete state (PENDING, ACCEPTED, PROCESSING, HELD)
  • incompleteDebits - a sum of the negative Adjustments made to the Account as part of Transactions which are in an incomplete state (PENDING, ACCEPTED, PROCESSING, HELD)
  • disputedCredits - a sum of the positive Adjustments made to the Account as part of Transactions which are in a disputed state (DISPUTED)
  • disputedDebits - Fees expected on the account from transactions that have been initiated but not yet completed. Sum of all FEE adjustments on every Transaction that is not (EFFECTED, ADJUSTED)
  • feeDebits - a sum of the negative Adjustments made to the Account as part of Transactions which are in an incomplete state (PENDING, ACCEPTED, PROCESSING, HELD)
  • withheldBalance - a portion of the balance that the end user is restricted from accessing based on the Reserve policy applied to that account. This is applicable only if you accept Card payments.

availableBalance = completeBalance + incompleteDebits + disputedDebits - withheldBalance

Reserves

If you accept card payments, a Reserve will be deposited by you at the beginning of your relationship with Paybase to cover potential Chargebacks and Delayed Settlements.

A higher Reserve amount can also be deposited to facilitate instant payouts to your Customers to cover for the period between a card payment being authorised and settled. This period is typically 3 working days.