Update Webhook Subscription

Authentication

These endpoints provide various methods for authenticating users from a backend service.

POST /auth/signin Sign-in from a backend service on behalf of a consumer customer (B2C) or customer delegate (B2B)

Operations

Customers

A person or business purchasing goods or services from a merchant using Spenda to facilitate the payment. Customers are defined at the merchant level, so if an individual makes payments with multiple merchants, they will have a customer record for each of these merchants.

Spenda supports two broad categories of customers:

Consumer customers are individuals typically making purchases from the merchant via e-commerce websites. They are uniquely identified by emailAddress for a given merchant.

Organisation customers represent businesses wishing to make purchases from the merchant. They are uniquely identified by referenceCustomerId for a given merchant.

GET /customers Return a paginated list of matching customers
POST /customers Create a new customer or update the details of an existing customer
GET /customers/{customerId} Return details of a customer
POST /customers/kyc Perform a Know Your Customer (KYC) check on a consumer customer
GET /customers/delegates Return a paginated list of matching customer delegates
GET /customers/delegates/{customerDelegateId} Return details of a customer delegate
PATCH /customers/delegates/{customerDelegateId} Various actions for updating a customer delegate such as linking to a new customer
DELETE /customers/delegates/{customerDelegateId} Delete a customer delegate

Operations

Merchants

A business or individual that uses Spenda to facilitate payments for their customers.

GET /merchants Return a paginated list of matching merchants
POST /merchants Create a new sub-merchant within the context of a marketplace
GET /merchants/{merchantId} Return details of a merchant
PATCH /merchants/{merchantId} Various actions for updating a merchant such as updating the bank account used for payouts
GET /merchants/{merchantId}/balances Query the account balances of a merchant
POST /merchants/{merchantId}/files Upload a document scan as part of the merchant onboarding profile
GET /merchants/{merchantId}/files/{fileId} Get details on a merchant onboarding file
GET /merchants/{merchantId}/applepay Get the domains registered for ApplePay for the specified merchant
GET /merchants/{merchantId}/owners Return details of all beneficial owners for the given merchant
POST /merchants/{merchantId}/owners Create a beneficial owner for the given merchant
GET /merchants/{merchantId}/owners/{ownerId} Return details of a beneficial owner
PUT /merchants/{merchantId}/owners/{ownerId} Overwrite an existing beneficial owner
DELETE /merchants/{merchantId}/owners/{ownerId} Delete a beneficial owner
GET /merchants/industries List all industries we currently support

Operations

Payment sources

A payment source represents a reusable source of funds to use for payments.

GET /sources/{sourceId}
DELETE /sources/{sourceId}
POST /sources Register a payment source that may be used to pay for one or more payments
GET /sources Return a paginated list of matching payment sources
GET /sources/blockedcards Return a paginated list of events related to cards that have been blocked
PATCH /sources/blockedcards/{cardBlockId} Update actions on blocked cards

Operations

Payment tokens

A payment token represents a single use reference to a source of funds that can be used to pay for an order.

POST /tokens Generate a pay-in-full payment token based on the provided payment source
GET /tokens/{paymentTokenId} Get the details for a pay-in-full payment token
POST /tokens/{merchantId}/surchargequote Calculates the surcharged amounts for the specified payment type

Operations

Pay plans

A pay plan represents a payment where the Spenda platform has extended a loan to make a purchase that the customer pays back over one or more instalments.

POST /payplans/offer Create a pay plan offer for a registered and KYC'd merchant customer
GET /payplans Return a paginated list of matching pay plans
POST /payplans Create a pay plan and payment token from a successful pay plan offer
GET /payplans/{payPlanId} Return details of a pay plan
POST /payplans/max Return the maximum loan amount the given customer is currently eligible for
POST /payplans/parameters Calculate the pay plan parameters for the given amount and list of variants

Operations

Orders

An order captures the details of the goods or services that the customer is purchasing from the merchant.

GET /orders Return a paginated list of matching orders
POST /orders Creates a new order
POST /orders/{orderId}/pay Pay for an order using a payment token
GET /orders/{orderId} Retrieves an order
DELETE /orders/{orderId} Cancels an order, invalidating it from being payable
PATCH /orders/{orderId} Actions for modifying an existing order

Operations

Simulation

Sandbox only endpoints for simulating external events such as a bank transfer.

POST /simulation Sandbox only endpoint to simulate external events such as a bank transfer being performed

Operations

Transactions

A transaction is a payment from the perspective of a merchant. The transaction shows how much the merchant will be paid, if they have been paid already and whether there have been any refunds.

