API docs by Redocly

Frizbee Prepaid Banking API (0.0.1 draft)

Download OpenAPI specification:Download

Frizbee Prepaid Banking is a specialized service designed to facilitate payments within a restricted network of acceptors. This API enables the creation and management of programs, each tailored to specific sectors, stores, or boutiques that can be fully managed via the API. It offers robust tools for managing user accounts, gift cards, bank cards, and custom-designed programs.

Utilizing JSON Web Tokens (JWT) for authentication and authorization, the API ensures secure interactions across various endpoints. Users are authenticated by obtaining an access token via a POST request to the /users/login endpoint, using their credentials. This token must then be included as a bearer token in the Authorization header for subsequent API requests.

Should the access token expire, a refresh token can be used to obtain a new access token without requiring user reauthentication. This is done by sending a POST request to the /users/refresh-token endpoint with the refresh token included in the request body.

The security of token storage and transmission is crucial to prevent unauthorized access to user accounts. Detailed information on each endpoint, including required request payloads and responses, can be found throughout this documentation. The API facilitates not only general banking transactions but also allows for the intricate management of restricted payment environments, ensuring each program adheres to its specified limitations regarding participant merchants and transaction scopes.

Users

Endpoints that manage enduser accounts within our solution.

Register a new user

Authorizations:
apiKey
Request Body schema: application/json
required
firstname
required
string <= 50 characters ^[A-Za-z-']+([ ][A-Za-z-']+)*$
lastname
required
string <= 50 characters ^[A-Za-z-']+([ ][A-Za-z-']+)*$
email
required
string <email> <= 100 characters ^([a-z0-9_\.-]+)@([\da-z\.-]+)\.([a-z\.]{2,5}...
password
required
string <password> <= 100 characters ^(?=.*[A-Za-z])(?=.*\\d)(?=.*[@$!%*#?&])[A-Za...
object
phone
required
string^\+?[0-9]{1,3}?[-.\s]?([0-9]{1,4}?[-.\s]?){2,...

Responses

Request samples

Content type
application/json
{
  • "firstname": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "password": "securePassword123",
  • "address": {
    },
  • "phone": "+33612345678"
}

Response samples

Content type
application/json
{
  • "message": "User created successfully",
  • "access_token": "string",
  • "refresh_token": "string"
}

User login

Authorizations:
apiKey
Request Body schema: application/json
required
email
required
string <email> ^([a-z0-9_\.-]+)@([\da-z\.-]+)\.([a-z\.]{2,5}...
password
required
string <password> ^(?=.*[A-Za-z])(?=.*\\d)(?=.*[@$!%*#?&])[A-Za...

Responses

Request samples

Content type
application/json
{
  • "email": "john.doe@example.com",
  • "password": "securePassword123"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJpc3N1ZXJfbmFtZSIsImV4cCI6MTcxMzY5NjI0Mn0.t1fZAJj5oXGWmB252mHsgl51eiX4CwX5_7T29cvzA-A"
}

Refresh access token

Allows a user to obtain a new access token using a valid refresh token.

Authorizations:
jwtAuth
Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string"
}

Update a user's entire profile

Updates the user's profile with new information. The entire user object must be provided in the request body.

Authorizations:
jwtAuth
path Parameters
uuid
required
string
Example: 578A6DA0-A5F0-4879-A50D-D50F425B7448
Request Body schema: application/json
required
uuid
string
firstname
string <= 50 characters ^[A-Za-z-']+([ ][A-Za-z-']+)*$
lastname
string <= 50 characters ^[A-Za-z-']+([ ][A-Za-z-']+)*$
email
string <email> <= 100 characters ^([a-z0-9_\.-]+)@([\da-z\.-]+)\.([a-z\.]{2,5}...
phone
string^\+(?:[0-9] ?){6,14}[0-9]$

Responses

Request samples

Content type
application/json
{
  • "uuid": "578A6DA0-A5F0-4879-A50D-D50F425B7448",
  • "firstname": "Jean",
  • "lastname": "Dupont",
  • "email": "jean.dupont@manager.one",
  • "phone": "+33123456789"
}

Response samples

Content type
application/json
{
  • "uuid": "578A6DA0-A5F0-4879-A50D-D50F425B7448",
  • "firstname": "Jean",
  • "lastname": "Dupont",
  • "email": "jean.dupont@manager.one",
  • "phone": "+33123456789"
}

Validate a user account

Validates a user's account using a token provided via email, typically sent during the registration process.

Authorizations:
jwtAuth
path Parameters
uuid
required
string

The unique identifier of the user

Request Body schema: application/json
required
token
required
string

Validation token received by the user via email.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "message": "Account has been successfully validated."
}

Change a user's password

Allows a user to change their password. Requires the current password for verification.

Authorizations:
jwtAuth
path Parameters
uuid
required
string

The unique identifier for the user

Request Body schema: application/json
required
currentPassword
required
string <password>
newPassword
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "currentPassword123!",
  • "newPassword": "newSecurePassword123!"
}

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Logout user and invalidate JWT refresh token

Authorizations:
jwtAuth

Responses

Response samples

Content type
application/json
{
  • "message": "User logged out successfully"
}

Disable a user account

Disables the user account making it inactive. The account can be reactivated later.

Authorizations:
jwtAuth
path Parameters
uuid
required
string

The unique identifier of the user.

Responses

Response samples

Content type
application/json
{
  • "message": "User account has been successfully disabled."
}

Delete a user account

Permanently deletes the user account from the system.

Authorizations:
jwtAuth
path Parameters
uuid
required
string

The unique identifier of the user.

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Deposit money onto a specific bank card through a payment processor

This endpoint allows users to deposit money directly onto a bank card identified by the card_id using an external payment method.

Authorizations:
jwtAuth
query Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: card_id=CARD1234567890
Request Body schema: application/json
required
amount
required
number <float>

Responses

Request samples

Content type
application/json
{
  • "amount": 100
}

Response samples

Content type
application/json
{}

Giftcards

Endpoints for managing gift cards associated with user accounts.

Attach a new giftcard to user's account

Authorizations:
jwtAuth
Request Body schema: application/json
required
giftcardCode
required
string
pinCode
required
string
user_uuid
required
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "giftcardCode": "GIFT12345XYZ",
  • "pinCode": "1234",
  • "user_uuid": "24151c2c-ba49-4830-9ade-66ee989cb0b0"
}

Response samples

Content type
application/json
{
  • "confirmation": "Gift card added successfully"
}

Convert the gift card balance to the specified bank card

Authorizations:
jwtAuth
Request Body schema: application/json
required
giftcardCode
required
string
card_id
required
string^[0-9A-Za-z]+$

Responses

Request samples

Content type
application/json
{
  • "giftcardCode": "GIFT12345XYZ",
  • "card_id": "CARD9876543210"
}

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Convert a gift card and create a bank card in one step

This endpoint handles the addition of a gift card, creation of a bank card, and the conversion of the gift card balance to the bank card.

Authorizations:
jwtAuth
Request Body schema: application/json
required
giftCardCode
required
string
pinCode
required
string
user_uuid
string

Responses

Request samples

Content type
application/json
{
  • "giftCardCode": "GFT1234567",
  • "pinCode": "1234",
  • "user_uuid": "24151c2c-ba49-4830-9ade-66ee989cb0b0"
}

Response samples

Content type
application/json
{
  • "confirmationMessage": "Gift card converted and bank card created successfully."
}

List all attached gift cards

Authorizations:
jwtAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details of a specific giftcard

Authorizations:
jwtAuth
path Parameters
giftcardCode
required
string
Example: GIFT12345XYZ

Responses

Response samples

Content type
application/json
{
  • "code": "GIFT12345XYZ",
  • "validityDate": "2022-12-31T23:59:59.999Z",
  • "balance": 50,
  • "faceValue": 50,
  • "attachmentDate": "2022-12-31T23:59:59.999Z",
  • "conversionDate": "2023-01-31T23:59:59.999Z"
}

Remove a giftcard from the user's account

Deletes a gift card only if it has not been converted. If the card has been converted, the operation will be rejected to preserve the transaction history.

Authorizations:
jwtAuth
path Parameters
giftcardCode
required
string
Example: GIFT12345XYZ
query Parameters
user_uuid
string
Example: user_uuid=a2bebbf0-b068-4e66-b77e-4d19fff95e99

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Cards

Endpoints related to the management of bank cards issued.

Retrieve bank cards

Authorizations:
jwtAuth
query Parameters
user_uuid
string

Filter cards by the user ID.

program_id
string

Filter cards by the program ID.

page
integer
Default: 1

Page number for pagination.

page_size
integer
Default: 10

Number of cards per page.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "total_pages": 5,
  • "total_items": 50,
  • "cards": [
    ]
}

Create a new bank card

Authorizations:
jwtAuth
Request Body schema: application/json
required
programId
required
string

The unique identifier of the program to which the card will be associated.

user_uuid
string

The unique identifier of the user to whom the card will be associated.

Responses

Request samples

Content type
application/json
{
  • "programId": "prog_123456",
  • "user_uuid": "a2bebbf0-b068-4e66-b77e-4d19fff95e99"
}

Response samples

Content type
application/json
{
  • "card_id": "card_789123",
  • "programId": "prog_123456",
  • "user_uuid": "a2bebbf0-b068-4e66-b77e-4d19fff95e99",
  • "status": "active"
}

Bank card details

Authorizations:
jwtAuth
path Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: CARD9876543210

Responses

Response samples

Content type
application/json
{
  • "card_id": "CARD9876543210",
  • "program": {
    },
  • "status": "active",
  • "user": {
    },
  • "type": "virtual_card",
  • "expiration_date": "2019-08-24",
  • "expiration_datefull": "2019-08-24",
  • "last_digits": "1234",
  • "initial_amount": 1000,
  • "consumed_amount": 200,
  • "available_amount": 800
}

Activate a bank card

Authorizations:
jwtAuth
path Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: CARD9876543210

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Lock a bank card

Authorizations:
jwtAuth
path Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: CARD9876543210

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}

