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

Card creation with 3D Secure

When you first create a card on Paybase, your user will be required to go through the 3D Secure authentication flow.

3D Secure with Paybase Capture

We highly recommend that you use Paybase Capture to collect card details from your users and create a card. Paybase Capture is a hosted solution which will automatically handle the 3D Secure authentication flow for you without any additional development.

card-form-screenshot

Manually handling 3D Secure

If your platform is PCI-DSS compliant, you will be able to use the cards endpoint to create cards for your users. However, this means that you will have to manually handle the 3D Secure authentication flow using an iframe or a URL redirect.

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.

Step 1: Use the cards endpoint to initiate the creation of a new card.

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 body to a successful API request will be the full card object. If 3D Secure authentication is activated on your account, the card will be created in a PROCESSING state and the object will return the 3D Secure authentication URL in the requirements attribute.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "tags": [],
  "annotations": {},
  "requirements": {
    "3ds": "//hosted.sandbox.paybase.io/3ds/initiate/wZgL_tS9Q"
  },
  "id": "card/6c1633c1-db04-4c40-b9f2-a38c65b2b7b8",
  "createdAt": "2019-08-30T15:20:13.479Z",
  "updatedAt": "2019-08-30T15:20:13.479Z",
  "stateId": "PROCESSING",
  "cardNumberSuffix": "7898",
  "expiry": "1020",
  "scheme": "mastercard",
  "type": "prepaid",
  "ownerId": "customer/1a716f8b-4c15-4cb5-a5f8-712b67bb596a",
  "billingAddress": {
    "houseNameNumber": "Merevale Avenue, Leicester, GB",
    "region": "GB",
    "postalCode": "LE10 2BU",
    "countryISO": "GB",
    "street":"Brick Lane",
    "townCity":"London"
  },
  "storageType": "CARD_ON_FILE",
  "setAsPreferred": false
}

Step 2: Display the returned 3D Secure authentication URL to your user in an iframe.

1
2
3
4
const iframe = document.createElement('iframe');
iframe.id = '3ds-flow';
iframe.src = card.requirements['3ds'];
document.body.appendChild(iframe);


If the requirements attribute returns a 3DS URL but you do not integrate the 3DS flow, the card will remain in the PROCESSING state and your user will not be able to transact.

Step 3: Once the 3D Secure authentication flow has been successfully completed by your user, the card will be ENABLED and ready for use.

Testing your integration in Sandbox

When integrating with our Sandbox environment, you can use several test card numbers to simulate different results.

If 3D Secure authentication is enabled on your account, the 3DS URL will return a test form that will also allow you to simulate various scenarios that you might receive in real life from the card issuing bank.

3ds-form

Cards details for successful transactions

The following card details will allow you to simulate a successful card creation. The same card details can then be used to simulate successful card transactions.

NumberExpiryCVVAddress
45397910017301061222289Unit 5, 120 Uxbridge Road, Middlesex, GB, HA6 7HJ
49294212346008211222356Flat 6, 347 Lavender Road, Northampton, GB, NN17 8YG
55734712345678981222159Merevale Avenue, Leicester, GB, LE10 2BU
5301250070000191122241925 The Larches, Narborough, Leicester, GB, LE10 2RT

Simulating errors on card creation

The following card numbers can be used to test specific errors flows when creating a card. When using these cards, only the card number is taken into account to return the expected result. The values provided for cvv and address are disregarded so you can use any value for these fields.

There are 2 points in the flow where you can get errors. The first is on the call to create a card, the second will be in the response from 3DS. If 3DS is not activated then all the errors will happen on creating a card.

The following card numbers will throw an error on the call to create a card.

Card numberError Message
4556053564670627something went wrong - check input and try again or contact support@paybase.io
5599419482721469something went wrong - please contact support@paybase.io

If 3DS is activated on your account, this following card numbers will fail to create a card after the 3DS flow is completed.

Card numberError Message
4911410419509261something went wrong - check input and try again or contact support@paybase.io
4596727852513126something went wrong - please contact support@paybase.io
4632217533721880card declined - contact issuer
4475838376688561card declined - potentially fraudulent (keep card)
4556532577816970card declined - no further information provided by issuer
5599417500568524card declined - invalid expiry or expired
5422227522451267avs cvv declined - check input and try again or contact support@paybase.io

Once you have successfully created a card, you can start creating transactions using this card.