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

200

Merchant created.

409

Merchant already registered by merchantId.

post /api/v1/merchants

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants

Production

https://loyalty-settlement.storebox.com/api/v1/merchants

Request samples

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

Response samples

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

Get merchants

Get all registered merchants.

Authorizations:

Responses

200

Merchants returned.

get /api/v1/merchants

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants

Production

https://loyalty-settlement.storebox.com/api/v1/merchants

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get merchant

Get a single merchant by merchantId.

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

External id of the merchant.

Responses

200

Merchant returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

Merchant updated.

404

No merchant found by merchantId.

put /api/v1/merchants/{merchantId}

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

Merchant deleted.

404

No merchant found by merchantId.

delete /api/v1/merchants/{merchantId}

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}

Get companies

Get companies for a merchant by merchantId.

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

External id of the merchant.

Responses

200

Merchant companies returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}/companies

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/companies

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/companies

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get stores

Get stores for a merchant by merchantId.

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

External id of the merchant.

Responses

200

Merchant stores returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}/stores

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/stores

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/stores

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get categories

Get categories for a merchant by merchantId.

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

External id of the merchant.

Responses

200

Merchant categories returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}/categories

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/categories

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/categories

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get campaigns

Get campaigns for a merchant by merchantId.

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

External id of the merchant.

Responses

200

Merchant campaigns returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}/campaigns

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/campaigns

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/campaigns

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

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

200

Derived shares returned.

404

No merchant found by merchantId.

get /api/v1/merchants/{merchantId}/derivedshares

Test

https://test-loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/derivedshares

Production

https://loyalty-settlement.storebox.com/api/v1/merchants/{merchantId}/derivedshares