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

Inbound Transaction Using Transaction Reference

Inbound payments are currently supported using UK Faster Payments only. To make payments into Paybase, you will need to provide your users a sort code, account number, account name and a Paybase generated reference. These details will be returned in the Retrieve a Reference API call.

It is important that you guide your users to provide the exact Reference when making a bank transfer because it is used to determine which account the incoming funds should be credited into. While the bank account number and sort code will typically stay the same for all transactions, the Reference can change depending on the type of transaction being created.

Transaction references are useful when you need to specify the amount upfront and can only be used once. In summary, you will create a transaction in a PENDING state to an account, then retrieve a reference for it. You can then make the payment using the reference and bank details provided. When we receive the inbound payment, the initial transaction will be transitioned to EFFECTED. In sandbox you can use the Console to simulate an incoming payment. In production your users will use their banking app / website to initiate the payment.

1. Create an Inbound Transaction

To create an inbound transaction, you will need the id of the account in which funds will arrive.

Use the txs/inbound endpoint to create the transaction that you expect to receive from your user with the parameters as in the example below. The accountId is the id of the account into which the incoming funds will be credited.

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"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "adjustments": [
    {
      "createdAt": "2019-02-25T17:38:53.021Z",
      "accountId": "account/b98774fc-3c41-43bc-bd03-13e327dcfbbb",
      "amount": "500",
      "type": "INTENT",
      "rate": "1.00000000"
    }
  ],
  "tags": [],
  "annotations": {},
  "id": "tx/a6af0aa7-2749-4715-b652-27c49b923421",
  "stateId": "PENDING",
  "createdAt": "2019-02-25T17:38:53.021Z",
  "updatedAt": "2019-02-25T17:38:53.021Z",
  "toOwnerId": "customer/28958679-e8a8-47a8-967c-f979ae8509a2",
  "purpose": "DEPOSIT",
  "flow": "INBOUND",
  "method": "bankAccount"
}

Save the id of the transaction as it will be required in the next request to get bank details required for the deposit and the reference associated with the transaction.

2. Get the Reference

Provide the id of the transaction on the GET reference API to retrieve the transaction reference.

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

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

const result = await client.getReference({
  toId: "tx/a6af0aa7-2749-4715-b652-27c49b923421",
  fromId: ""
});

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

requests.get(
  "https://api-json.sandbox.paybase.io/v1/reference/tx/a6af0aa7-2749-4715-b652-27c49b923421Params: toIdParams: fromId",
  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/tx/a6af0aa7-2749-4715-b652-27c49b923421Params: toIdParams: fromId",
  [
    "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/tx/a6af0aa7-2749-4715-b652-27c49b923421Params: toIdParams: fromId"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \

1
2
3
4
5
6
7
{
  "reference": "PBSTCKR6G4P98PYSS6",
  "accountName": "Client Money Account 1 - Sandbox",
  "accountNumber": "00000021",
  "sortCode": "040504",
  "IBAN": "GB95CLRB04050400000021"
}

The response includes all the details needed to make a transfer from a bank account.

Please do NOT attempt to make this transaction from a real bank account. You must simulate it from the Paybase Console as it is not real money.

3. Initiate the Payment

The transaction created above can be simulated on the Console using the reference returned in the previous step.

Go to https://console.sandbox.paybase.io/partner/integrations and the Debug - Sandbox Only card (you may need to scroll). Input the reference retrieved in the previous step and click Send.

card-form-screenshot

On clicking Send you will see a message saying the payment was successful.

When navigating to the Transactions page you should see that the transaction is now in an EFFECTED state.

Next up