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

Webhooks

Webhooks allow you to set up subscriptions (called Integrations) to Event Streams within our system. When an event is emitted on one of those streams, we will send an HTTP POST to the configured URL. Integrations can be used to keep the state of your own system inline with Paybase's, or be notified of asynchronous processes.

When setting up an Integration, you can define the events you would like to receive by using PQL. This gives you a large amount of flexibility to be extremely granular in describing the kind of events you would like to receive.

There are no limits to the number of Integrations you can create.

Setting up Integrations

Integrations are defined and set-up from the Console.

To set-up a new webhook:

  1. Go to the integrations tab on your Console home screen.
  2. On the Webhooks card, click the "Add Webhook" button.
  3. Input you query and the webhook URL you would like to use and click create.

Please note: The URL hostname you provide should match domains that were provided at on-boarding. Please contact us if you would like to add a specific hostname to your whitelist.

When you create an Integration, a specific Event will be sent to your server. You must respond to this initial request with an HTTP code of 204 so that we can be sure your server is set up correct. If this request is not completed successfully, the creation of the Integration will fail. Please see the Handshake section under each Event Stream version for information about this payload.

Using PQL

Using PQL to define the filter of the Event Stream allows for granular handling of individual events, having event specific endpoints on your system, or being notified of something extremely specific within the Paybase system.

A naive Integration may use the following PQL to receive all events the stream emits.

1
WHERE 1 = 1

We consider this a generally bad idea, but it may be useful for debugging purposes while initially setting up your Integration.

For more complex requirements you can use PQL to the full extent. Following are some examples of queries to use for Integrations.

  • Filtering to include only events associated with transactions:
1
WHERE type LIKE transaction%
  • Receiving a notification when a customer hits a certain CDD Level:
1
WHERE type = "customer_cdd_level_changed" AND entity.cddLevel = "THREE"

Event Stream V2

Event Stream V2 is the preferred Integration target and will soon be the only one that allows the creation of new Integrations. It contains more fully-featured events and some that are not available on V1.

Handshake

At the set-up of a new Integration on this Event Stream, you will receive a payload that exactly matches below. Your server must respond with an HTTP status of 204 to complete the Integration set-up process.

1
{ "type": "integration_handshake" }

Structure

Payloads that your server will receive are generally structured as below. They will always contain a type property denoting the Event that was emitted.

1
2
3
4
5
6
7
8
{
    "type": "customer_created",
    "subjectId": "<Your Tenancy Id>",
    "traceId": "<Paybase Internal TraceId>",
    "entity": {
      // The Entity that was acted upon
    }
  }

There may be some events which differ slightly in structure around entities that are not usually accessible via the Public API. For example, events associated with alerts or customer due-diligence checks do not contain an entity property.

Supported Events

