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

Create an inbound transactionPOST/v1/txs/inbound

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

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

const { accessToken } = await client.createCustomerAuthenticationToken({
  id: "<- Sending Customer ID ->"
});

const result = await client.createInboundTransaction({
  accountId: "account/b98774fc-3c41-43bc-bd03-13e327dcfbbb",
  amount: "500",
  method: "bankAccount",
  purpose: "DEPOSIT",
  targetStateId: "PENDING"
}, { apiKey: accessToken });

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

requests.post(
  "https://api-json.sandbox.paybase.io/v1/txs/inbound",
  data = json.dumps({
    "accountId": "account/b98774fc-3c41-43bc-bd03-13e327dcfbbb",
    "amount": "500",
    "method": "bankAccount",
    "purpose": "DEPOSIT",
    "targetStateId": "PENDING"
  }),
  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
16
17
18
$client = new \GuzzleHttp\Client();
$client->request(
  "post",
  "https://api-json.sandbox.paybase.io/v1/txs/inbound",
  [
    "body" => "{
      \"accountId\": \"account/b98774fc-3c41-43bc-bd03-13e327dcfbbb\",
      \"amount\": \"500\",
      \"method\": \"bankAccount\",
      \"purpose\": \"DEPOSIT\",
      \"targetStateId\": \"PENDING\"
    }",
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
5
6
7
8
9
10
11
curl -X POST \
"https://api-json.sandbox.paybase.io/v1/txs/inbound"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \
  -d '{
    "accountId": "account/b98774fc-3c41-43bc-bd03-13e327dcfbbb",
    "amount": "500",
    "method": "bankAccount",
    "purpose": "DEPOSIT",
    "targetStateId": "PENDING"
  }'

Request

FieldDescription
accountIdrequired
string

The unique identifier of the destination Paybase account into which funds should arrive.

Format

account/_uuid_

e.g. account/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

amountrequired
string

The amount of the transaction.

Format

Represented in the smallest currency unit. e.g. 1000 pennies for GBP 10

methodrequired
string

Whether the funds will originate from a card or via a bank transfer.

enum

card, bankAccount

targetStateIdoptional
enum

The state in which you want the transaction to enter when it is created. Typically this will be PENDING, HELD or EFFECTED.

enum

  • PENDING - The initial state of a transaction where it is considered incomplete. The transaction amount will be deducted from the sender's balance but not added to the receiver's balance. Target this stateId for inbound transactions of method bankAccount. For most other use cases the state is transient. However, if a Paybase rule flags a transaction for review it will remain in PENDING until the alert associated with the rule breach is resolved.

  • HELD - Target this stateId when you want to create an inbound escrow transaction. The transaction will be processed and remain in HELD until you transition it to another state.

  • EFFECTED - The state the most transactions will aim to achieve. EFFECTED transactions have been processed and taken effect. Incomplete debits and credits will become complete, and the balances of all involved parties will be adjusted accordingly.

purposerequired
enum

The purpose of the created transaction.

enum

  • PURCHASE - Payment for goods or services

  • TRANSFER - Transfer from one Paybase account to another

  • DEPOSIT - Deposit of funds on a Paybase account

paymentInstrumentIdoptional
string

The payment instrument to use for the created transaction.

Format

bank_account/_uuid_ or card/_uuid_

e.g. bank_account/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

If method is card, the id of the required card must be provided as the paymentInstrumentId.

If method is bankAccount, the id should only be provided if funds are expected from a known bankAccount which has already been created on the system. However, if the details of the sending bank account are not yet known, it is not mandatory to provide a paymentInstrumentId upfront. In this case, when funds are received by Paybase, a bankAccount will automatically be created and linked to the customer owning the destination account.

descriptionoptional
string

A description of the transaction.

FORMAT

string of max. 140 characters

annotationsoptional
object<string, string>

A hash map of key value pairs. Annotations allow you to supply information which is pertinent to your own system (e.g. Providing the ID of a customer on your system to link to their Paybase account). Annotations can also drive various Paybase rules.

tagsoptional
array<string>

An array of string values. Tags can be attached to objects in order to drive rules based logic either on Paybase or on your own system.

groupIdoptional
string

An identifier that can be used to link transactions together. A groupID can only be provided at creation of the transaction. Its use is purely symbolic and does not drive specific platform logic. However, the groupID can be used for query purposes.

Response

FieldDescription
id
string

The unique identifier of the transaction object.

Format

transaction/_uuid_

e.g. transaction/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

stateId
enum

The current state of the external transaction.

enum

PENDING, ACCEPTED, PROCESSING, HELD, EFFECTED, DISPUTED, ADJUSTED, ERRORED, CANCELLED, FAILED

createdAt
date

The timestamp in UTC at which the object was created.

updatedAt
date

The timestamp in UTC at which the object was last updated.

fromOwnerId
string

The unique id of the sender from who the transaction originates. The sender can be a customer or the tenant i.e. you.

Format

customer/_uuid_

e.g. customer/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

toOwnerId
string

The unique id of the owner of the acccount that receives the transaction. The owner can be a customer or the tenant i.e. you.

Format

customer/_uuid_

e.g. customer/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

paymentInstrumentId
string

The identifier of the payment instrument to use to facilitate an external transaction. Not applicable to internal transactions.

Format

bank_account/_uuid_ or card/_uuid_

e.g. card/62dc1d23-d473-46a6-b4b3-e63c3f6d4658

purpose
enum

The purpose of the created transaction.

enum

  • PURCHASE - Payment for goods or services

  • TRANSFER - Transfer from one Paybase account to another

  • DEPOSIT - Deposit of funds on a Paybase account

  • WITHDRAWAL - Withdrawal of funds from a Paybase account to a real bank account

adjustments
array<Adjustment>

A list of all adjustments on a transaction.

flow
enum

The direction of the flow of funds with respect to the Paybase platform.

enum

  • INBOUND - Funds flowing into the Paybase platform for a purchase or deposit.

  • OUTBOUND - Funds leaving the Paybase platform as a result of a withdrawal.

  • INTERNAL - transfer of funds between two Paybase accounts.

method
string

The method by which the transaction is facilitated.

enum

card, bankAccount, transfer

description
string

A description of the transaction. For withdrawals to a bank account, this may appear on the recipient's statement.

Format

string of max. 140 characters

annotations
object<string, string>

A hash map of key value pairs. Annotations allow you to supply information which is pertinent to your own system (e.g. Providing the ID of a customer on your system to link to their Paybase account). Annotations can also drive various Paybase rules.

tags
array<string>

An array of string values. Tags can be attached to objects in order to drive rules based logic either on Paybase or on your own system.

groupId
string

An identifier that can be used to link transactions together. A groupID can only be provided at creation of the transaction. Its use is purely symbolic and does not drive specific platform logic. However, the groupID can be used for query purposes.

requirements
object<string, string>

A map of further authentication requirements for successfully creating the transaction.

The transaction will remain in PROCESSING status until these requirements have been resolved.

reference
string

For an INBOUND bankAccount transaction, reference is the unique transaction reference to be used when your customer makes a bank transfer into a Paybase account. The value will only be returned if you previously generated a reference for the transaction using the /v1/reference/ endpoint.

For an OUTBOUND bankAccount transaction, reference is the payment reference that will be sent to the recipient's bank.

amount
string

The amount of the transaction intent.

Format

Represented in the smallest currency unit. e.g. 1000 pennies for GBP 10