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: a0406ac

Cards

You can accept Card payments on your platform allowing your customers to pay for goods and services or deposit funds into their Paybase Account. Paybase currently supports VISA and MasterCard.

At the time of creating a Card, you also need to link it to a Customer or a Cardholder through an ownerId.

Cardholders

The cardholder object can be used to represent a user on your platform who will typically be on the buying side. Cardholders differ from Customers in that there is no CDDLevel associated with a Cardholder and therefore they do not have to pass additional verification as Customers do. This allows you to seamlessly accept card payments from your users by collecting only their name, email and card details.

However, it is worth noting that the cardholder object should only be used for those users who will exclusively make card payments and you never intend to create a Paybase Account for them. A Paybase Account allows your users to hold balances and pay-in via bank transfer. However, a cardholder cannot be linked to an account or a bankAccount and therefore this functionality would not be available to these users. Therefore, if you expect to allow your users to make both card payments and bank account transfers, you should create them as a customer instead of a cardholder.

Creating a card with Paybase Capture

Collecting card details from users is governed by PCI DSS (Payment Card Industry Data Security Standard) and generally applies to all companies that handle card data. Complying with and maintaining these standards is a time and resource intensive task and we would generally advise you against an integration that involves any card data passing through your own servers. To shift the burden and complexity of PCI compliance away from you, you can use Paybase Capture, a set of hosted payment forms allowing you to securely collect card details from your users. Since the form is hosted and presented to your users directly from our servers, you will not have to handle this information directly. The branding of Paybase Capture forms can be controlled with a custom CSS that you can upload under Assets in the Integrations section on the Console. Note that the file must be named theme.css.

The following endpoints should be used for loading Paybase Capture forms.

EnvironmentEndpoint URL
Productionhttps://hosted.paybase.io
Sandboxhttps://hosted.sandbox.paybase.io

Using a Paybase Capture form to create a new card involves the following steps:

Step 1: Ensure that you have already created a Cardholder or a Customer to who you will link the card that you create. You will also need their id in the subsequent steps.

Step 2: Generate an authentication token for the customer (or cardholder) for who you want to create a card.

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

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

const result = await client.createCustomerAuthenticationToken({
  id: "{customerId}"
});

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

requests.post(
  "https://api-json.sandbox.paybase.io/v1/customer/{customerId}Params: id/tokens",
  data = json.dumps({}),
  headers = {
    "Content-Type": "application/json",
    "X-Token": "<X-Token goes here>"
  }
).json()

1
2
3
4
5
6
7
8
9
10
11
12
$client = new \GuzzleHttp\Client();
$client->request(
  "post",
  "https://api-json.sandbox.paybase.io/v1/customer/{customerId}Params: id/tokens",
  [
    "body" => "{}",
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
5
curl -X POST \
"https://api-json.sandbox.paybase.io/v1/customer/{customerId}Params: id/tokens"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \
  -d '{}'

The API call will return an accessToken which you will use in the next step.

Step 3: Load the Paybase Capture iframe on your webpage as below where {token} is the accessToken created in Step 2.

1
2
3
4
5
6
<iframe
  id="paybaseCardForm"
  title="Inline Frame Example"
  src="https://hosted.paybase.io/card?t={token}">
</iframe>
  

Upon successful completion of the form, the iframe will use the postMessage API to communicate with the parent window and return a full card object.

1
2
3
4
5
6
<script>
  window.addEventListener('message', event => {
    console.log('your card details', event.data)
  })
</script>
  

Save the id on your database as it will be required for any API requests associated with the created card.

Creating a card via cards endpoint

Use the cards endpoint only if you are fully PCI DSS compliant. Otherwise use Paybase Capture to create a card for your users.

Before you create a card, you will need to have already created a cardholder or a customer to who you will link the card that you create. You will also need their id to provide in the ownerId field of the cards request.

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

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

const { accessToken } = await client.createCustomerAuthenticationToken({
  id: "customer/28958679-e8a8-47a8-967c-f979ae8509a2"
});

const result = await client.createCard({
  ownerId: "customer/28958679-e8a8-47a8-967c-f979ae8509a2",
  cardNumber: "5573471234567898",
  expiry: "0921",
  cvv: "159",
  billingAddress: {
    postalCode: "SE6 9YU",
    countryISO: "GB",
    houseNameNumber: "7",
    street: "Brick Lane",
    townCity: "London"
  }
}, { apiKey: accessToken });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import json
import requests

requests.post(
  "https://api-json.sandbox.paybase.io/v1/cards",
  data = json.dumps({
    "ownerId": "customer/28958679-e8a8-47a8-967c-f979ae8509a2",
    "cardNumber": "5573471234567898",
    "expiry": "0921",
    "cvv": "159",
    "billingAddress": {
      "postalCode": "SE6 9YU",
      "countryISO": "GB",
      "houseNameNumber": "7",
      "street": "Brick Lane",
      "townCity": "London"
    }
  }),
  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
19
20
21
22
23
24
$client = new \GuzzleHttp\Client();
$client->request(
  "post",
  "https://api-json.sandbox.paybase.io/v1/cards",
  [
    "body" => "{
      \"ownerId\": \"customer/28958679-e8a8-47a8-967c-f979ae8509a2\",
      \"cardNumber\": \"5573471234567898\",
      \"expiry\": \"0921\",
      \"cvv\": \"159\",
      \"billingAddress\": {
        \"postalCode\": \"SE6 9YU\",
        \"countryISO\": \"GB\",
        \"houseNameNumber\": \"7\",
        \"street\": \"Brick Lane\",
        \"townCity\": \"London\"
      }
    }",
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X POST \
"https://api-json.sandbox.paybase.io/v1/cards"  -H "Content-Type: application/json" \
  -H "X-Token: <X-Token goes here>" \
  -d '{
    "ownerId": "customer/28958679-e8a8-47a8-967c-f979ae8509a2",
    "cardNumber": "5573471234567898",
    "expiry": "0921",
    "cvv": "159",
    "billingAddress": {
      "postalCode": "SE6 9YU",
      "countryISO": "GB",
      "houseNameNumber": "7",
      "street": "Brick Lane",
      "townCity": "London"
    }
  }'

The response to a successful API request will be the full card object. Store the returned id as it will be required for any API requests associated with this card.