GET /transactions/{transactionId} Return details of a transaction
GET /transactions Return a paginated list of matching transactions
PATCH /transactions/{transactionId} Various actions for updating a transaction such as issuing a refund
POST /transactions/payouts Request to create a manual payout for a merchant
GET /transactions/payouts Return a paginated list of matching payout summaries
GET /transactions/payouts/{payoutId} Return an aggregated breakdown of the money movements included in the payout along with details of the disbursement itself
GET /transactions/invoices Return a paginated list of matching merchant invoices
GET /transactions/invoices/{invoiceId} Return an aggregated breakdown of the money movements included in the invoice along with billing details
GET /transactions/invoices/{invoiceId}/pdf Return a PDF of the merchant invoice intended to be sent to the payer merchant
GET /transactions/settlement Return a paginated list of all settlement entries matching the given search criteria
GET /transactions/settlement/report Return a list of all settlement entries matching the given search criteria
GET /transactions/disputes Return a paginated list of all disputes matching the given search criteria
GET /transactions/refunds Return a paginated list of matching refunds

Operations

Marketplaces

A B2B2C setup where an entity with business customers (sub-merchants) uses Spenda to facilitate payments for their customers' customers.

GET /marketplaces/{marketplaceId} Return details of a marketplace
POST /marketplaces/customer Marketplace customers allow marketplaces to onboard their customers once and have them available over all their sub-merchants

Operations

Webhooks

Webhooks are a mechanism where merchants and marketplaces can register an endpoints against one or more events. When these events occur, a POST HTTP request is made to the registered endpoint with the event details.

GET /webhooks Return a paginated list of matching webhook subscriptions
POST /webhooks Create a new webhook subscription
GET /webhooks/{id} Return details of a webhook subscription
PATCH /webhooks/{id} Update an existing webhook subscription

Operations

Query Webhook Subscriptions

Request

Return a paginated list of matching webhook subscriptions.

Security

Marketplace API Key | Merchant Secret Token | Admin JWT | Marketplace JWT | Merchant JWT

Query

limitinteger(int32)

Maximum results per page. Default to 20, must be between 1 and 500.

pageinteger(int32)

Page number of results to show (starting at page 1).

sortstring

Comma-delimited list of fields to sort by with sort priority from first to last. Fields are sorted by their natural ordering unless prefixed with a - character.

merchantIdArray of strings

Only include webhook merchant subscriptions for this given list of sub-merchants. Only relevant for marketplace users interested in merchant level subscriptions.

marketplaceIdstring

Only include webhook marketplace subscriptions for the given marketplaceId. Only relevant for admin users interested in marketplace level subscriptions.

statusstring(WebhookSubscriptionState)

Filter by subscription status

Enum"Active""Suspended"

curl -i -X GET \
  'https://api.sandbox.au.meetapril.io/webhooks?limit=0&page=0&sort=string&merchantId=string&marketplaceId=string&status=Active' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Matching items sorted as specified

Headers

Page-Countinteger(int64)required

Total count of pages available for current query.

Total-Record-Countinteger(int64)required

Total number of records matching the query.

Bodyapplication/jsonArray [

One of:

WebhookMarketplaceSubscriptionobject(WebhookMarketplaceSubscription1)required

WebhookMarketplaceSubscription.idstringrequired

Unique identifier for this webhook subscription.

WebhookMarketplaceSubscription.marketplaceIdstringrequired

The marketplace system identifier for the marketplace for which you will receive webhook events.

WebhookMarketplaceSubscription.urlstringrequired

Destination endpoint that will be called via an HTTP POST on new events.

WebhookMarketplaceSubscription.eventsArray of strings(WebhookEventType)

Items Enum"MerchantCreated""MerchantActivated""MerchantSuspended""MerchantAvailableBalanceUpdated""MerchantBankAccountAdded""MerchantPrimaryBankAccountUpdated""PayPlanCreated""PayPlanActivated""PayPlanCompleted""PayPlanInDefault"

WebhookMarketplaceSubscription.descriptionstring

An optional description indicating what the webhook is used for.

WebhookMarketplaceSubscription.metadataobject(JsonObject)

Optional metadata to include in the payload of all webhooks generated by this subscription.

WebhookMarketplaceSubscription.statusstring(WebhookSubscriptionState)required

Is this subscription currently active.

Enum"Active""Suspended"

WebhookMarketplaceSubscription.secretstring

Key used to sign events. Can be used to verify the event is genuine.

]

Response

application/json

[
  {
    "WebhookMarketplaceSubscription": { … }
  }
]

Create Webhook Subscription

Request

Create a new webhook subscription. If called with a marketplace API key, the subscription will be at the marketplace level. If called with merchant credentials or if the Merchant-Id header is provided, the subscription will be at the merchant level.

Security

Marketplace API Key | Merchant Secret Token | Marketplace JWT | Merchant JWT

Headers

Merchant-Idstring

Perform operation in the context of the given merchant. Usually not required — specify only if acting on behalf of a merchant not implied by the credentials specified in the Authorization header.

Bodyapplication/jsonrequired

One of:

CreateWebhookMarketplaceSubscriptionobject(CreateWebhookMarketplaceSubscription1)required

