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

3D Secure Transaction Flow

If 3D Secure authentication is enabled on your account, you will be required to complete the 3D Secure flow in order to create a successful inbound card transaction.

Before you create an inbound card transaction, you will need to have already created a card whose id you need to provide in the paymentInstrumentId field in your request.

Step 1: Use the create inbound transaction endpoint to initiate the creation of a new inbound transaction.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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: "card",
  purpose: "DEPOSIT",
  targetStateId: "EFFECTED",
  paymentInstrumentId: "card/6c1633c1-db04-4c40-b9f2-a38c65b2b7b8"
}, { apiKey: accessToken });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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": "card",
    "purpose": "DEPOSIT",
    "targetStateId": "EFFECTED",
    "paymentInstrumentId": "card/6c1633c1-db04-4c40-b9f2-a38c65b2b7b8"
  }),
  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
$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\": \"card\",
      \"purpose\": \"DEPOSIT\",
      \"targetStateId\": \"EFFECTED\",
      \"paymentInstrumentId\": \"card/6c1633c1-db04-4c40-b9f2-a38c65b2b7b8\"
    }",
    "headers" => [
      "Content-Type" => "application/json",
      "X-Token" => "<X-Token goes here>",
    ]
  ]
);

1
2
3
4
5
6
7
8
9
10
11
12
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": "card",
    "purpose": "DEPOSIT",
    "targetStateId": "EFFECTED",
    "paymentInstrumentId": "card/6c1633c1-db04-4c40-b9f2-a38c65b2b7b8"
  }'

The response body to a successful API request will be the full txs object. If 3D Secure authentication is activated on your account, the transaction 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
27
{
  "adjustments": [
    {
      "id": "ed122416-0fef-4510-8efd-abd393a10bbe",
      "createdAt": "2019-09-02T11:53:39.281Z",
      "accountId": "account/fdd5b2e9-83c5-466d-9436-3567a8d4a521",
      "amount": "1000",
      "type": "INTENT",
      "rate": "1.00000000"
    }
  ],
  "tags": [],
  "annotations": {},
  "requirements": {
    "3ds": "//hosted.sandbox.paybase.io/3ds/initiate/tgL405iFS"
  },
  "id": "tx/e4fd6edd-87b1-4370-9b32-9dcb55168fb2",
  "stateId": "PROCESSING",
  "createdAt": "2019-09-02T11:53:39.281Z",
  "updatedAt": "2019-09-02T11:53:39.281Z",
  "fromOwnerId": "customer/18984145-45d7-45ce-b0c5-585ea022172d",
  "toOwnerId": "customer/18984145-45d7-45ce-b0c5-585ea022172d",
  "paymentInstrumentId": "card/1f9db38d-2845-4ec5-96ba-d5eddc3d6b47",
  "purpose": "PURCHASE",
  "flow": "INBOUND",
  "method": "card"
}

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

1
2
3
4
5
6
7
const iframe = document.createElement('iframe');
iframe.id = '3ds-flow';
iframe.src = txs.requirements['3ds'];
window.addEventListener('message', event => {
  console.log('your transactions details', event.data)
});
document.body.appendChild(iframe);


If the requirements attribute returns a 3DS URL but you do not integrate the 3DS flow, the transaction will remain in the PROCESSING state.

Step 3: Once the 3D Secure authentication flow has been successfully completed by your user, the transaction will transition to the targetStateId which is typically PENDING, HELD or EFFECTED.

Testing your integration in Sandbox

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 successful card transactions in Sandbox.

SchemeTypeNumberCVVAddress
VisaDebit4539791001730106289Unit 5, 120 Uxbridge Road, Middlesex, GB, HA6 7HJ
VisaCredit4929421234600821356Flat 6, 347 Lavender Road, Northampton, GB, NN17 8YG
MastercardDebit5573471234567898159Merevale Avenue, Leicester, GB, LE10 2BU
MastercardCredit530125007000019141925 The Larches, Narborough, Leicester, GB, LE10 2RT

Simulating errors on card transactions

The following card numbers will allow you to create a card successfully, but will return the specified errors when attempting a transaction with them. The values provided for cvv and address are disregarded so you can use any value for these fields.

Card numberError Message
4911208446567801something went wrong - check input and try again or contact support@paybase.io
4556053592191430something went wrong - please contact support@paybase.io
4129831849585613card declined - contact issuer
4556532542550027card declined - potentially fraudulent (keep card)
4539534676374978card declined - no further information provided by issuer
5422226597484872card declined - invalid expiry or expired
5422229318299207card declined - insufficient funds