Get a list of payment transactions for a specific card

Retrieves a paginated list of payment transactions associated with a specific bank card.

Authorizations:
jwtAuth
path Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: CARD9876543210
query Parameters
startDate
string <date-time> ^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])...
Example: startDate=2022-12-31T23:59:59.999Z
endDate
string <date-time> ^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])...
Example: endDate=2023-01-31
page
integer
Default: 1

Page number of the transaction list.

page_size
integer
Default: 10

Number of transactions to return per page.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "total_pages": 5,
  • "total_items": 50,
  • "transactions": [
    ]
}

List all conversions, deposits and fees operations for a specific card

Retrieves a history of all gift card conversions, bank card deposits and fees (renewal or account management).

Authorizations:
jwtAuth
path Parameters
card_id
required
string^[0-9A-Za-z]+$
Example: CARD9876543210
query Parameters
startDate
string <date-time> ^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])...

Start date for filtering the transaction history.

endDate
string <date-time> <= 32 characters ^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])...

End date for filtering the transaction history.

page
integer <int32> [ 0 .. 1024 ]
Default: 1

Page number for pagination.

page_size
integer <int32> [ 0 .. 100 ]
Default: 10

Number of transactions per page.

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "page": 1,
  • "total_pages": 5,
  • "total_items": 50
}