CreateWebhookMarketplaceSubscription.urlstringrequired

Destination endpoint that will be called via an HTTP POST on new events. Protocol must be https

CreateWebhookMarketplaceSubscription.eventsArray of strings(WebhookEventType)

Items Enum"MerchantCreated""MerchantActivated""MerchantSuspended""MerchantAvailableBalanceUpdated""MerchantBankAccountAdded""MerchantPrimaryBankAccountUpdated""PayPlanCreated""PayPlanActivated""PayPlanCompleted""PayPlanInDefault"

CreateWebhookMarketplaceSubscription.descriptionstring

An optional description indicating what the webhook is used for.

CreateWebhookMarketplaceSubscription.metadataobject(JsonObject)

Optional metadata to include in the payload of all webhooks generated by this subscription.

curl -i -X POST \
  https://api.sandbox.au.meetapril.io/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Merchant-Id: string' \
  -d '{
    "CreateWebhookMarketplaceSubscription": {
      "url": "https://api.myservice.io/events",
      "events": [
        "MerchantCreated"
      ],
      "description": "string",
      "metadata": {}
    }
  }'

Responses

Bodyapplication/json

One of:

WebhookMarketplaceSubscriptionobject(WebhookMarketplaceSubscription1)required

WebhookMarketplaceSubscription.idstringrequired

Unique identifier for this webhook subscription.

WebhookMarketplaceSubscription.marketplaceIdstringrequired

The marketplace system identifier for the marketplace for which you will receive webhook events.

WebhookMarketplaceSubscription.urlstringrequired

Destination endpoint that will be called via an HTTP POST on new events.

WebhookMarketplaceSubscription.eventsArray of strings(WebhookEventType)

Items Enum"MerchantCreated""MerchantActivated""MerchantSuspended""MerchantAvailableBalanceUpdated""MerchantBankAccountAdded""MerchantPrimaryBankAccountUpdated""PayPlanCreated""PayPlanActivated""PayPlanCompleted""PayPlanInDefault"

WebhookMarketplaceSubscription.descriptionstring

An optional description indicating what the webhook is used for.

WebhookMarketplaceSubscription.metadataobject(JsonObject)

Optional metadata to include in the payload of all webhooks generated by this subscription.

WebhookMarketplaceSubscription.statusstring(WebhookSubscriptionState)required

Is this subscription currently active.

Enum"Active""Suspended"

WebhookMarketplaceSubscription.secretstring

Key used to sign events. Can be used to verify the event is genuine.

Response

application/json

{
  "WebhookMarketplaceSubscription": {
    "id": "webhook_aZ-9V_KvllCPqGtA",
    "marketplaceId": "mktp_aZ-9UfKvllCPqGsi",
    "url": "https://api.myservice.io/events",
    "events": [ … ],
    "description": "string",
    "metadata": {},
    "status": "Active",
    "secret": "string"
  }
}

Get Webhook Subscription

Request

Return details of a webhook subscription.

Security

Marketplace API Key | Merchant Secret Token | Admin JWT | Marketplace JWT | Merchant JWT

Path

idstringrequired

curl -i -X GET \
  'https://api.sandbox.au.meetapril.io/webhooks/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

One of:

WebhookMarketplaceSubscriptionobject(WebhookMarketplaceSubscription1)required

WebhookMarketplaceSubscription.idstringrequired

Unique identifier for this webhook subscription.

WebhookMarketplaceSubscription.marketplaceIdstringrequired

The marketplace system identifier for the marketplace for which you will receive webhook events.

WebhookMarketplaceSubscription.urlstringrequired

Destination endpoint that will be called via an HTTP POST on new events.

WebhookMarketplaceSubscription.eventsArray of strings(WebhookEventType)

Items Enum"MerchantCreated""MerchantActivated""MerchantSuspended""MerchantAvailableBalanceUpdated""MerchantBankAccountAdded""MerchantPrimaryBankAccountUpdated""PayPlanCreated""PayPlanActivated""PayPlanCompleted""PayPlanInDefault"

WebhookMarketplaceSubscription.descriptionstring

An optional description indicating what the webhook is used for.

WebhookMarketplaceSubscription.metadataobject(JsonObject)

Optional metadata to include in the payload of all webhooks generated by this subscription.

WebhookMarketplaceSubscription.statusstring(WebhookSubscriptionState)required

Is this subscription currently active.

Enum"Active""Suspended"

WebhookMarketplaceSubscription.secretstring

Key used to sign events. Can be used to verify the event is genuine.

Response

application/json

{
  "WebhookMarketplaceSubscription": {
    "id": "webhook_aZ-9V_KvllCPqGtA",
    "marketplaceId": "mktp_aZ-9UfKvllCPqGsi",
    "url": "https://api.myservice.io/events",
    "events": [ … ],
    "description": "string",
    "metadata": {},
    "status": "Active",
    "secret": "string"
  }
}