TypeDescription
customer_createdCustomer record created
customer_updatedCustomer record updated in some way, including a transition of state
customer_disabledCustomer record transitioned into a state of DISABLED
customer_enabledCustomer record transitioned into a state of ENABLED
customer_lockedCustomer record transitioned into a state of LOCKED
customer_closingCustomer record transitioned into a state of CLOSING
customer_terminatedCustomer record transitioned into a state of TERMINATED
customer_cdd_level_changedCustomer's Active CDD Level changed
cardholder_createdCardholder record created
cardholder_updatedCardholder record updated in some way, including a transition of state
cardholder_disabledCardholder record transitioned into a state of DISABLED
cardholder_enabledCardholder record transitioned into a state of ENABLED
cardholder_closedCardholder record transitioned into a state of CLOSED
card_createdCard record created
card_updatedCard record updated in some way, including a transition of state
card_activatedCard record transitioned into a state of ENABLED
card_archivedCard record transitioned into a state of INACTIVE
card_disabledCard record transitioned into a state of DISABLED
bank_account_createdBank Account record created
bank_account_updatedBank Account record updated in some way, including a transition of state
bank_account_disabledBank Account record transitioned into a state of DISABLED
bank_account_enabledBank Account record transitioned into a state of ENABLED
account_createdAccount record created
account_updatedAccount updated in some way, including a transition of state
account_enabledAccount record transitioned into a state of ENABLED
account_disabledAccount record transitioned into a state of DISABLED
account_closedAccount record transitioned into a state of CLOSED
account_balance_updatedAccount balance updated
transaction_createdTransaction record created
transaction_updatedTransaction record updated in some way, including a transition of state
transaction_effectedTransaction record transitioned into a state of EFFECTED
transaction_pausedTransaction that was created to be immediately EFFECTED was paused, most likely because of a Paybase rule
transaction_rejectedTransaction creation was rejected for some reason. This is useful for being notified of Triggered transactions that have failed at creation
transaction_heldTransaction record transitioned into a state of HELD, most likely as the result of an Escrow transaction
transaction_failedTransaction record transitioned into a state of FAILED
transaction_cancelledTransaction record transitioned into a state of CANCELLED
transaction_acceptedTransaction record transitioned into a state of ACCEPTED
transaction_processingTransaction record transitioned into a state of PROCESSING
transaction_erroredTransaction record transitioned into a state of ERRORED
transaction_disputedTransaction record transitioned into a state of DISPUTED
transaction_adjustedTransaction record transitioned into a state of ADJUSTED
check_passedDue-diligence Check for a Customer is PASSED
check_failedDue-diligence Check for a Customer is FAILED
alert_raisedAlert raised by the Paybase system. The Alert will be accessible on the Console
alert_action_requiredAlert requires actioning by one of your Agents. The Alert will be accessible on the Console
alert_dismissedAlert transitioned to DISMISSED. The Alert will be accessible on the Console
alert_resolvedAlert transitioned to RESOLVED. The Alert will be accessible on the Console

Validating a request from Paybase

As an additional layer of security, you can verify the identity of the request you receive from the webhook to ensure that you only accept requests from Paybase. You will need to use the Public Keys below. Note that the keys are different for Sandbox and Production environments.

Sandbox Key

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1fh93oTuoCrRLpk/W8uv
du4C0PoHQPjnwSwveWnLdkmeCmMBuLCaRMLfjwZMiWgZiiQS8jYdb+sLv52rcjaC
OYSoh4oFpaKuWZvkeLMNqIWQ6obkha5/jvce6y4MwGdkPlEyTThKgyR0+QU7x6+m
8ICASjUsuzcgZZNJSPEf15BHU7rvV8GCzNGd+GqRQ5Poj4iAQ/Cn/xoR0oty04vp
ireasf8XAVIoOMsYO+bTpUSxmVRCvALnV3dP5Q17YQeSTCR5s94BEm9Jv+s6Sy+p
uY1htpsweLdabrPvJWn3Ai3XP2fUMkPkcLi11Q9A+wbFgDzmMj5Q1/JRelBm78LD
0xagBr7XdpZA08SSio12OKcSUcA8QNi1IV9t5mhJ8XwmhrQ4Hl8RJNAKTeSoq8J9
J/Gc1fCJVMV/ltocH1Ed+jlqlNypMtzsWLT8659aHPN8lLanWo/CEpIHU1ckHsMU
UyZxlUeRqjohWalJX3Jmu9eo9/r4ZN47hz2ZJTUPMhPw6FOCV/UXZbd/5AX64go/
o9EJWKzWL+gIIiwwt6oFfCrLtLepzrA4LvJAw7CZJkTRjAvR5dEnxGkicqhjyTUX
PgHtjLVRaX0lVrsY8X0JbKFHsC1PJNFF8bIrjVu5Cmgnal4wl59E7m3xV5f/vleJ
sml7T4gwb9HOeexGnS3ojZkCAwEAAQ==
-----END PUBLIC KEY-----