List export jobs for a program

Retrieves a list of export jobs for a specific program, including pagination and ordering options.

Authorizations:
jwtAuth
query Parameters
programId
required
string

The unique identifier of the program

page
integer
Default: 1

Page number for pagination.

page_size
integer
Default: 10

Number of jobs per page.

orderBy
string
Default: "createdAt_desc"
Enum: "createdAt_asc" "createdAt_desc"

Order by creation date, ascending or descending.

Responses

Response samples

Content type
application/json
{}

Initiate export of all cards associated with a specific program

Initiates an asynchronous job to export details of all bank cards linked to a specific program. Returns a job ID for status checking.

Authorizations:
jwtAuth
query Parameters
programId
required
string

The unique identifier of the program

status
string

Filter cards by their status (e.g., active, blocked, expired)

startDate
string <date>

Filter cards that were issued after this date

endDate
string <date>

Filter cards that expire before this date

Responses

Response samples

Content type
application/json
{
  • "message": "Export job initiated successfully.",
  • "jobId": "job_123456789"
}

Check the status of an export job

Returns the current status of an export job, including the download link once available.

Authorizations:
jwtAuth
path Parameters
jobId
required
string

The job ID returned by the export initiation endpoint

query Parameters
programId
required
string

The unique identifier of the program

Responses

Response samples

Content type
application/json
{}

Set the balance of a bank card

Updates the available balance of a specific bank card. This endpoint can set a new balance directly, useful for manual adjustments or corrections.

Authorizations:
jwtAuth
path Parameters
card_id
required
string
Example: CARD1234567890

The unique identifier of the bank card.

Request Body schema: application/json
required
balance
required
number <float>

The new balance to be set on the card.

Responses

Request samples

Content type
application/json
{
  • "balance": 1500.5
}

Response samples

Content type
application/json
{
  • "message": "Balance has been successfully updated.",
  • "card_id": "CARD1234567890",
  • "newBalance": 1500.5
}

Programs

Endpoints to get informations about your programs.

List all programs

Authorizations:
jwtAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new program

Authorizations:
jwtAuth
Request Body schema: application/json
required
name
string <= 100 characters
description
string <= 1024 characters
location
string <= 255 characters
Array of objects (Store) <= 100 items
renewalFee
boolean
renewalAmount
number <float>
giftCardEnabled
boolean

Indicates whether the use of gift cards is enabled for this program.

object (GiftCardProgram)

Responses

Request samples

Content type
application/json
{
  • "name": "Mall Program",
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...",
  • "location": "Global",
  • "stores": [],
  • "renewalFee": true,
  • "renewalAmount": 20,
  • "giftCardEnabled": true,
  • "giftCardSettings": {
    }
}

Response samples

Content type
application/json
{
  • "name": "Mall Program",
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...",
  • "location": "Global",
  • "stores": [],
  • "renewalFee": true,
  • "renewalAmount": 20,
  • "giftCardEnabled": true,
  • "giftCardSettings": {
    }
}

Edit a program

Authorizations:
jwtAuth
path Parameters
programId
required
string
Request Body schema: application/json
required
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "name": "Mall Program",
  • "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...",
  • "location": "Global",
  • "stores": [],
  • "renewalFee": true,
  • "renewalAmount": 20,
  • "giftCardEnabled": true,
  • "giftCardSettings": {
    }
}

Delete a program

Authorizations:
jwtAuth
path Parameters
programId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": 4001,
  • "message": "Validation failed for one or more fields."
}