Storebox Loyalty Settlement API (1.0.0)

Download OpenAPI specification:Download

Introduction

With the Loyalty Settlement platform users can earn points or real money when using thier payment card in a store. By processing payment card transactions or merchant receipts contributions will be calculated as a percentage of the amount on the current transaction.

Calculated contributions is returned by the API as a settlement. Each settlement has a user share and a provider share. The user share is the value that the user has earned and the provider share is the fee to the provider (the consumer of this api). Settlements can be summed up at intervals and the the merchant can be charged.

As a Loyalty Settlement provider partnerships must be made with different merchants with agreement on the percentage for user share and provider share. After agreement the merchant can be created but to start receiveing payment transactions the user must signup thier payment card to Storebox.

This can be done with our Card API if you, as a provider, have the users in your own user/member system. Or if Storebox should do the user administration, then a user should be created through our Loyalty API and afterwards cards can be added to a user.

Authentication

basicAuth

In each API call the username/password must be provided. This will be used by the storebox.com system to authenticate the calling system and authorize it to perform the requested operation. The username and password will be delivered by Storebox upon registration. The password can be changed at regular intervals. For each API call HTTP Authorization header should be set:

Authorization: Basic {Base64(<username>:<password>)}
Security Scheme Type HTTP
HTTP Authorization Scheme basic

Merchants

Merchants are the central part of the Loyalty Settlement API. A merchant is the high level resource with relations to companies, stores, categories and campaigns.

Add merchant

Add a single merchant. To start receiving payment transactions then add a Company resource afterwards.

Authorizations:
Request Body schema: application/json
merchantId
string [ 1 .. 32 ] characters

External id of the merchant. Automatically generated upon creation if not provided.

merchantName
required
string [ 1 .. 128 ] characters

Name of the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant"
}

Response samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active",
  • "companies": [
    ],
  • "campaigns": [
    ]
}

Get merchants

Get all registered merchants.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get merchant

Get a single merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
{
  • "merchantId": "mdo9afaoaoy2u7tomdy9y1mzcpftvdpk",
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active",
  • "companies": [
    ],
  • "campaigns": [
    ],
  • "stores": [
    ],
  • "categories": [
    ],
  • "derivedShares": [
    ]
}

Update merchant

Update one or more fields for a merchant by merchantId. The merchantId cannot be updated.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Request Body schema: application/json
merchantName
string [ 1 .. 128 ] characters

Name of the merchant

merchantStatus
string
Default: "active"
Enum: "active" "disabled"

Status of the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantName": "Test Merchant",
  • "merchantStatus": "active"
}

Delete merchant

Delete a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Get companies

Get companies for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get stores

Get stores for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get categories

Get categories for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get campaigns

Get campaigns for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get derived shares

Get all derived shares for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace derived shares

Replace all derived shares for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Request Body schema: application/json
required
Array of objects[ items ]

The list of derived shares to replace existing derived shares.

Responses

Request samples

Content type
application/json
{
  • "derivedShares": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get invoices

Get invoices data for a merchant by merchantId.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Settlement Source States

Get the state of each settlement source.

Authorizations:
path Parameters
merchantId
required
string [ 1 .. 32 ] characters

External id of the merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Settle merchants

Settle with merchants. Will sum up settlments pr. merchant pr. type (user share and provider share) and create invoice data accordingly. The returned settlementId can be used to fetch invoice data through /api/v1/invoices.

Authorizations:
query Parameters
externalMerchantId
string
Example: externalMerchantId=mdo9afaoaoy2u7tomdy9y1mzcpftvdpk

External id of merchant

Responses

Response samples

Content type
application/json