Get Sandbox Access

Paybase Developer Centre

OverviewAPI GuidesGetting StartedRecipesGig Economy PlatformsSharing Economy PlatformsMarketplacesBlockchain BusinessesEscrowRolesRulesDue 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: 7c99a7a

Transactions

Transaction types

Paybase offers various types of transaction depending on the nature of product we are supporting. We group each type of transaction as follows:

  • Flow - indicates whether funds are flowing into, out of, or within the Paybase platform.
  • Method - the underlying scheme by which the transaction is being processed.
  • Purpose - the intent of the transaction
FlowMethodPurposeDescription
InboundCardPurchase or DepositInbound Card transactions are used to load funds into an Account in the Paybase system.
OutboundBankAccountWithdrawalOutbound BankAccount transactions are used to withdraw funds from the platform via the UK's Faster Payments payment network.
InternalTransferTransfer or PurchaseInternal Transfer transactions are used to move funds across Accounts within the Paybase system.

Transaction states

Transactions can exist in one of these states: PENDING, ACCEPTED, PROCESSING, HELD, ERRORED, CANCELLED, FAILED, EFFECTED, DISPUTED, ADJUSTED

Typically, a transaction will be created, and once it's passed our rules will progress from PENDING, through ACCEPTED, to PROCESSING. From PROCESSING, a successful transaction will transition to EFFECTED. This is the happy path for a transaction and usually EFFECTED will mark the end of a transaction's lifecycle.

Sometimes a transaction could be DISPUTED. This can happen, for example, when a customer disputes whether a transaction is valid or if it happened at all. Furthermore, a transaction may be fully or partially refunded. In this case, it will transition to ADJUSTED.

The available balance of an Account follows the rule of optimistic debits and pessimistic credits. This means transactions that have not yet been EFFECTED will debit the balance of the sender, but not credit the balance of the receiver. Once they have been EFFECTED, the receiver's available balance is credited accordingly.

PENDING

PENDING is the initial state of a transaction, at this point the transaction will be considered incomplete, it will be deducted from the sender's balance but not added to the receiver's balance. For most use cases the PENDING state is transient, however, when a rule marks a transaction for review it will remain in PENDING. A PENDING transaction can either transition to ACCEPTED or CANCELLED.

ACCEPTED

An ACCEPTED transaction means that the transaction has passed all rules and requirements, the transaction is ready to be processed at this point. Typically, this state is transient as we begin to process transactions immediately. Accepted transactions can be transitioned to CANCELLED or PROCESSING.

PROCESSING

A transaction that is in the PROCESSING state is presently being committed. For transactions internal to Paybase, this state is transient. For transactions that involve banking and card networks, this state will mean we have passed the transaction onto the network for execution and are waiting for confirmation of an outcome. From PROCESSING, a transaction can be transitioned to HELD, ERRORED, FAILED, or EFFECTED.

HELD

The HELD state is used as part of conditional payments and escrow solutions. When in HELD the value of the funds is not available to either party. From HELD the transition can only move to directly EFFECTED, however, the transaction can also be transitioned to ADJUSTED, internally this will go via EFFECTED. The transaction should be transitioned to EFFECTED when the 'conditional payments' scenario went entirely as planned, transitioning to ADJUSTED should be used when a deduction or refund should be involved, in this case you would also need to supply an adjustment amount to describe the amount to be refunded.

ERRORED

If processing of the transaction failed due to a temporary supplier or network failure, the transaction will transition to ERRORED. From ERRORED, the transaction can be retried, it will transition back to ACCEPTED and then PROCESSING. An ERRORED transaction can also be CANCELLED.

CANCELLED

A CANCELLED transaction is in an end state, it will revert any incomplete adjustments and cause the transaction to have no effect on any involved party's balances.

FAILED

If processing of the transaction failed due to a permanent error (e.g. the provided bank account details are invalid), the transaction will transition to FAILED. This is not the same as CANCELLED as FAILED indicates the transaction is invalid. FAILED is an end state and cannot be transitioned out of. It will revert any incomplete adjustments and cause the transaction to have no effect on any involved party's balances.

EFFECTED

The EFFECTED state means the transaction has been processed and taken effect. Incomplete debits and credits will become complete, and the balances of all involved parties will be adjusted accordingly. For most cases, a transaction will stay in this state forever, however, it can be transitioned to DISPUTED or ADJUSTED.

DISPUTED

The DISPUTED state indicates that the transaction is currently under dispute.

ADJUSTED

A transaction should be transitioned to the ADJUSTED state when it has been refunded. It may enter ADJUSTED from DISPUTED as a result of a dispute resolution that requires a full or partial refund. A transaction may also be ADJUSTED from the EFFECTED state. This is preferable when both parties are mutually agreed on the adjustment as it avoids the dispute process.

Transaction refunds

For more on transaction refunds, go here

Next up...