Production Key

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5mkplWM7Ejy6mHH15zAf
ueJOdNI2Qi0KWJcbeiXut2WXiVDPV1459XY2VO8Y0/Q5T7TSYGXjiavStd9+JYPf
Cs7yqVXlvhgU0BfxhVmoemp7xD0EckNde3Px1iGrbFa+y8/+dvr7OdQlhxz0zCLO
WkIz+COh1XXU8YJ9veSI0ZFUIDpZcJRdPpIL1WfslMks7d06Fi3YLTac5bjd5wGE
C7V0ZlKPqcV25petES8bPb3yROBvxr8AAtX73M6S3yFGp+tQV4TUQOpWnF64cSg9
7ZovjvVRuzBvMp18jhjn6Y1X+jmyAexOLgfV3YujlIaRgyupYxOOesSObCNKAY1J
rB0egFIC/W5SHxMR7kGeUU1CDZdfM4aRQIbty3xq6EtTNQDAZkw+FJqvOtfvR5jl
9TEZm9MbUG660iabeevzg8+6nA3aV9209ydcVjzb+F/oAG4AnYEwiAuDSuRYyPGR
mIVAhu7fXxd4ROlsak5ta68StQHBcBxJ2848Q7AkiR6AUsWMO4Eo/zkSzv7AXCo3
Ar7tJ43HMCI9Y95ek0ap0eyGRG+4WMoaHh1XD7tlpVtsYVO2EdQg0/qKXcidmcf5
EsezclKcQYkwXG3jLHCR3euv/UpOxXLFR7aKmLpdXU4YyPMAT69jULfzvoEhRguW
74vMW+0vAiPnKcYcCXm5IgECAwEAAQ==
-----END PUBLIC KEY-----

To verify the request, you will need the following:

  • The body of the request you want to verify
  • The public key above for the Paybase environment you are using
  • The request signature that you can find in X-Signature request header

The example below shows how to verify a request in Node.JS using the crypto standard library.

1
2
3
4
5
6
7
8
9
10
11
12
13
const crypto = require('crypto');

const base64 = x => Buffer.from(x, 'base64').toString('utf8');
const PAYBASE_PUBLIC_KEY = base64(process.env.PAYBASE_PUBLIC_KEY);

// body represents the body of the request
// signature represents the signature from the request. you can find it in the `X-Signature` header
const verify = (body, signature) => {
  const verifyBase = crypto.createVerify('sha256WithRSAEncryption');
  verifyBase.update(typeof body === 'string' ? body : JSON.stringify(body));
  verifyBase.end();
  return verifyBase.verify(PAYBASE_PUBLIC_KEY, signature, 'base64');
};

Event Stream V1 (Deprecated)

Event Stream V1 is currently being deprecated. It is ill-advised to set-up new Integrations using this Event Stream and will soon be impossible.

Event Stream V1 allows you to hook in to certain raw events within the Paybase system. It does not produce events for information around asynchronous processes such as Triggered transactions or Customer due-diligence.

Handshake

At the set-up of a new Integration on this Event Stream, you will receive a payload that exactly matches below. Your server must respond with an HTTP status of 204 to complete the Integration set-up process.

1
{ "type": "integration.handshake" }

Structure

Payloads are structured in the following way. They always contain a type and a payload containing both request and response objects.

1
2
3
4
5
6
7
{
  "type": "account.create",
  "payload": {
    "request": { ... },
    "response": { ... }
  }
}

Supported events

In their simplest forms, Integrations can be created against the following events to catch all of the specific event types. If you want to have one endpoint handle multiple different event types, you can extend the query.

NameDescription
account.createTriggered when an account is created
account.transitionByIdTriggered whenever an account's state is changed
bank-account.createTriggered when a bank account is created
bank-account.transitionByIdTriggered whenever a bank account's state is changed
card.createTriggered when a card is created
card.transitionByIdTriggered whenever a card's state is changed
customer.createTriggered when a customer is created
customer.transitionByIdTriggered whenever a customer's state is changed
customer.updateByIdTriggered whenever a customer is updated
tx.createTriggered when a transaction is created
tx.transitionByIdTriggered whenever a transaction's state is changed